Functions of Grapnel API

Functions defined in grapnel.h: nothing...

Functions defined in grapnel_srv.h:

Functions defined in grapnel_cl.h: Functions defined in ddstuff.h Functions defined in ddstuff_srv.h Functions defined in ddstuff_cl.h

Functions defined in grapnel.h

Functions defined in grapnel_srv.h

char *grp_version(int *High, int *Low, int *PatchLevel)

This function can be used to get version number information of Grapnel Library. Output parameters are filled with high version number (High), low version number (Low), and patch level (PatchLevel). return value of this function is a pointer to a string which contains version numbers separated by periods. For example, if High is 0, Low is 24, and PatchLevel is 5, then the returned string is 0.24.5.

int grp_create_proc(struct TProcessInfo pinf, int flag, int argc, char *argv[])

used in server process to create a process. Name of the process and other information about the process is must be specified in the pinf structure. Flag is the spawning flag of the pvm_spawn() call, this can be used to launch the process via a debugger, such as xdbx. In this case, this paramter can be GRP_PcDebug, else GRP_PcDefault should be used. argc is and number of parameters specified in argv array to pass to the process. Return value of this function is the identification number of the created process, or an error code (<0) if process creation is failed.

int grp_stop_process(int tid)

This function stops the process specified by the tid parameter which must be the identification number of the process. If the process stopped successfully, the return value is TRUE, else it is FALSE.

int grp_start_server(void)

Used in the server program to take administrative actions before the server task starts its normal operations. This function returns TRUE if pvm system is running or FALSE if it is not.

void grp_create_channel(TProcessInfo src, TProcessInfo dest, int msgtag)

Creates a point-to-point channel and initializes its data structure. Can only be used in the server program. src and dest hold information about the source and the destination processes. msgtag is used to identify the channel. This is an arbitrary number, which is specified by the programmer. It must be unique.

void grp_report_channel(int msgtag, char *fromproc, int fromSID, int fromType, char *toproc, int toSID, int toType)

Internal function to report data of channel to the event file. It is an empty function in non-instrumented version of Grapnel Library

void grp_server(void)

This function is used in the server program after the process and channel creation phase. This function enters to an endless loop and scans the GRP processes and services their I/O requests. It also keep tracks on the number of alive processes and if this number reaches zero the function returns.
<-- grapnel_cl.c -->

Functions defined in grapnel_cl.h

void grp_start(void)

Prolog function which must be called prior to any operation in a GRP process.

void grp_init_channel(struct Tchannel *ch, int nuof_channs)

Initializes the channel ch. This funciton should be called in a GRP process to set up the process channels. The subsequent initialization calls must correspond to the grp_create_channel() calls in the server process. ch parameter points to the array of channel structures to be initialized and nuof_channs says how many elements the array has.

int grp_BeginBlock(int Type, int iID)

This function is used in GRP processes to take service actions at the beginning of program blocks.

int grp_nrecv(int tid, int msgtag, char type)

For internal use only!

Receives a value from a process specified by the tid and with a msgtag message tag.

int grp_pre_send(struct Tchannel * ch, int magic)

This function is used in GRP processes to prepare receiving of data through the channel ch. magic parameter defines how many additional, administrative information will be sent with the message and it specifies if the communication is blocked or not. Value of this parameter can be built using bitwise or (|) and bitwise and (&) operations between predefined constants.

void grp_pack(void *data, int n, int type)

Packing data to the sending buffer before send operation. Address of the data must be given in data parameter, number of data (if it is an array, the number of items) in the n parameter, and type of the data in the type parameter (it can be BYTE, DOUBLE, FLOAT, INT, LONG, STR). This function can be called more then once before grp_post_send().

int grp_post_send(struct Tchannel * ch, int magic)

In actual version of the API, this function must be used after grp_pre_send() and grp_pack() functions to send prepared message to the other process. The ch parameter identifies the communication channel. magic parameter is used to specify if the communication is blocked or not. See MagicXXXX constants.

int *grp_pre_mcast(struct Tchannel *ch, int *ch_no, int type)

Preparing multicast operation. ch parameter is an array of channel structures, data will be multicasted through these channels. An extra item required in the array after the last valid item with 0 in the msgtag field of the channel structure. The function places valid number of channels in the output parameter ch_no. This function allocates memory for an array and puts identification numbers of the destination processes into it and returns the address of the array. grp_post_mcast() function must be called to deallocate this memory area.

void grp_post_mcast(int *mcast, int ch_no)

Multicasting data to a set of tasks. This operation must be prepared with grp_pre_mcast() function. First parameter (mcast) must be the return value of the grp_pre_mcast() call and second one (ch_no) is the output parameter (ch_no) of the grp_pre_mcast(). This function deallocates memory area allocated temporarily for multicats operation by the grp_pre_mcast() function.

int grp_mcast(struct Tchannel *ch, void *data, int type)

This function is obsolete!

Multicasts via the specified channels. The ch parameter points to a list of channels where the msgtag field of the last item is zero, indicating the end of the list. Only non-blocking multicast is supported.

int grp_fopen(char *name, char *mode)

Open a file to read and/or write. File is opened on host where the server process is running. name is name of the file to open. The name is relative to actual directory where the server process has been started up. mode parameter can be "r", "w", "a", "r+", "w+", or "a+" same as you can use with fopen function. Return value is an identification number which you can use later to identify the file in file operations for example grp_fprint.

int grp_fclose(int fd)

Close file identified by fd parameter. It must be a return value of a previous call of grp_fopen function. If you forget to close opened files and the client process exits then the opened files remain opened until the server process exits.

void grp_fprintf(int fd, char *format, ...)

Same as grp_printf function but you can specify the file with parameter fd which you are going to write to.

void grp_printf(char *format, ...)

Sends a string to the server which prints it on the console. Parameters of this function are same as printf() function's. Note that length of the formatted string is limited to STR_LEN.

void grp_scanf(char *msg, void *data, int type)

Enters a data from the keyboard and stores it in the data variable. A promt message can be specified in the msg parameter. The data type to be scanned is specified in the same way as in the grp_pack() call.

void grp_fatal(char *format, ...)

This function is similar to grp_printf, you can use same parameters. It sends formatted string to server program and it prints it out to standard error output. After this, the client process exits.

int grp_pre_recv(struct Tchannel * ch, int *magic)

Receiving a message from a remote task using ch channel. magic parameter will be filled with "magic" number received in the message which specifies if communication is blocked or not. If it blocked, reply is sent back to the sender process.

Return value: magic number (same as output value of the magic parameter).

void grp_unpack(void *data, int no, int type)

Unpacking data from message received by the grp_pre_recv() function. This function can be called more than once to pick up data packed to the message by the grp_pack() function calls. data parameter must point to a memory area where the unpacked data will be copied to. no specifies number of data with the same type to unpack, and type the type of the data.

int grp_post_recv(struct Tchannel * ch)

Normally this function is called after every data is unpacked from received message. In actual version, it does nothing.

int grp_pre_mrecv(struct Tchannel *ch, int *which)

Alternative receive operation. Channels to source tasks must be in array ch. Last item in this array should have 0 as value of msgtag field to indicate the end of the channel list. which output parameter will contain port ID of the port where the message is received through, this value is returned by the function too.

int grp_post_mrecv(struct Tchannel *ch, int *which, int block_send)

This function can be called after grp_pre_mrecv() function with same parameters and in actual version of Grapnel Library, this function does nothing.

void grp_exit(int code)

This function must be called as last operation in a Grapnel process. This reports to the server that the process has terminated with exit code code.

Functions defined in ddstuff.h

char *NewString(char *string)

This function allocates memory area to store string, cpoies actual parameter to the newly allocated area and returns the address of the new string. Strings made by this function can be removed by the DisposeString() function.

void DisposeString(char *str)

This function disposes memory area allocated by the NewString() function to store a string. The paramter should be the value returned by the NewString() function.

Functions defined in ddstuff_srv.h

struct TProcessInfo *grp_pinfbyname(struct TProcessInfo *pinfs, char *name)

This function can be used to search for information about a process which has name name. Search is performed in the pinfs array of TProcessInfo structures. If requested process is not found, NULL will be returned.

struct TProcessInfo *grp_pinfbytid(struct TProcessInfo *pinfs, int tid)

This function can be used to search for information about a process which has task ID tid. Search is performed in the pinfs array of TProcessInfo structures. If requested process is not found, NULL will be returned.

int ReadMapFile(struct TProcessInfo pinfs[], char *AppName)

This function is used by the server process to read map file before process creation phase and place mapping instructions in the pinfs array which is a global array of the server process used to store information about processes. Mapping file describes which cpu resource, or host the processes must be started on. Format of the mapping file is simple. First line contains a number which tells how many rules are placed in the file. Following lines contains rules. Every rule has two items, first is process name and the sendond is the host (or cpu resource) name. For example: 
$ cat buffer.map
3
Buffer    leila

Producer  sun2
Consumer
  indy
$
White spaces (including new lines and empty lines) are ignored by this function. Rules do not have to reside on one line, they can occupy more lines. Mapping file shoud be in the directory pointed by the OBJDIR environment variable and name of the file must be same as the name of the application (passed in AppName parameter) plus .map suffix. If OBJDIR variable is undefined, ReadMapFile tries to open mapping file in current directory. If the server process is started with -V flag this function reports found and succesfully read rules and at the end of the function it reports the summary: how many rules are read and how many used. If something goes wrong, the function continues its work but returns FALSE, otherwise the return value is TRUE. Server process ignores return value of this function because the application still be executable despite this function fails.

void Init(int argc, char *argv[], char *VerGrp2c, char *Headers)

This function is used in the server process to analyse the command line parameters. Recognized options are follows:
-d
Set Debug flag to TRUE. Server program will use debugging facilities.
-v
Print out version number information about grp2c program which was used to generate source code of the server program, Grapnel Library, DDstuff Library, and installed header files. Parameter VerGrp2c is printed as version number of the grp2c program and Headers as version number of installed header files. They must be passed from server program.
-f
Set Force flag to TRUE. Server program will skip version checking. This option has an other effect as well. If the server process has unable to start all processes and some of them still unstarted, the server process stops processes that are started successfully and exits. Using this option the server process will not stop but will continue to work.
-m
Set SkipMap flag to TRUE. Server program will not read mapping file and will start every process on default cpu resource (chosen by the target system).
-V
Set Verbose flag to TRUE. Grapnel API functions will print out what are they doing.
-t value
Set TimeLimit variable to value. When this option is used and the specified time is elapsed, the server stops every processes and exits.
-n
In normal case the Grapnel Programs are calling administrative functions from GRED library to communicate with Graphical Editor to animate execution and make other visual effects during the execution. If the application is started by hand instead of GRED program, it does not required to make these function calls. Using -n option turns off GRED library calls.
-h
The server process prints out a short description of its options and exits.
-p
Stop processing parameters. Remaining parameters are not checked. Parameters before -p (and -p itself) are not passed to processes.
-T value
This option can be used to reduce verbosity of Tape event generation. It sets value of TapeLevel variable. If level value is 0 (default level) then every Tape events are generated by API functions. If the value is 1 then events that signs beginning of programming blocks (graphical items) are not generated. Greater values can be used in the future to skip more kind of events.
Back to Grapnel Compiler