Using CICS services

The rules governing the use of CICS® services in exit programs vary, depending on the exit point from which the exit program is being started.

The following general rules apply:
  • No CICS services can be started from any exit point in the dispatcher domain.
  • CICS services can be started by using the exit programming interface (XPI) from most exits. If you use the XPI, note the rules and restrictions that are listed for each exit and each of the XPI macros.
  • Some CICS services can be requested by using EXEC CICS commands from some exits. The valid commands are listed in the detailed descriptions of the exits. If no commands are listed, it means that no EXEC CICS API or SPI commands are supported. EXEC CICS commands that cause an XCTL (either directly or implied); for example, EXEC CICS XCTL or EXEC CICS SHUTDOWN must never be used.

    An exit program started at an exit that does not support the use of EXEC CICS commands must not call a task-related user exit program (TRUE). Calling a TRUE is equivalent to issuing an EXEC CICS command. Exceptions to this rule are programs started from the XFCFRIN and XFCFROUT exits, which can call a TRUE.

    Note: In exits which support the use of EXEC CICS file control commands, file commands that form a related sequence (such as EXEC CICS STARTBR, EXEC CICS READNEXT, and EXEC CICS ENDBR) must all be issued in the same invocation of the exit program.

    For example, if one invocation of an exit program issues an EXEC CICS STARTBR command, and the next invocation of the exit program for that same task issues an EXEC CICS READNEXT command, the READNEXT fails with an INVREQ condition.

  • All exit programs that issue EXEC CICS commands must first address the EIB. This is not done automatically by using the DFHEIENT macro, as is the case with normal EXEC assembler language programs. Therefore, the first EXEC command to be issued from an exit program must be EXEC CICS ADDRESS EIB (eib-register), where eib-register is the default register (R11) or the register given as a parameter to the DFHEIENT macro.

    All exit programs that issue EXEC CICS commands and that use the DFHEIENT macro, should use the DFHEIRET macro to set a return code and return to CICS. See Returning values to CICS.

  • There are a number of exits where you can use both EXEC CICS commands and XPI calls, but you should ensure that there is no conflict in the usage of register 13. To avoid such conflict, use the DATAREG option on the DFHEIENT macro (see XPI register usage for information).

    For an example of how to use EXEC CICS commands and XPI calls in the same global user exit program, see Global user exit sample program DFH$XTSE.

Important:
  • If your global user exit program does not contain EXEC CICS commands, do not use the CICS command-level translator when assembling the program.
  • Do not make non-CICS (for example, RACF® or MVS) system service calls from global user exit programs.
  • If an operating system request causes a wait, your whole CICS system stops until the operating system request has been serviced.