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.

About this task

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. The XPI is described in The user exit programming interface (XPI).
  • 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. TRUEs are described in Task-related user exit programs.

    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.

Note:
  • 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.