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.
Usage notes: - The CEEENTRY macro automatically sets the module to AMODE ANY
and RMODE ANY. Therefore, when converting to Language Environment-conforming assembler,
if data management macros had been coded using 24-bit addressing mode,
they should be changed to use 31-bit addressing mode (see z/OS DFSMS Macro Instructions for Data Sets). If it is not possible
to change all the modules making up the program to use 31-bit addressing
mode (and none of the modules are already set to RMODE 24), then it will be
necessary to use the RMODE=24 CEEENTRY option. Alternatively, the
module can be set to RMODE 24 during the link-edit process. This
is done by specifying the link-edit RMODE option on the invocation PARM
or the SETOPT control statement.
- Unless otherwise indicated, no register values should be expected
to remain unchanged after the code generated by CEEENTRY has executed.
- When more than one CEEENTRY macro invocation occurs in an assembly,
it is the programmer's responsibility to code DROP statements for
the base registers set up by the previous invocation of the CEEENTRY macro.