Obligations of task-related user exits (TRUEs) running on open TCBs

If a TRUE runs on an open TCB, it is freed from the constraints imposed by the QR TCB and avoids the need to create and manage its own set of subtask TCBs. If an operating system wait issued by an external resource manager halts the open TCB, CICS® continues processing on the QR TCB, and on other open TCBs. A TRUE running on an open TCB nevertheless has obligations both to the CICS system as a whole and to future users of the open TCB it is using.

Obligations of TRUEs running on L8 open TCBs

An L8 TCB is dedicated for use by the CICS task to which it is allocated to, but when 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 TRUE, and not that the TRUE has broken the threadsafe restrictions, which CICS would not detect.

An L8 TCB is not dedicated for use by a particular TRUE, but is used by all TRUEs that are invoked by the CICS task and that require an L8 TCB. The L8 TCB is also used by the threadsafe application code executed by the task.

Obligations of TRUEs running on T8 and X8 open TCBs

For XPLINK programs and for Java programs running in an OSGi JVM, X8 and T8 TCBs are respectively dedicated for to use by the CICS task at that link level. When control returns to a higher link level, the TCB is freed and is available for use by another CICS task.

For Java programs running in a Liberty JVM, the T8 TCB is dedicated to use by a CICS task for the lifetime of that task in the same way as an L8 TCB. If T8 TCBs remain clean, they can be used by subsequent tasks. And the application code that is executed by the calling task runs on the same TCB as the TRUE.

Threadsafe restrictions

A TRUE running on an open TCB must not treat the executing open TCB environment in such a way that it causes problems for the following:
  • Other TRUEs running on open TCBs called by the same task
  • OPENAPI programs called by the same task
  • Application program logic that could run on the open TCB
  • Future tasks that might use the open TCB
  • CICS management code
In particular:
  • When invoking CICS services, or when returning to CICS, A TRUE running on an open TCB must ensure it restores the z/OS® programming environment as it was on entry to the TRUE. This includes cross-memory mode, ASC mode, request block (RB) level, linkage stack level, TCB dispatching priority, in addition to canceling any ESTAEs added.
  • At CICS task termination, a TRUE running on an open TCB must ensure it leaves the open TCB in a state suitable to be reused by another CICS transaction. In particular, it must ensure that all non-CICS resources acquired specifically on behalf of the terminating task are freed. Such resources might include:
    • Dynamically allocated data sets
    • Open ACBs or DCBs
    • STIMERM requests
    • z/OS-managed storage
    • ENQ requests
    • Attached subtasks
    • Loaded modules
    • Owned data spaces
    • Added access list entries
    • Name/token pairs
    • Fixed pages
    • Security settings (TCBSENV must be set to zero)
  • A TRUE running on an open TCB must not use the following z/OS system services that will affect overall CICS operation:
    • CHKPT
    • ESPIE
    • QEDIT
    • SPIE
    • STIMER
    • TTIMER
    • XCTL / XCTLX
    • Any TSO/E services
  • A TRUE running on an open TCB must not invoke under the L8 mode TCB a Language Environment® program that is using z/OS Language Environment services, because L8 mode TCBs are initialized for Language Environment using CICS services.