CELQCALL macro — Call a Language Environment-conforming AMODE 64 routine

CELQCALL can be used to pass control from an AMODE 64 assembler program to another AMODE 64 control section at a specified entry point. It is meant to be used with the CELQPRLG prolog and CELQEPLG macros. The target of CELQCALL can be resolved either statically (bound with the same program object) or dynamically (imported from a DLL).

The CELQCALL macro does not generate any return codes. Return information may be placed in GPR 3 (and possibly GPRs 2 and 1, or the floating point registers) by the called program, as specified by 64-bit XPLINK linkage conventions. For more information, refer to z/OS Language Environment Vendor Interfaces.

GPRs 0, 1, 2, 3, 5, 6, and 7 are not preserved by this macro.


Syntax

>>-+-------+--CELQCALL--entry-name--+--------------------+------>
   '-label-'                        '-, (--parm1--, ...)-'   

>--, -WORKREG=--reg--------------------------------------------><

label: Optional label 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 parameters to be passed to the called program. The parameters are copied to the argument area in the calling program's DSA, and then GPRs 1, 2, and 3 are loaded with the first three words of this argument area. Sufficient space must be reserved in the caller's argument area to contain the largest possible parameter list. A minimum of 8 words (32 bytes) must always be allocated for the argument area. Use the DSASIZE= parameter on the CELQPRLG prolog macro to ensure the calling program's DSA is large enough.
At this time, the CELQCALL macro only supports passing parameters by reference.
WORKREG=: A numeric value representing a general purpose register between 8 and 15, inclusive, that can be used as a work register by this macro. Its contents will not be preserved.

Usage notes:

This macro requires that the calling routine's 64-bit XPLINK environment address is in register 5 (as it was when the routine was first invoked).
This macro requires that a PSECT was defined by the CELQPRLG prolog macro.
This macro requires the GOFF assembler option.
This macro requires the binder to bind, and the RENT and DYNAM(DLL) binder options. You will also need the CASE(MIXED) binder option if the entry-name is mixed case.
The output from the binder must be a PM4 (or higher) format program object, and therefore must reside in either a PDSE or the HFS.

The following AMODE 64 assembler example shows a call to an AMODE 64 routine named Xif1 where no parameters are passed.

ADLA6IF1 CELQPRLG DSASIZE=DSASZ,PSECT=ADLA6IFP
*
R3       EQU   3             RETURN VALUE
*
         WTO   'ADLA6IF1: Calling imported AMODE 64 function Xif1',    X
               ROUTCDE=11
*
         CELQCALL Xif1,WORKREG=10
*
         SGR   R3,R3
RETURN   DS   0H
         CELQEPLG
*
         LTORG
CEEDSAHP CEEDSA SECTYPE=XPLINK
MINARGA  DS    8F
DSASZ    EQU *-CEEDSAHP_FIXED
         END      ADLA6IF1

This is an example of AMODE 64 assembler code calling a function with 5 parameters.

ADLA6IF7 CELQPRLG DSASIZE=DSASZ,PSECT=ADLA6IFP
*
R3       EQU   3             RETURN VALUE
*
         WTO   'ADLA6IF7: Calling imported AMODE 64 function Xif7 passiX
               ng parmeters (15,33,"Hello world",45.2,9)',             X
               ROUTCDE=11
*
         CELQCALL Xif7,(PARM1,PARM2,PARM3,PARM4,PARM5),WORKREG=10
*
         SGR   R3,R3
RETURN   DS   0H
         CELQEPLG
*
         LTORG
PARM1    DC    FL4'15'
PARM2    DC    FL2'33'
PARM3    DC    C'Hello world'
         DC    X'00'
PARM4    DC    D'45.2'
PARM5    DC    FL4'9'
CEEDSAHP CEEDSA SECTYPE=XPLINK
ARGAREA  DS    10F
DSASZ    EQU *-CEEDSAHP_FIXED
         END      ADLA6IF7