Guidelines for using CEEBXITA

Installation-wide:

You must bind (link) the exit with the appropriate Language Environment® initialization/termination routines after modification.
Use the sample customization jobs CEEWDXIT and CEEWCXIT to assist with creating and binding (linking) your exit with Language Environment initialization/termination routines.
See the section on changing the assembler language user exit in z/OS Language Environment Customization for more details.

Application-specific:

You must bind (link) the exit with your application.
Use the sample job CEEWUXIT to assist with creating your exit.
See the section on changing the assembler language user exits in z/OS Language Environment Customization for more details.

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. You cannot code CEEBXITA as an XPLINK application. However, since CEEBXITA is called directly by Language Environment and not the application, a non-XPLINK CEEBXITA can be statically bound in the same program object with an XPLINK application.

Figure 1. Interface for the CEEBXITA assembler user exit

The interface for the CEEBXITA assembler user exit contains a list of keywords such as CEEAUE_EN (the input parameter).

When the user exit is called, register 1 points to a word that contains the address of the CEEAUE control block. The high-order bit is on.

The CEEAUE control block contains the following fullwords:

CEEAUE_LEN (input parameter)

A fullword integer that specifies the total length of this control block. For Language Environment, the length is 48 bytes.

CEEAUE_FUNC (input parameter)

A fullword integer that specifies the function code. Language Environment supports the following function codes:

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.

The user exit should ignore function codes other than those numbered from 1 through 5.

CEEAUE_RETC (input/output parameter)

A fullword integer that specifies the return or abend code. CEEAUE_RETC has different meanings, depending on CEEAUE_ABND:

If the flag CEEAUE_ABND (see below) is off, this fullword is interpreted as the Language Environment return code placed in register 15.
If the flag CEEAUE_ABND is on, CEEAUE_RETC is interpreted as an abend code used when an abend is issued. (This could be either an EXEC CICS® ABEND or an SVC13.)

CEEAUE_RSNC (input/output parameter)

A fullword integer that specifies the reason code for CEEAUE_RETC:

If the flag CEEAUE_ABND (see below) is off, this word is interpreted as the Language Environment reason code placed in register 0.
If the flag CEEAUE_ABND is on, CEEAUE_RETC is interpreted as an abend reason code used when an abend is issued.

This field is ignored when an EXEC CICS ABEND is issued.

CEEAUE_FLAGS

Contains four 1-byte flags. CEEBXITA uses only the first byte but reserves the remaining flags. All unspecified bits and bytes must be 0. The layout of these flags is shown in Figure 2:

Figure 2. CEEAUE_FLAGS format

Byte 0
          x... .... CEEAUE_ABTERM
          0... .... Normal termination
          1... .... Abnormal termination
          .x.. .... CEEAUE_ABND
          .0.. .... Terminate with CEEAUE_RETC
          .1.. .... ABEND with CEEAUE_RETC and CEEAUE_RSNC given
          ..x. .... CEEAUE_DUMP
          ..0. .... If CEEAUE_ABND=0, ABEND with no dump
          ..1. .... If CEEAUE_ABND=1, ABEND with a dump
          ...x .... CEEAUE_STEPS
          ...0 .... ABEND the task
          ...1 .... ABEND the step
          .... 0000 Reserved (must be zero)
Byte 1
          0000 0000 Reserved for future use
Byte 2
          0000 0000 Reserved for future use
Byte 3
          0000 0000 Reserved for future use

Byte 0 (CEEAUE_FLAG1) has the following meaning:

CEEAUE_ABTERM (input parameter)

OFF: Indicates that the enclave is terminating normally (severity 0 or 1 condition).
ON: Indicates that the enclave is terminating with an Language Environment return code modifier of 2 or greater. This could, for example, indicate that a severity 2 or greater condition was raised but not handled.

CEEAUE_ABND (input/output parameter)

OFF: Indicates that the enclave should terminate without an abend being issued. Thus, CEEAUE_RETC and CEEAUE_RSNC are placed into register 15 and register 0 and returned to the enclave creator.
ON: Indicates that the enclave terminates with an abend. Thus, CEEAUE_RETC and CEEAUE_RSNC are used by Language Environment in the invocation of the abend. During running in CICS, an EXEC CICS ABEND command is issued.

The TRAP runtime option does not affect the setting of CEEAUE_ABND.

When the ABTERMENC(ABEND) runtime option is specified, the enclave always terminates with an abend when there is an unhandled condition of severity 2 or greater, regardless of the setting of the CEEAUE_ABND flag. See Termination behavior for unhandled conditions for a detailed explanation of how the CEEAUE_ABND parameter can affect the behavior of the ABTERMENC runtime option.

CEEAUE_DUMP (output parameter)

OFF: Indicates that when you request an abend, an abend is issued without requesting a dump.
ON: Indicates that when you request an abend, an abend requesting a dump is issued.

CEEAUE_STEPS (output parameter)

OFF: Indicates that when you request an abend, an abend is issued to abend the entire TASK.
ON: Indicates that when you request an abend, an abend is issued to abend the STEP.

This parameter is ignored under CICS.

CEEAUE_A_CC_PLIST (input/output parameter)

A fullword pointer to the parameter address list of the application program.

If the parameter is not a character string, CEEAUE_A_CC_PLIST contains the register 1 value as passed by the calling program or operating system at the time of program entry.

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_A_WORK (input parameter)

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_A_OPTIONS (output parameter)

Upon return, this field contains a fullword pointer to the address of a halfword-length prefixed character string that contains runtime options. These options are honored only during the initialization of an enclave. 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 NONOVR.

Under CICS, the STACK runtime option cannot be modified with the assembler user exit.

CEEAUE_USERWD (input/output parameter)

A fullword whose value is maintained without alteration and passed to every user exit. Upon entry to the enclave initialization user exit, it is zero. Thereafter, the value of the user word is not altered by Language Environment or any member libraries. The user exit might change the value of this field, and Language Environment maintains that value. This allows the user exit to acquire a work area, initialize it, and pass it to subsequent user exits. The work area might be freed by the termination user exit.

CEEAUE_A_AB_CODES (output parameter)

During the initialization exit, this field contains a fullword address of a table of abend codes that the Language Environment condition handler percolates while in the (E)STAE exit. Therefore, the application does not have the chance to address the abend. This table is honored before shunt routines. 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 might be either user abend codes or system abend codes. User abend codes are specified by F'uuu'. For example, if you want to percolate user ABEND 777, a F'777' would be coded. System abend codes are specified by X'00sss000'.

This parameter is not enabled under CICS.

CEEAUE_FBCODE (input parameter)

Contains a fullword address of the condition token with which the enclave terminated. If the enclave terminates normally (that is, not due to a condition), the condition token is zero.

CEEAUE_PAGE (input parameter)

This parameter indicates whether PL/I BASED variables that are allocated storage outside of AREAs are allocated on a 4K-page boundary. You can specify in the field the minimum number of bytes of storage that must be allocated. Your allocation request must be an exact multiple of 4 KB.

The IBM-supplied default setting for CEEAUE_PAGE is 32768 (32 KB).

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 Language Environment is different than under OS PL/I Version 2 Release 3.