High level language user exit interface

z/OS® Language Environment® provides CEEBINT, an HLL user exit, for enclave initialization. You can code CEEBINT in z/OS XL C, PL/I, or z/OS XL C++ (subject to the restrictions in Order of processing of user exits), or z/OS Language Environment-conforming assembler. The HLL user exit cannot be written in COBOL. COBOL programmers can use an HLL exit written in z/OS XL C, PL/I, z/OS Language Environment-conforming assembler, z/OS XL C++ (again, subject to the restrictions in Order of processing of user exits), or default to the IBM-supplied default HLL user exit.

The HLL enclave initialization exit is invoked after the enclave has been established, after the Debug Tool initial command string has been processed, and prior to the invocation of compiled code. When invoked, it is passed a parameter list that conforms to the z/OS Language Environment definition. The parameters are all fullwords and are defined as follows:

Number of arguments in parameter list (input)

A fullword binary integer.

On entry: Contains 7.
On exit: Not applicable.

Return code (output)

A fullword binary integer.

On entry: 0.
On exit: Able to be set by the exit, but not interrogated by z/OS Language Environment.

Reason code (output)

A fullword binary integer.

On entry: 0
On exit: Able to be set by the exit, but not interrogated by z/OS Language Environment.

Function code (input)

A fullword binary integer.

On entry: 1, indicating the exit is being driven for initialization.
On exit: Not applicable.

Address of the main program entry point (input)

A fullword binary address.

On entry: The address of the routine that gains control first.
On exit: Not applicable.

User word (input/output)

A fullword binary integer.

On entry: Value of the user word (CEEAUE_USERWD) as set by the assembler user exit.
On exit: The value set by the user exit, maintained by z/OS Language Environment and passed to subsequent user exits.

Exit List Address (output)

A fullword binary integer reserved for future use. This allows the establishment of one or more user exits when the enclave user exit sets this field to a list of user exits. Currently, only one user exit is supported in z/OS Language Environment.

A_Exits

The address of the exit list control block, Exit_list.

On entry: 0.
On exit: 0, unless you establish a hook exit, in which case you would set this pointer and fill in relevant control blocks. The control blocks for Exit_list and Hook_exit are shown in the following figure.

As supplied, CEEBINT has only one exit defined that you can establish: the hook exit described by the Hook_exit control block. This exit gains control when hooks generated by the PL/I compile-time TEST option are executed. You can establish this exit by setting appropriate pointers (A_Exits to Exit_list to Hook_exit). Figure 1 illustrates the Exit_list and Hook_exit control blocks.

Figure 1. Exit_list and hook_exit control blocks

The control block Exit_list exit contains the following fields:

Exit_list_len: The length of the control block. It must be 1.
Exit_list_hooks: The address of the Hook_exit control block.

The control block for the hook exit must contain the following fields:

Hook_exit_len

The length of the control block.

Hook_exit_rtn

The address of a routine you want invoked for the exit. When the routine is invoked, it is passed the address of this control block. Because this routine is invoked only if the address you specify is nonzero, you can turn the exit on and off.

Hook_exit_fnccode

The function code with which the exit is invoked. This is always 1.

Hook_exit_retcode

The return code set by the exit. You must ensure it conforms to the following specifications:

0: Requests that Debug Tool be invoked next
4: Requests that the program resume immediately
16: Requests that the program be terminated

Hook_exit_rsncode

The reason code set by the exit. This is always zero.

Hook_exit_userwd

The user word passed to the user exits.

Hook_exit_ptr

An exit-specific user word.

Hook_exit_reserved

Reserved.

Hook_exit_dsa

The contents of register 13 when the hook was executed.

Hook_exit_addr

The address of the hook instruction executed.