Filter
Top Products
Writing a task-related user exit program
The main function of the task-related user exit program is to translate the calling
program’s parameters into a form acceptable to your non-CICS resource manager,
and then to pass control to the resource manager. You therefore need to be familiar
with your resource manager’s syntax requirements. The calling program’s
parameters are described in “Caller parameter lists” on page 279.
This section describes the user exit parameter lists, the schedule flag word, which
is used by the exit program to register its need to be invoked by CICS management
services, and register-handling in the task-related user exit program. This section
also discusses the use of the CICS syncpoint manager and the CICS task manager.
It also discusses some factors that you should consider if you plan to use TCBs
provided by the CICS open transaction environment (OTE).
Obligations of OPENAPI task-related user exits
Open API task-related user exits (that is, exits enabled with the OPENAPI option)
are invoked on an open L8 mode TCB instead of the main CICS QR TCB. If a
TRUE wants to invoke an external resource manager without the benefit of the
open API facility, it has to manage its own set of subtask TCBs. It can then use one
of these private TCBs on which it can run the request to access the external
resource manager. Typically, the subtask TCB is posted to access the external
resource manager, while the CICS task running on the QR TCB in the TRUE is put
into a CICS dispatcher wait until the subtask completes its work. The CICS
dispatcher wait allows the CICS dispatcher to dispatch another CICS task on the
QR TCB in the meantime. The reason for this architecture is that external resource
managers cannot be invoked directly by a caller on the QR TCB, because any
operating system wait issued by the external resource manager would halt the QR
TCB, and thereby the whole of CICS.
An open API TRUE is invoked on an L8 mode TCB, which is dedicated for use by
the calling CICS task, and is separate from the CICS QR TCB. Therefore, a TRUE
can invoke its external resource manager on the allocated L8 TCB and avoid the
need to manage its own set of subtask TCBs. An operating system wait issued by
an external resource manager will halt the L8 TCB, but CICS continues processing
on the QR TCB, and on other open TCBs.
An open API TRUE, although freed from the constraints imposed by the QR TCB,
and from having to create subtask TCBs, nevertheless does have obligations both
to the CICS system as a whole and to future users of the L8 TCB it is using. An L8
TCB is dedicated for use by the CICS task to which it is allocated, but once the
CICS task has completed, the L8 TCB is returned to the dispatcher-managed pool
of L8 mode TCBs, provided it is still in a “clean ” state. (An unclean TCB in this
context means that the task using the L8 mode TCB suffered an unhandled abend
in an open API TRUE, and not that the TRUE has broken the threadsafe
restrictions, which CICS would not detect.) Note that the L8 TCB is not dedicated
for use by a particular open API TRUE, but is used by all open API TRUEs and
OPENAPI programs invoked by the CICS task to which the L8 mode TCB is
allocated. Also, if an application program invoking an open API TRUE is coded to
threadsafe standards, and defined to CICS as threadsafe, it continues to execute
on the L8 mode TCB on return from the TRUE. When considering whether to
exploit CICS OTE support rather than manage your own subtask TCBs, consider
the restrictions listed below. You can then decide whether to work within these
restrictions or to use your own subtask TCB, which is dedicated for your own
TRUE's use.
Chapter 2. Task-related user exit programs 271