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.
Figure 1. C syntax of GIMAPI
invocation 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.