A task-related user exit allows you to write your own program to access a resource, such as a database, that would not otherwise be available to your CICS® system. Such a resource is known as a non-CICS resource. The exit is said to be task-related because it becomes part of the task that invoked it and because, unlike a global user exit, it is not associated with an exit point. You do not have to use any of the task-related user exits, but you can use them to extend and customize the function of your CICS system according to your own requirements.
The most common use of a task-related user exit is to communicate with a resource manager external to CICS, for example, a file or database manager. The CICS interface modules that handle the communication between the task-related user exit and the resource manager are usually referred to as the resource manager interface (RMI) or the task-related user exit interface.
The task-related user exit mechanism is known as an adapter because it provides the connection between an application program that needs to access a non-CICS resource and the manager of that resource. Figure 4 illustrates the adapter concept.
The adapter is made up of three or more locally-written programs. These are a "stub" program, a task-related user exit program, and one or more administration routines or programs.
The stub program intercepts a request (for example, to access data held on an external database manager) issued by the calling application program. The stub can be used to resolve a locally-defined high-level language command into a task-related user exit macro call, DFHRMCAL, which then causes CICS to pass control to the task-related user exit program.
The task-related user exit program translates commands for accessing a non-CICS resource into a form acceptable to the resource manager. The program must be written in assembler language, and can reside above or below the 16MB line. For more guidance information about addressing and residency modes, refer to Addressing-mode implications. The program must not alter the contents of any access registers. It is executed in response to a specific application program request, for example, to read data from an external database. In this instance, it may be passed application data, such as a search argument for a required record. Responses from the resource manager are passed back to the calling program by the task-related user exit program.
The task-related user exit program is provided with a parameter list (DFHUEPAR) by the CICS management module that handles task-related user exits. This parameter list gives the task-related user exit access to information such as the addresses and sizes of its own work areas.
The task-related user exit program may be invoked by the CICS task manager, the CICs SPI manager, and the CICS syncpoint manager, as well as by an application program. It may also be invoked at CICS termination or by the Execution Diagnostic Facility (EDF). The parameter list serves to distinguish between these various callers, and gives access to a register save area containing the caller’s registers.
The administration routines contain the EXEC CICS ENABLE and DISABLE commands that you use to install and withdraw the task-related user exit program. The administration routines may also contain commands to retrieve information about one of the exit program’s work areas (the EXEC CICS EXTRACT EXIT command), and to resolve any inconsistency between CICS and a non-CICS resource manager after a system failure (the EXEC CICS RESYNC command). For programming information about the EXEC CICS ENABLE, DISABLE, EXTRACT EXIT, and RESYNC commands, refer to the CICS System Programming Reference manual.
The remainder of this section discusses each of these parts of the adapter in turn.