|
You can modify CEEBXITA to perform any function you need, but the
exit must have the following attributes after you modify it at installation:
- The user-supplied exit must be named CEEBXITA.
- The exit must be reentrant.
- The exit must be able to execute in AMODE(ANY) and RMODE(ANY).
- The installation-wide guidelines are as follows:
- 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.
- The application-specific guidelines are as follows:
- You must bind (link) the exit with your application.
- Use the sample customization job CEEWUXIT and CEEWCXIT to assist
with creating your exit.
If a user exit is modified, you are responsible for conforming
to the interface shown in Figure 1.
Rule: The modified user exit must be written in assembler.
Figure 1. Interface for 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 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 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 as follows:
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.
- 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
stop the entire TASK.
- ON
- Indicates that when you request an abend, an abend is issued to
stop the STEP.
This parameter is applicable only to z/OS; it
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
prior to 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 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 Language Environment is different
than under OS PL/I Version 2 Release
3.
|