CEEBINT high-level language user exit interface

Language Environment provides CEEBINT for enclave initialization. You can code CEEBINT in non-XPLINK C and C++, Fortran, PL/I, or Language Environment-conforming assembler. You cannot code CEEBINT as an XPLINK application. CEEBINT is not invoked for an XPLINK application. COBOL programs can use CEEBINT, but CEEBINT cannot be written in COBOL or be used to call COBOL programs.

CEEBINT is supported with POSIX(ON) and in a threaded environment. It is driven only on the initial thread.

You can modify CEEBINT to perform any function desired, although the exit must have the following attributes after you modify it:

The user exit must not be a main-designated routine. That is, it must not be a C or C++ main function, and OPTIONS(MAIN) must not be specified for PL/I applications.
CEEBINT must be linked with compiled code. If you do not provide an initialization user exit, an IBM-supplied default, which simply returns control to your application, is linked with the compiled code. When written in C++, CEEBINT must be linked with your application and it can only function as an application-specific user exit.
The exit cannot be written in COBOL.
When CEEBINT is written in C/C++, the following must be coded so that SMP/E can maintain the CSECT and properly link the intended user exit:
```
#pragma map(CEEBINT,"CEEBINT")
```
The exit should be coded so that it returns for all unknown function codes.
C or C++ constructs such as the exit(), abort(), raise(SIGTERM), and raise(SIGABRT) functions terminate the enclave.
A PL/I EXIT or STOP statement terminates the enclave.
Use the callable service IBMHKS to turn hooks on and off. For more information about IBMHKS, see PL/I for MVS & VM Programming Guide.
C or C++ functions such as exit(), abort(), raise(SIGTERM), and raise(SIGABRT) terminate the entire application as well as the user exit.

CEEBINT is invoked after the enclave has been established, after the Debug Tool initial command string has been processed, and before the invocation of compiled code. When invoked, it is passed a parameter list. The parameters are all fullwords and are defined as:

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 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 Language Environment

Function code (input)

A fullword binary integer

On entry: 1, indicating the exit is being driven for initialization
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 Language Environment and passed to subsequent user exits. It can be accessed from the main() function through the system programming facilities C __xusr() function.

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

Exit List Address (output)

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 compiler TEST option are executed. You can establish this exit by setting appropriate pointers (A_Exits to Exit_list to Hook_exit).

Figure 1. Exit_list and hook_exit control blocks

The exit_list contains the exit_llist_len and exit_list_hooks. It gains control when the hook_exit is executed. The hook_exit contains fields such as hook_exit_len.

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. Since 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 that it conforms to the following specifications:

0: Requests that the 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 CEEBXITA and CEEBINT

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