Administering the adapter

Careful use of task-related user exits can allow your application programmers to be unaffected by the invocation of non-CICS resource managers from CICS® application programs. Enabling and disabling task-related user exit programs for an installation should be the responsibility of one or more supervisory or master terminal operators. This section lists what you must do before you can use the adapter, and describes the commands used by the supervisor to administer task-related user exit programs.

What you must do before using the adapter

  1. A task-related user exit program must be defined to the system using the CEDA INSTALL PROGRAM command.
  2. To enable the task-related user exit program and to define its working storage needs, you must use the EXEC CICS ENABLE command. A task-related user exit program must be both enabled and started before it is available for execution. For example:
    EXEC CICS ENABLE PROGRAM('EP9')
         TALENGTH(750) GALENGTH(200) SHUTDOWN
    EXEC CICS ENABLE PROGRAM('EP9')
         START
    The first command loads the task-related user exit program EP9, and causes a 200-byte work area to be obtained and associated with it. The first command also schedules the allocation of a further 750-byte work area for each task that subsequently invokes EP9, and the invocation of EP9 at CICS termination. The second command starts the exit program, that is, it makes its entry point capable of being invoked.
    Note:
    If a task-related user exit program is enabled before it has been installed, CICS scans the LPA for the program and may issue message DFHLD0107I, meaning that it was unable to find the program in the LPA and is using the DFHRPL version.

Enabling for specific invocation-types

Use the following options of the EXEC CICS ENABLE command to cause your exit program to be invoked at specific events:

INDOUBTWAIT
specifies that, at phase 2 syncpoint time, if CICS is in-doubt about the outcome of the UOW, the exit program is to be invoked with the UERTWAIT verb (wait), instead of a forced definition of UERTCOMM (commit) or UERTBACK (backout). UERTWAIT signifies that CICS does not yet know the outcome of the UOW. In response to a UERTWAIT call, the task-related user exit should invoke its resource manager to free any task-related resources, such as the thread. However, the resource manager should maintain any locks held by the UOW, and record that the UOW is in-doubt.

When CICS receives the outcome of the UOW from its coordinator, a resynchronization task is attached to notify the task-related user exit about the outcome of the UOW.

If CICS is in-doubt about the outcome of a UOW for which an external resource manager has requested resynchronization (using the EXEC CICS RESYNC command), CICS waits until the in-doubt has been resolved before initiating a resynchronization task.

The effects of not enabling a task-related user exit with the INDOUBT keyword are:

SHUTDOWN
specifies that the exit program is to be invoked at CICS shutdown.
SPI
specifies that the exit program is to be invoked to satisfy EXEC CICS INQUIRE EXITPROGRAM calls that specify the CONNECTST or QUALIFIER options. Use this option to enable user programs to discover whether the exit program is connected to its resource manager, and what its entryname qualifier is.
Note:
The exit program can set this option dynamically, by setting the UEFMSPI bit-mask in the schedule flag word.

For programming information about the EXEC CICS ENABLE PROGRAM command, refer to the CICS System Programming Reference manual.<

The administration routines

As well as being enabled before they can be used, task-related user exit programs should be disabled when you have finished using them. You should prepare procedures (the administration routines) for enabling and disabling your task-related user exit programs, using the EXEC CICS ENABLE and DISABLE commands, and for resynchronizing between sessions or after a system failure. Your enabling routines could be PLT initialization programs or online programs. Your disabling routines could, for example, be started by a TRUE invoked at CICS termination.

The EXTRACT EXIT command obtains the address and the length of a global work area that is owned by, or shared by, a named task-related user exit program.

For programming information about these commands and the rules governing them, and also about resynchronization, refer to the CICS System Programming Reference manual.

Tracing a task-related user exit program

CICS outputs a trace entry just before control is passed to the task-related user exit and just after returning from the exit. You can control these trace entries using the RI option of the CETR trace control transaction or the EXEC CICS SET TRACETYPE command.

Related concepts
Introduction to the task-related user exit mechanism (the adapter)
The stub program
Overview of the XPI
Related tasks
Writing a task-related user exit program
Making an XPI call
Related reference
The XPI functions
[[ Contents Previous Page | Next Page Index ]]