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

There are four global user exit points in the EXEC interface program that you can use before or after an API or SPI call.

Exit XEIIN
Invoked before the execution of any EXEC CICS application programming interface (API) or system programming interface (SPI) command.
Exit XEISPIN
Invoked before the execution of any EXEC CICS SPI command except:
  • EXEC CICS ENABLE
  • EXEC CICS DISABLE
  • EXEC CICS EXTRACT EXIT
  • EXEC CICS PERFORM DUMP
  • EXEC CICS RESYNC ENTRYNAME
The sequence is: 
TRACE   –   XEIIN   –   XEISPIN   –   EDF   –   command
Exit XEIOUT
Invoked after the execution of any EXEC CICS API or SPI command.
Exit 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 might occur if the transaction is suspended; for example, during file I/O wait. This situation might 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, 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 EIB fields and in EXEC interface block (EIB) response and function codes. The function code is followed by a 2-byte field that contain 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 changing 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 modifying 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.