CEEENTRY macro— Generate a Language Environment-conforming prolog

CEEENTRY provides a Language Environment-conforming prolog. Code is generated in cooperation with the CEEPPA macro. (See CEEPPA macro — Generate a PPA for syntax.) The macro generates reentrant code.

You must use CEEENTRY in conjunction with the macros CEETERM, CEECAA, CEEDSA, and CEEPPA.

CEEENTRY assumes that the registers contain what is described in Register conventions for assembler main routines.

To call an assembler routine from an existing Fortran program, or to make a static call from OS/VS COBOL or VS COBOL II, CEEENTRY must specify NAB=NO and MAIN=NO.

Syntax

>>-name--CEEENTRY--+----------------+--+-----------------+------>
                   '-PPA=--label--,-'  '-AUTO=--value--,-'   

>--+------------------+--+-------------------+------------------>
   |       .-YES-.    |  |        .-YES-.    |   
   '-NAB=--+-NO--+--,-'  '-MAIN=--+-NO--+--,-'   

>--+----------------------+--+----------------------+----------->
   |           .-NO--.    |  |           .-YES-.    |   
   '-ENCLAVE=--+-YES-+--,-'  '-EXECOPS=--+-NO--+--,-'   

>--+-----------------------+--+---------------------+----------->
   '-PARMREG=--register--,-'  |          .-NO--.    |   
                              '-EXPORT=--+-YES-+--,-'   

>--+----------------------------------+------------------------->
   '-BASE=--+-register-----------+--,-'   
            |    .-,--------.    |        
            |    V          |    |        
            '-(----register-+--)-'        

>--+---------------------+--+--------------------+-------------->
   |         .-HOST-.    |  |         .-ANY-.    |   
   '-PLIST=--+-MVS--+--,-'  '-RMODE=--+-24--+--,-'   
             +-TSO--+                 '-31--'        
             +-CICS-+                                
             +-IMS--+                                
             '-OS---'                                

>--+-------------------+---------------------------------------><
   |         .-ANY---. |   
   '-AMODE=--+-24----+-'   
             +-31----+     
             '-ANY31-'     

name

The entry name (and the CSECT name, if this is the first call to CEEENTRY).

PPA=

The label of the corresponding PPA (Program Prolog Area) generated using the CEEPPA macro. If unspecified, the name “PPA” is used.

AUTO=

The total number of bytes (rounded up to a doubleword) used by prolog code for the DSA and local automatic variables that are to be allocated for the duration of this routine. If unspecified, the default is only the size of the DSA without any automatic variables. This default size is indicated by the label CEEDSASZ (the DSA mapping generated by the CEEDSA macro). See CEEDSA macro — Generate a DSA mapping for syntax).

NAB=

YES

Indicates that the previous save area has a NAB (next available byte) value; YES is the default. In general,

• If your routine is always called by a Language Environment-conforming assembler routine, specify NAB=YES.
• If your routine can be called by a non-Language Environment-conforming assembler routine, specify NAB=NO.

NO

Indicates that the previous save area may not contain the NAB. Code to find the NAB is generated. This parameter is ignored if MAIN=YES is specified. You must specify MAIN=NO and NAB=NO to call an assembler routine from an existing Fortran application, or to make a static call from OS/VS COBOL or VS COBOL II.

MAIN=

YES

Indicates that the Language Environment environment should be brought up. Designates this assembler routine as the main routine in the enclave. YES is the default. If you specify MAIN=YES, you cannot specify register 2 as the base register for the module. MAIN=YES is not supported under CICS® on releases earlier than CICS TS 3.1.

The following is accomplished by the macro invocation:

• The caller's registers (14 through 12) are saved in a DSA provided by the caller.
• The base register is set (see BASE= for more information).
• Register 12 is set with an address of CEECAA.
• Register 13 is set with an address of CEEDSA.
• PARMREG (Register 1 is the default) is set based on PLIST.
• All other registers are undefined.

NO

Designates this assembler routine as a subroutine in the enclave. NO should be specified when the Language Environment environment is already active and only prolog code is needed. You must specify NAB=NO in order to call an assembler routine from an existing Fortran application, or to make a static call from OS/VS COBOL or VS COBOL II.

The following is accomplished by the macro invocation:

• The caller's registers (14 through 12) are saved in a DSA provided by the caller.
• The base register is set (see BASE= for more information).
• Register 13 is set with an address of CEEDSA.
• PARMREG is set (see PARMREG.)
• All other registers are undefined.

ENCLAVE=

YES

Indicates that Language Environment should always create a nested enclave for this program. ENCLAVE=YES may only be specified when MAIN=YES. The use of ENCLAVE=YES will result in increased storage and CPU usage. Most applications will not need a new enclave; therefore ENCLAVE=NO should be used.

NO

Indicates that a new enclave is not needed for this program. If you do not specify a value, NO is assumed.

EXECOPS=

YES

Indicates that the main routines are to honor runtime options on the inbound parameter string. This option is applicable only when MAIN=YES is in effect for the routine. The EXECOPS setting is ignored if MAIN=NO is specified. If you do not specify a value, YES is assumed.

NO

Indicates that there are no runtime options in the inbound parameter string. Language Environment considers the entire inbound parameter string as program arguments, but does not attempt to process runtime options and remove them from the inbound parameter string.

PARMREG=

Specifies the register to hold the inbound parameters. If you do not specify a value, register 1 is assumed.

For MAIN=YES, the value in the PARMREG is determined by PLIST. For MAIN=NO and PARMREG=1 (PARMREG defaults to 1), register 1 is restored from the save area passed to the routine. When MAIN=NO and PARMREG is not equal to 1, register 1 is used to load the specified PARMREG. Then, register 1 is used for the CEEENTRY expansion.

EXPORT=

Indicates whether this entry point will be exported.

NO

This entry point can only be called from other routines that are link-edited into the same program object.

YES

This entry point will be marked as an exported DLL function. If you specify EXPORT=YES, then you must use the GOFF Assembler option.

If you want the exported name to be a long name and/or mixed case, follow the CEEENTRY macro with an ALIAS statement. For more details on DLLs, including full sample assembler DLL routines, see Building and using dynamic link libraries (DLLs).

For the entry point to be available as an exported DLL function, you must specify the DYNAM(DLL) binder option, and the resulting program object must reside in a PDSE.

BASE=

Establishes the register(s) that you specify here as the base register(s) for this module. If you do not specify a value, register 11 is assumed; register 12 cannot be used. When more than one register is specified, the registers must be separated by commas and enclosed in parentheses. The same register cannot be specified more than once.

PLIST=

Indicates that the main routines are to honor PLIST format on the inbound parameter string. This option is applicable only when MAIN=YES is in effect for the routine. The PLIST settings are ignored if MAIN=NO is specified. If you do not specify a value, HOST format is assumed.

The HOST format sets the specified PARMREG based on the environment in which the program is executing. For example, in an environment that assumes CEEENTRY defaults, register 1 is set equal to the address of a one word PLIST that contains the address of a field with a halfword-prefixed string of user parameters. To obtain the inbound parameter list as specified, use PLIST (OS).

RMODE=

Allows the specification of the modules CSECT RMODE setting. Valid settings for this option are ANY, 24 and 31. The default, if unspecified, is ANY.

AMODE=

Allows the specification of the modules CSECT AMODE setting. Valid settings for this option are 24, 31, ANY31, and ANY. The default, if unspecified, is ANY.