CEEPCALL macro — Pass control to control sections at specified entry points

The CEEPCALL macro passes control to a control section at a specified entry point. The target of CEEPCALL can be resolved either statically (link-edited with the same program object) or dynamically (imported from a DLL). The only required positional parameter is the name of the called entry point. This name is case-sensitive, and can be up to 255 characters in length. The optional parameter list will be pointed to by General Purpose Register (GPR) 1.

Since only REENTRANT Assembler code is supported by this macro, it must be specified as a combination of LIST and EXECUTE forms so that the parameter list can be built in automatic (that is, stack) storage.

The CEEPCALL macro does not generate any return codes. A return code may be placed in GPR 15 by the called program.

GPRs 1, 14, and 15 are not preserved by this macro.

Read syntax diagramSkip visual syntax diagram
Syntax

>>-+-------+--CEEPCALL--+-----------------------------+--,--MF=L-><
   '-label-'            '-, (--parm1--, ...)--+-----+-'            
                                              '-,VL-'              

or

Read syntax diagramSkip visual syntax diagram
Syntax

>>-+-------+--CEEPCALL--entry-name--+-----------------------------+--,--MF=(E,--prob_addr--)-><
   '-label-'                        '-, (--parm1--, ...)--+-----+-'                            
                                                          '-,VL-'                              
label
Optional symbol beginning in column 1.
entry-name
Specifies the entry name of the program to be given control. This entry name can reside in the same program object, or can be an exported DLL function.
(parm1, ...)
One or more optional parameters to be passed to the called program, separated by commas. In the list form, these are specified as A-type addresses, and in the execute form are RX-type addresses or specified as registers (2) - (12).

To create the parameter list, the calling program creates a list of addresses of each parameter in the order designated. In the execute form of the macro, GPR 1 contains the address of the parameter list when the program receives control. (If no parameters are coded, GPR 1 is not altered.) See Figure 2.

VL
Code VL only if the called program can be passed a variable number of parameters. VL causes the high-order bit of the last address parameter to be set to 1; the bit can be checked to find the end of the list.
MF=L
Creates the list form of the CEEPCALL macro to construct a nonexecutable problem program parameter list. This list form generates only ADCONs of the address parameters. You should refer to this problem program parameter list in the execute form of a CEEPCALL macro.
MF=(E,prob_addr)
Creates the execute form of the CEEPCALL macro, which can refer to and modify a remote problem program parameter list. Only executable instructions and a function descriptor representing the entry point are generated.
Usage notes:
  1. This macro requires the GOFF Assembler option
  2. This macro requires the binder to link edit, and the RENT and DYNAM(DLL) binder options. You also need the CASE(MIXED) binder option if the entry-name is mixed case.
  3. The output from the binder must be a PM3 (or higher) format program object, and therefore must reside in either a PDSE or a UNIX file system.

For more information about DLLs, including full sample assembler DLL routines, see Building and using dynamic link libraries (DLLs). The following example illustrates an invocation of the CEEPCALL macro to call the routine named Bif1 with no parameters:

Figure 1. Example calling routine named Bif5 with no parameters:
DLLAPPL  CEEENTRY MAIN=YES,PPA=DLLPPA
*        Symbolic Register Definitions and Usage
R15      EQU   15            Entry point address
*
        CEEPCALL Bif1,MF=(E,)
*
         SR    R15,R15
RETURN   DS   0H
         CEETERM  RC=(R15),MODIFIER=0
*
DLLPPA   CEEPPA
         LTORG
         CEEDSA
         CEECAA
         END      DLLAPPL

The following example illustrates an invocation of the CEEPCALL macro to call the routine named Bif5 passing 5 integer parameters:

Figure 2. Example calling routine named Bif5 passing 5 integer parameters:
DLLAPPL  CEEENTRY MAIN=YES,PPA=DLLPPA,AUTO=AUTOSZ
*        Symbolic Register Definitions and Usage
R15      EQU   15            Entry point address
*
THECALL  CEEPCALL Bif5,(PARM1,PARM2,PARM3,PARM4,PARM5),VL,MF=(E,PARMS)
*
         SR    R15,R15
RETURN   DS   0H
         CEETERM  RC=(R15),MODIFIER=0
*
PARM1    DC    A(15)
PARM2    DC    A(33)
PARM3    DC    A(45)
PARM4    DC    A(57)
PARM5    DC    A(99)
DLLPPA   CEEPPA
         LTORG
         CEEDSA
PARMS    CEEPCALL ,(0,0,0,0,0),MF=L
AUTOEND  DS    0D
AUTOSZ   EQU   AUTOEND-CEEDSA
         CEECAA
         END      DLLAPPL
Parent topic: Assembler macros