Introduction to the task-related user exit mechanism (the adapter)

You can use a task-related user exit (TRUE) 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 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 must access a non-CICS resource, and the manager of that resource. Figure 1 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 below the 16 MB line, or above 16 MB but below 2 GB. For more information about addressing and residency modes, see 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 can 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.

Figure 1. The adapter concept
The diagram shows the stub program, the task-related user exit program, and the administration routines within the adapter. An application program outside the adapter is joined to the stub program by a two way arrow. Also outside the adapter is a non-CICS resource, joined to a resource manager. Two-way arrows join the application program to the task-related user exit program, and the task-related user exit program to the resource manager.

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 can be invoked by any of the following:
  • An application program
  • CICS SPI manager
  • CICS sync point manager
  • CICS task manager
  • CICS termination manager
  • CICS context management
  • CICS application environment management
  • 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 registers of the caller.

AMODE 64 task-related user exits are not supported.

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 might also contain commands to retrieve information about one of the work areas of the exit program (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 detailed programming information, see ENABLE PROGRAM command, DISABLE PROGRAM command, EXTRACT EXIT, and RESYNC ENTRYNAME.