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.
- A task-related user exit program must be defined to the system using the
CEDA INSTALL PROGRAM command.
- 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:
- If CICS is in-doubt about a UOW, a forced decision is taken and the task-related
user exit invoked with the forced decision.
- If CICS is forced to take a decision because a task-related user exit is
not enabled with INDOUBTWAIT, it takes a forced decision for all resources updated by the UOW, even if all the other resources are
capable of waiting for in-doubt resolution. This applies to local resources
such as files, and also other RMCs, such as LU6.1, LU6.2, or MRO connections
to other systems.
- An inbound RESYNC command from a resource manager that requests resynchronization
for a UOW that CICS was in-doubt about, results in CICS invoking the
task-related user exit with a forced decision.
- 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.
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.
[[ Contents Previous Page | Next Page Index ]]