Design overview

The task-related user exit interface is comparable with the EXEC interface. When an application program requests the services of a non-CICS® resource manager, it does so by a module called the task-related user exit. The exit receives arguments from the application program, and passes them on to the resource manager in a suitable form.

The advantage of this method is that if the resource manager is changed, the application program that invokes the resource manager should not need to be changed too.

The exit is part of the resource manager programs. The name of the exit, or the name of the entry to the exit, is specified by the resource manager, and each application program that invokes the resource manager has to be link-edited with an application program stub that refers to that name.

The exit is enabled and disabled using the user exit manager (DFHUEM). For enabling, the resource manager can specify the size of a task-related work area that it requires.

The exit, when enabled and subsequently driven, receives arguments in the form specified by the DFHUEXIT TYPE=RM parameter list (see the CICS Customization Guide or the manual). Register 1 points to this parameter list. Register 13 points to the address of a save area, rather than the address of the CSA. The save area is 18 words long, with registers 14 through 12 stored in the fourth word onward.

Responses to the request are indicated by values placed in register 15, and also by means that are specific to the architecture of the application interface, for example, by moving data into storage areas passed by the call, or into the caller’s register 15.

The main control blocks used by the task-related interface are the task interface element (TIE):

Task-related user exit implementation

The state of an exit is managed by DFHUEM, which is described under User exit control. For an exit, the TALENGTH argument and a profile in the form of a bit-string are held in the exit program block (EPB). These arguments are not processed until the occurrence of an application program CALL that explicitly names the exit, unless the TASKSTART keyword is used on the ENABLE request.

Entry to the exit is through the task-related user exit interface, which comprises:

DFHERM receives a set of registers (those of the caller, for example, the application program), and a routing argument which names the exit. This routing argument is constructed by DFHRMCAL, in the application stub, and is not normally visible to the application programmer. DFHERM retrieves the name of the requested exit from the routing argument, and scans any existing task interface elements (TIEs) that are chained from the task’s TCA, looking for a TIE associated with the named exit. If such a TIE is not found, it searches the installed exits on a chain of EPBs, looking for the matching name. On finding a match, DFHERM constructs a TIE to represent the connection between that task and the exit. The TIE is initialized from information provided in the EPB; the TALENGTH argument defines the size of a task-local work area which can be thought of as a logical extension of the TIE. The profile string is also copied into the TIE.

DFHERM stacks (stores in a last-in, first-out manner) various parts of the program execution environment--the status of HANDLE commands, file browse cursors, the EXEC interface block (EIB), and so on--and builds a parameter structure which is essentially a superset of that built by DFHUEH. Additional arguments include the task-local work area, the profile referred to above, and an 8-byte UOW identifier supplied by Recovery Manager.

DFHERM then passes control to the exit’s entry point using standard CALL conventions, in which register 13 addresses a save area for DFHERM’s own registers, register 14 addresses DFHERM’s next sequential instruction, and register 1 addresses the passed parameters. This is a vector of addresses which include that of the caller’s register save area. Any changes the exit makes to arguments of the application program interface (API), or to the contents of the caller’s register save area, are not examined by DFHERM when it regains control, because they are not part of the CICS task-related user exit interface--rather they are the concern of the caller and the exit. However, the exit can request DFHERM to schedule certain actions by means of the profile argument. For example, the exit can request that it be informed (driven) when commitment of resources (syncpointing) is taking place, or the exit can request that DFHERM no longer routes API calls to it from this task.

Finally, on regaining control from the exit, DFHERM unstacks the objects that it had previously stacked, and returns to the caller. The state of the cursors, HANDLE labels, and so on, is apparently unchanged by the actions of DFHERM or the exit. Note that the exit may have used EXEC CICS HANDLE commands; this does not interfere with the caller’s HANDLE status.

In the discussion of DFHERM so far, the term "caller" has been used for the application program. However, a caller can be a function such as syncpoint (DFHERMSP), task control (DFHAPXM or DFHERMSP), system programming interface (DFHUEIQ), CICS termination (DFHAPDM or DFHSTP) or EDF (DFHERM). The exit can set appropriate bits in the profile (schedule flag word) so that, if the corresponding function is subsequently invoked, it in turn calls the exit. The exit can determine the identity of the caller from the first argument (called the "function definition"). This argument, passed by DFHERM, always has its first byte equal to X'00'. (If the first byte is other than X'00', the exit has been entered from DFHUEH as a global user exit.) DFHERM sets the second byte of this argument according to the type of caller, thus indicating which interface is addressed by the caller’s register save area. The second byte is:

X'01'
For system programming interface
X'02'
For an application program
X'04'
For the syncpoint program
X'08'
For CICS task control
X'0A'
For a CICS termination call
X'0C'
For an EDF call.

Any remaining arguments are specific to each individual caller.

The flow of control for the task-related user exit interface is shown in Figure 77.

Figure 77. Task-related user exit control flow
 This is a technical drawing showing the flow of control for the task-related user exit interface.

Processors

The term "processor" is used to refer to two different types of object:

  1. For the EXEC interface, it refers to the function-dependent modules associated with the EXEC interface nucleus, DFHEIP. These processors usually have names such as DFHEPC, DFHETC, DFHETD, and so on, and each of these is invoked by DFHEIP. DFHERM is also a processor of this type.
  2. In various contexts, including task-related user exits, it refers to a piece of code that is link-edited with an application program and serves the dual function of:

Both these types of processor are part of the path between an application call and the functional control module that supports the request. This path appears as follows:

Application call
 Application processor (type 2)
  DFHEIP
   EXEC interface processor (type 1)
    Functional control module

Examples of the interface are:

EXEC CICS SYNCPOINT ... CICS API
 DFHECI     CICS COBOL EIP router
  DFHEIP
   DFHEISP  CICS syncpoint router
    DFHSPP  CICS syncpoint manager
       CICS Recovery manager domain
 
EXEC DLI TERM ... DLI HLPI
 DFHECI     CICS COBOL EIP router
  DFHEIP
   DFHERM   CICS RMI module
    DFHEDP  DLI HLPI manager
             (implemented as a task-related
                user exit)
[[ Contents Previous Page | Next Page Index ]]