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
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
formatByte 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.