Assembler user exit interface
- The user-supplied exit must be named CEEBXITA.
- The exit must be reentrant.
- The exit must be capable of executing in AMODE(ANY) and RMODE(ANY).
- The exit must be relinked with the application after modification (if you want an application-specific user exit), or relinked with z/OS® Language Environment® initialization/termination routines after modification (if you want an installation-wide user exit).
If a user exit is modified, you are responsible for conforming to the interface shown in Figure 1. This user exit must be written in assembler.
- CEEAUE_LEN (input parameter)
- A fullword integer that specifies the total length of this control block. For z/OS Language Environment, the length is 48 bytes.
- CEEAUE_FUNC (input parameter)
- A fullword integer that specifies the function code. In z/OS Language
Environment,
the following function codes are supported:
- 1
- initialization of the first enclave within a process
- 2
- termination of the first enclave within a process
- 3
- nested enclave initialization
- 4
- nested enclave termination
- 5
- process termination
- CEEAUE_RETC (input/output parameter)
- A fullword integer that specifies the return or abend code.
CEEAUE_RETC has different meanings
depending on the flag CEEAUE_ABND:
- As an input parameter, this fullword is the enclave return code.
- As an output parameter, if the flag CEEAUE_ABND is on, this fullword is interpreted as an abend code that is used when an abend is issued. (This could be either an EXEC CICS ABEND or an SVC 13.)
- If the flag CEEAUE_ABND is off, this fullword is interpreted as the enclave return code that might have been modified by the exit.
See z/OS Language Environment Programming Guide for more information about how z/OS Language Environment computes return and reason codes.
- CEEAUE_RSNC (input/output parameter)
- A fullword integer that specifies the reason code for CEEAUE_RETC.
- As an input parameter, this fullword is the z/OS Language Environment return code modifier.
- As an output parameter, if the flag CEEAUE_ABND is on, CEEAUE_RETC is interpreted as an abend reason code that is used when an abend is issued. (This field is ignored when an EXEC CICS ABEND is issued.)
- If the flag CEEAUE_ABND is off, this fullword is the z/OS Language Environment return code modifier that might have been modified by the exit.
See z/OS Language Environment Programming Guide for more information about how z/OS Language Environment computes return and reason codes.
- CEEAUE_FLAGS (input/output parameter)
- Contains four flag bytes. CEEBXITA uses only the
first byte but reserves the remaining bytes. All unspecified bits
and bytes must be zero. The layout of these flags is shown in Figure 2.
Figure 2. CEEAUE_FLAGS format
Byte 0 (CEEAUE_FLAG1) has the following meaning:- CEEAUE_ABTERM (input parameter)
- When OFF, the enclave terminates normally (severity
0 or 1 condition).
When ON, the enclave terminates with the z/OS Language Environment return code modifier of 2 or greater. This could, for example, indicate that a condition of severity 2 or greater was raised that was unhandled.
- CEEAUE_ABND (output parameter)
- When OFF, the enclave terminates without an abend. CEEAUE_RETC and CEEAUE_RSNC are
placed
in register 15 and register 0 and returned to the
enclave creator.
When ON, the enclave terminates with an abend. Thus, CEEAUE_RETC and CEEAUE_RSNC are used by z/OS Language Environment in the invocation of the abend. While executing in CICS®, an EXEC CICS ABEND command is issued.
CEEAUE_RSNC is ignored under CICS. The TRAP option does not affect the setting of CEEAUE_ABND.
- CEEAUE_DUMP (output parameter)
- When OFF and you request an abend, an abend is issued without requesting a system dump. When ON and you request an abend, an abend is issued requesting a system dump.
- CEEAUE_STEPS (output parameter)
- When OFF and you request an abend, one is issued
to abend the entire task. When ON and you request an abend,
one is issued to abend the step.
Note: This fullword is ignored under CICS.
- CEEAUE-A-CC-PLIST (input/output parameter)
- A fullword pointer to the parameter address list of the application
program.
As an input parameter, this fullword contains the register 1 value passed to the main routine. The exit can modify this value, and the value is then passed to the main routine. If runtime options are present in the invocation command string, they are stripped off before the exit is called.
If the parameter inbound to the main routine is a character string, CEEAUE-A-CC-PLIST contains the address of a fullword address that points to a halfword prefixed string. If this string is altered by the user exit, the string must not be extended in place.
- CEEAUE_WORK (input parameter)
- Contains a fullword pointer to a 256-byte work area that the exit can use. On entry, it contains binary zeros and is doubleword-aligned. This area does not persist across exits.
- CEEAUE_OPTIONS (output parameter)
- On return, this field contains a fullword
pointer to the address of a halfword length
prefixed character string that contains runtime options. These options
are only processed for enclave initialization. When invoked for enclave
termination, this field is ignored.
These runtime options override all other sources of runtime options except those that are specified as non-overrideable.
Under CICS, the STACK runtime option cannot be modified using the assembler user exit.
- CEEAUE_USERWD (input/output parameter)
- Contains a fullword whose value is maintained without alteration and passed to every user exit. On entry to the enclave initialization user exit, it is zero. Thereafter, the value of the user word is not altered by z/OS Language Environment or any member libraries. The user exit can change the value of this field and z/OS Language Environment maintains this value. This allows a user exit to initialize the fullword and pass it to subsequent user exits.
- CEEAUE_A_AB_CODES (output parameter)
- During the initialization exit, this field contains the fullword
address of a table of abend codes that the z/OS Language
Environment
condition handler
percolates while in the (E)STAE exit. Therefore, the application
is not given the opportunity to field the abend. The table consists
of:
- A fullword count of the number of abend codes that are to be percolated
- A fullword for each of the particular abend codes that are to be percolated
The abend codes can be user abend codes or system abend codes. User abend codes are specified by F'uuu'. For example, if you wanted user abend 777 to be percolated, an F'777' would be coded. System abend codes are specified by X'00sss000'. Avoid specifying the values 0C0 through 0CF as 'sss'. Language Environment ignores values between OCO and OCF. No abend is percolated, and z/OS Language Environment condition handling semantics are in effect.
This function is not enabled under CICS.
- CEEAUE_FBCODE (input parameter)
- Contains the fullword address of the condition token with which the enclave terminated. If the enclave terminates normally (that is, not because of a condition), the condition token is zero.
- CEEAUE_PAGE (input/output parameter)
- Usage of this field is related to PL/I BASED variables that are allocated storage outside of AREAs. You can indicate whether storage should be allocated on a 4K-page boundary. You can specify the minimum number of bytes of storage that you want allocated. Your allocation request must be an exact multiple of 4K. The IBM®-supplied default setting for CEEAUE_PAGE is 32768 (32K).
If CEEAUE_PAGE is set to zero, PL/I BASED variables can be placed on other than 4K-page boundaries.
CEEAUE_PAGE is honored only during enclave initialization (that is, when CEEAUE_FUNC is 1 or 3).
The offset of CEEAUE_PAGE under z/OS Language Environment is different from the offset of IBMBXITA under OS PL/I Version 2 Release 3.