User exit control

User exit control enables the user to run exit programs at selected points (known as exit points) in CICS® modules in the application domain and in other domains. The exit program can be enabled or disabled dynamically, and useful information can be transferred to a user work area.

This function:
  • Controls which exit programs are to run at which exit points. This is generally specified using EXEC CICS commands and can be changed during a CICS run.
  • Invokes the specified exit programs when control reaches an exit point in a CICS module, and handles any change in flow indicated by a return code from the user exit program.

The exit programs are separate from the control modules and are associated with them dynamically by means of the EXEC CICS ENABLE command. See Customizing with user exit programs for a description of how to use exit programs.

Design overview

An exit point can have more than one exit program, and an exit program can be shared by more than one exit point. Work areas can be set up for the exit programs, and several exit programs can share a work area. For some exit points, the continuation of the control module can be controlled by a return code.

Each exit point is identified internally by an exit number. The user exit table (UET) contains a UET header and an entry for each exit point, in exit-number order. The UET is addressed from CSAUETBA in the CSA and exists throughout the life of CICS.

Each enabled exit program is represented by an exit program block (EPB). This exists only while an exit program is enabled or while any other exit program is using the work area owned by this exit program. The EPBs are chained together in order of enablement. The UET header points to the first EPB.

Each activation of an exit program for a particular exit point is represented by an exit program link (EPL) which points to the EPB for the exit program. The first EPL for each exit point is contained in the UET entry. If an exit point has more than one exit program, additional EPLs are obtained to represent each subsequent activation. These additional EPLs are chained off the UET entry in order of activation. Thus, for each exit, its EPL chain defines the exit programs that are to be executed at that exit point, and the order of execution.

The user exit interface (UEI) control blocks are illustrated in Figure 1. Note that most of the linkages that are shown in the diagram are created dynamically in response to ENABLE commands.
Figure 1. UEI control blocks
Diagram illustrating the control blocks for the user exit interface.
Note:
  1. There are three enabled programs: AAA, BBB, and CCC.
  2. Program AAA owns a global work area, which is shared by program BBB. The global work area pointer (@GWA) in BBB’s EPB points to the EPB of the program owning the shared area, namely AAA’s EPB.
  3. Exits 1 and 4 are associated with these exit programs.
  4. For Exit 1, exit programs AAA, CCC, and BBB have been activated, in that order, as indicated by the EPL chain.
  5. Exit program BBB has been activated for exit 4.

All user exit programs are executed in the AP domain. When exit programs are activated for exit points in other domains, control is passed from the domain to the AP domain’s user exit service module, which creates the necessary environment to invoke the exit programs via the user exit subroutine.

Control blocks

The control blocks associated with the user exit interface are illustrated in Figure 1 and Figure 2.
Figure 2. Control blocks associated with the user exit interface
Diagram showing the control blocks associated with the user exit interface.
Table 1. Main control blocks
Control block Description
UETH User exit table header
UETE User exit table entry, one for every exit point
EPB Exit program block, one for every enabled user exit program, containing information about the location and activity of the program, and any global work area owned or shared by the program
EPL Exit program link. Each EPL indicates one exit program to be invoked at an exit point and which EPL, if any, contains information about the next program to be invoked at that exit point.

Modules

Module Description
DFHAPEX The interface between an exit point in a domain (other than the AP domain) and the AP domain.
DFHSUEX Handles the invocation of user exit programs at exit points in CICS domains (other than the AP domain). Processing is similar to DFHUEH, passing a parameter list defined in DFHAPEX.
DFHUEH Links an exit point in a CICS management module in the AP domain and the user code. DFHUEH invokes in turn each started exit program for that exit point, passing a parameter list defined in the CICS management module.
DFHUEM The EXEC interface processor for the ENABLE, DISABLE, and EXTRACT user exit commands.

Exits

No global user exit points are provided for this function.

Trace

The following point IDs are provided for this function:
  • AP D5xx, for which the trace levels are UE 1, AP 1, AP 2, and Exc.

For user exit programs running at an exit point within the AP domain, UE level 1 trace entries are produced.

For user exit programs running at an exit point in a CICS domain other than the AP domain, the UE level 1 trace entries are not produced. Instead, the D5xx trace entries for AP level 1 and AP level 2 are available, providing more information than the UE trace. For AP level 1, the DFHUEPAR parameter list is traced, containing the addresses of fields special to that exit point. For AP level 2 tracing, the contents of the fields are printed, each field being truncated to 200 bytes if necessary.

Module reference