EXEC interface program exits XEIIN, XEIOUT, XEISPIN, and XEISPOUT

There are four global user exit points in the EXEC interface program:

XEIIN
Invoked before the execution of any EXEC CICS application programming interface (API) or system programming interface (SPI) command.
XEISPIN
Invoked before the execution of any EXEC CICS SPI command except:

The sequence is:

TRACE   -   XEIIN   -   XEISPIN   -   EDF   -   command
XEIOUT
Invoked after the execution of any EXEC CICS API or SPI command.
XEISPOUT
Invoked after the execution of any EXEC CICS SPI command except those listed for XEISPIN.

The sequence is:

command   -   EDF   -   XEISPOUT   -   XEIOUT   -   TRACE
Note:
Asynchronous processing of these exits may occur if the transaction is suspended (for example, during file I/O wait). This situation may also occur under CEDF because CEDF issues its own EXEC CICS commands between the application’s XEISPIN and XEISPOUT exits.

If, for example, the same GWA is shared between the XEIIN and XEIOUT exits, you must allow for the possibility of asynchronous processing, in order to ensure integrity of the data and to prevent unpredictable results.

On entry to the exits, the exit-specific parameter UEPARG contains the address of the command parameter list.

The command parameter list

The first parameter in the list points to a string of data known as argument 0. The other parameters point to the values specified for the parameters passed on the command.

Argument 0 begins with a 2-byte function code that identifies the command. (Function codes are documented in Appendix A of the CICS® Application Programming Reference manual and in Appendix B of the CICS System Programming Reference manual.) The function code is followed by a 2-byte field containing "existence bits" which indicate whether arguments are passed on the command. For example, consider the command:

EXEC CICS LINK PROGRAM(‘MYPROG’)

Here, argument 0 begins with the function code X'0E02' (LINK). Existence bit 1 is set, indicating that there is an argument 1 (namely, ‘MYPROG’).

The correspondence between command parameters (such as PROGRAM) and their positions and values in the parameter list (in this case, argument 1, ‘MYPROG’) can be deduced from the translated code for the particular command.

Important

Modifying CICS commands by tampering with argument 0 is not supported, and leads to unexpected errors or results.

For example, if an application program is written in assembler or PL/I and you modify argument 0, you will be writing to program storage (that is, storage occupied by the program itself), which could cause 0C4 abends. Furthermore, modifying argument 0 not only alters the CICS command for this execution of the command in the application program, it changes the CICS command in the virtual storage copy of the application program. This means that the next task to invoke the same copy of the program will also execute the modified command.

This particular example of the danger of tampering with argument 0 does not apply to COBOL or C application programs, but nevertheless you should not modify CICS commands for application programs written in any supported language.

Bypassing commands

An XEIIN or XEISPIN exit program can bypass execution of a command by setting the UERCBYP return code. If it does this, EDF is not invoked, but XEISPOUT, XEIOUT, and exit trace are invoked if they are active.

Bypassing an EXEC CICS command allows an exit program to replace the CICS function with its own processing, for example.

Before setting UERCBYP, your program should check the value pointed to by UEPPGM, to ensure that it is not bypassing an EXEC CICS command issued by CICS.

Exit XEIIN

When invoked
Before the execution of any EXEC CICS API or SPI command.
Exit-specific parameters
UEPARG
Address of the EXEC command parameter list.
UEPEXECB
Address of the system EIB.
UEPUSID
Address of the 8-character userid.
UEPPGM
Address of the 8-character application program name.
UEPLOAD
Address of the application program’s load-point.
UEPRSA
Address of the application’s register save area. This contains the contents of the registers at the point when the program issued the EXEC CICS command.
Return codes
UERCNORM
Continue processing.
UERCBYP
Bypass the execution of this command.
UERCPURG
Task purged during XPI call.
XPI calls
All can be used.

Exit XEISPIN

When invoked
Before the execution of any EXEC CICS SPI command except:
Exit-specific parameters
UEPARG
Address of the EXEC command parameter list.
UEPEXECB
Address of the system EIB.
UEPUSID
Address of the 8-character userid.
UEPPGM
Address of the 8-character application program name.
UEPLOAD
Address of the application program’s load-point.
UEPRSA
Address of the application’s register save area. This contains the contents of the registers at the point when the program issued the EXEC CICS command.
Return codes
UERCNORM
Continue processing.
UERCBYP
Bypass the execution of this command.
UERCPURG
Task purged during XPI call.
XPI calls
All can be used.

Exit XEIOUT

When invoked
After the execution of any EXEC CICS API or SPI command.
Exit-specific parameters
UEPARG
Address of the EXEC command parameter list.
UEPEXECB
Address of the system EIB.
UEPUSID
Address of the 8-character userid.
UEPPGM
Address of the 8-character application program name.
UEPLOAD
Address of the application program’s load-point.
UEPRSA
Address of the application’s register save area. This contains the contents of the registers at the point when the program issued the EXEC CICS command.
Return codes
UERCNORM
Continue processing.
UERCPURG
Task purged during XPI call.
XPI calls
All can be used.

Exit XEISPOUT

When invoked
After the execution of any EXEC CICS SPI command except:
Exit-specific parameters
UEPARG
Address of the EXEC command parameter list.
UEPEXECB
Address of the system EIB.
UEPUSID
Address of the 8-character userid.
UEPPGM
Address of the 8-character application program name.
UEPLOAD
Address of the application program’s load-point.
UEPRSA
Address of the application’s register save area. This contains the contents of the registers at the point when the program issued the EXEC CICS command.
Return codes
UERCNORM
Continue processing.
UERCPURG
Task purged during XPI call.
XPI calls
All can be used.

Related concepts
Overview -- what is a global user exit?
Overview of the XPI
Global user exit XPI examples, showing the use of storage
Related tasks
Writing global user exit programs
Making an XPI call
Related reference
List of global user exit points
The XPI functions
[[ Contents Previous Page | Next Page Index ]]