Global and Task-related Exit Programs

You must enable each user exit that an application program needs before it is called, and you can disable it when the application program has finished with it, though you do not have to; user exits are always disabled by default when CICS starts up. You use the CICS command ENABLE PROGRAM to enable a user exit program, and the CICS command DISABLE PROGRAM to disable a user exit program. If you try to enable an invalid exit an EIBRCODE of X'804000' is returned. If you try to enable an exit that is valid but not implemented, an EIBRCODE of X'804010' is returned. The EXTRACT EXIT command is also provided; you use this to gain access to the work area of a user exit program. For details of the level of support provided for these commands see the topic System Programmers Commands.

You must define each user exit program as a program (in the PLT) and the definition must be available on the running system.

For information about global user exits and task-related user exits see the IBM manual CICS/ESA 3.3 Customization Guide. This manual contains a list of valid user exit points.

You need to include the following two copybooks in your user exit program, whether it is for a global user exit or a task-related user exit:

  • The user exit parameters are passed to your exit program in structure uxi-user-exit-interface, defined in the copybook dfhcbuxi.cpy. Two fields in this structure, uxi-operational-flags-ptr and uxi-scheduling-flags-ptr, point respectively to two further structures, lk-uxc-operation and lk-uxz-schedule-param, in the other copybook, dfhcbuxc.cpy.
  • A CICS application can call a task-related user exit directly, for example, to obtain the address of the task area. Normally, the CICS application would call a task-related user exit program with the DFHRMCAL macro. As this macro is not supported, the application must call the user exit program directly, and must include the copy books dfhcbuxi.cpy and dfhcbuxc.cpy. If a user exit program can be called by an application program, you need to use a mechanism by which the exit program can decide whether it was called by an application program or by MSS. The sample exit program included below shows one approach: the application sets an unused bit in lk-uxc-schedule, which the user exit program tests for.