Programming in C

For GIMAPI to be invoked from a C/370 program, GIMAPI must first be loaded into storage. The calling program must identify the parameter linkage as standard OS linkage and must declare the routine. Figure 1 shows the statements to load and unload the module, the #pragma statement that identifies the linkage, the function declaration, and the calling syntax.

  typedef void APIPGM();
  typedef void CFUNC();
  #pragma linkage(APIPGM,OS)
  ⋮
  APIPGM * gimapi;
  gimapi = (APIPGM *) fetch("GIMAPI");
  ⋮
  (*gimapi) (apicmd,&parmptr,&outptr,language,&rc,&cc,&msgbuff);
  ⋮
  release((CFUNC*) gimapi)

The FETCH must be done once, then GIMAPI can be invoked any number of times before it is released. The release function requires a pointer to a C function as its parameter. APIPGM becomes an OS program. The typedef of CFUNC is used to cast the gimapi parameter so the program compiles correctly.

apicmd

The apicmd parameter is a string of length 8 that contains the name of the command to be passed to GIMAPI.

&parmptr

A qparm variable is declared of type QUERY_PARMS. The parmptr pointer variable is set to the address of the query parameter structure. The address of the pointer variable is passed to GIMAPI.

&outptr

The outptr variable is a pointer variable that will be set to the address of the beginning of storage containing the output of the command processing. The address of outptr is passed to GIMAPI.

language

A character string of length 3 to indicate the language to use for messaging by GIMAPI. Valid values are ENU and JPN.

&rc

Address of a variable defined as long to be set to the command's return code by GIMAPI.

&cc

Address of a variable defined as long to be set to the command's condition code by GIMAPI.

&msgbuff

The msgbuff variable is a pointer variable that is set to the head of a linked list of messages that could be created by GIMAPI processing. The elements to the link list are ITEM_LIST structures. The address of the pointer variable is passed to GIMAPI.