Open TCB management

The open transaction environment (OTE) is an environment where CICS® application code can use non-CICS services (facilities outside the scope of the CICS API) inside the CICS address space, without causing wait issues on the quasi-reentrant task control block (QR TCB).

Applications that exploit the open transaction environment run on their own open TCB, rather than on the QR TCB. CICS does not perform subdispatching on an open TCB, whereas it does on the QR TCB. If the application that is running on an open TCB calls a non-CICS service that blocks the TCB, the TCB blocking does not affect other CICS tasks. For more information about writing applications to exploit the open transaction environment, see Multithreading: Reentrant, quasi-reentrant, and threadsafe programs.

TCB modes

Each open TCB mode has a 2-character identifier to indicate its specific purpose, and is handled by CICS in a different way.
L8 mode TCBs and L9 mode TCBs
These TCBs are used as follows:
  • L8 TCBs are used for CICS-key application programs that are defined as API(OPENAPI) by their PROGRAM resource definition.
  • L8 TCBs are used for CICS-key application programs that are defined as CONCURRENCY(REQUIRED), API(CICSAPI) by their PROGRAM resource definition.
  • L8 TCBs are used when programs need access to a resource manager through a task-related user exit (TRUE) that was enabled using the OPENAPI option on the ENABLE PROGRAM command. Task-related user exits always run in CICS key.
  • L8 TCBs are used by CICS when accessing document templates and HTTP static responses that are stored in z/OS® UNIX System Services files.
  • L8 TCBs are used for web service requests and parsing XML CICS programs that run in CICS key and are defined as OPENAPI.
  • L9 TCBs are used for application programs that run in user key and are defined as OPENAPI.
CICS operates with an OPENAPI task-related user exit, and therefore uses L8 TCBs, when it is connected to the following products:

Other IBM products, for example, IP CICS Sockets and the z/OS Integrated Cryptographic Service Facility (ICSF), can also use an OPENAPI enabled task-related user exit. For more information about managing IP CICS sockets, see z/OS Communications Server: IP CICS Sockets Guide. For more information about the CICS-ICSF Attachment Facility, see z/OS Cryptographic Services ICSF System Programmer's Guide.

SP mode TCB and S8 mode TCBs
These TCBs are used by CICS to manage SSL connections and requests to LDAP using the DFHDDAPX XPI interface. The S8 TCBs run in a single enclave, which is owned by the SP TCB, and also contains the SSL cache.

The S8 TCBs are contained in an SSL pool, which is managed by the CICS dispatcher. Each SSL connection uses an S8 TCB from the SSL pool. All CICS processing for an SSL connection occurs on the S8 TCB (there is no switching between the S8 and SO TCBs). The web server HTTP attach task (CWXN by default) will stay on the S8 TCB until all the data have been sent or received.

An S8 TCB is allocated to a task from the SSL pool, but is locked only for the period of time that it takes to perform functions such as an SSL handshake or an LDAP request. After this function is complete, the TCB is released back into the SSL pool to be reused.

Note: If the messages being sent or received are very large, the task could hit the runaway limit and be terminated. To avoid the task being abended, you might need to increase the transaction RUNAWAY value for the web server HTTP attach transaction (CWXN by default), the web server alias transactions, and any transactions that issue the web client API commands SEND, RECEIVE, and CONVERSE.

In UNIX System Services (USS), the MAXTHREADS and MAXTHREADTASKS parameters can be used to restrict the number of pthreads that a USS process can own. Each SSL TCB requires a pthread and an MVS™ task. You must therefore ensure that the values of these USS parameters exceed the value of the MAXSSLTCBS system initialization parameter. If you do not set a large enough value for MAXTHREADS or MAXTHREADTASKS and CICS reaches one of these limits while attempting to attach an SSL TCB, CICS issues error message DFHDS0002 severe error code X'0137' from DFHDSIT.

TP mode TCB and T8 mode TCBs
These TCBs are used by a JVM server to process requests for Java™ programs. The JVM server is a runtime environment that can handle multiple concurrent requests for Java applications in a single JVM. The TP mode TCB owns the Language Environment® enclave and the pool of T8 TCBs. Each JVM server that is running in the CICS region has one TP TCB and at least one, but not more than 256, T8 TCBs. A T8 TCB is allocated to a task from the THRD pool of the appropriate JVM server, but is locked only for the period of time that it takes to perform the system processing. T8 TCBs are not shared between JVM servers.
Each T8 TCB requires a pthread and an MVS task. The maximum number of T8 TCBs that is allowed for the CICS region is 2000. In z/OS UNIX, you can use the MAXTHREADS and MAXTHREADTASKS parameters to restrict the number of pthreads that a z/OS UNIX process can own. You must therefore ensure that the values of these parameters exceed the maximum number of T8 TCBs. If you do not set a large enough value for MAXTHREADS or MAXTHREADTASKS and CICS reaches one of these limits while attempting to attach a T8 TCB, CICS issues error message DFHDS0002 severe error code X'0137' from DFHDSIT. For more information about the thread limits of JVM servers, see Managing the thread limit of JVM servers.
X8 mode TCBs and X9 mode TCBs
Both these TCBs are used to run C and C++ programs compiled with the XPLINK option. X8 TCBs are used for programs in CICS key, and X9 TCBs are used for programs in user key. Each instance of an XPLink program uses one X8 or X9 TCB. For more information about using XPLink, see XPLink and C and C++ programming .

Open TCB pools

CICS manages open TCBs in pools. A pool contains open TCBs that are used for the same purposes. A pool can consist of some TCBs that are allocated to tasks, and others that have been freed by applications and are available for reuse.

CICS can create or attach open TCBs in each pool up to the limit set for the pool. The maximum number of TCBs allowed in each pool is set as follows
  • The MAXOPENTCBS system initialization parameter, if specified, sets the value for the open TCB pool. If the MAXOPENTCBS system initialization is not specified, CICS sets the limit for the L8 and L9 mode open TCB pool automatically based on the maximum number of tasks specified for the CICS region (the MXT value), using the following formula: (2 * MXT Value) + 32. For information about explicitly setting the MAXOPENTCBS parameter yourself, see MAXOPENTCBS.
  • The MAXSSLTCBS system initialization parameter specifies the value for the SSL TCB pool.
  • MAXTHRDTCBS specifies the value for the JVM server THRD TCB pool. The number of threads reserved for each JVM serverTHREADLIMIT value on the JVMSERVER resource is automatically calculated by adding 1 to the number of threads, up to a limit of 2000.
  • The MAXXPTCBS system initialization parameter, if specified, sets the value for the XP TCB pool. If the MAXXPTCBS system initialization is not specified, CICS sets the limit for the X8 and X9 mode XP TCB pool automatically to a value equal to the maximum number of tasks specified for the CICS region (the MXT value). For information about explicitly setting the MAXXPTCBS parameter yourself, see MAXXPTCBS .

When an application makes a request that requires an open TCB, CICS first tries to find a suitable TCB that is available for reuse in the appropriate pool. CICS can match a request with an available TCB of the correct mode only if the TCB is for the correct subspace. CICS attaches a new TCB when it cannot find a suitable match with a free TCB for the correct subspace, provided that the limit for the pool has not been reached.

A CICS task is allowed as many X8 and X9 TCBs as it requires, and these TCBs are kept only until the program finishes. However, each CICS task is allowed at most one L8 and one L9 TCB, and it keeps an L8 and an L9 TCB from the time it is allocated to the end of the task, reusing it for further requests as needed. The TCBs then become free, and CICS can allocate them to another task or destroy them.

Sometimes CICS cannot find a suitable match for an application’s request, and the limit for the pool has been reached. In this situation, CICS might fulfill the request by destroying a free TCB in the pool that has the wrong subspace or mode, and replacing it with a TCB with the right mode and subspace. This technique is called stealing. Stealing can be costly on performance, depending on the type of open TCB, so CICS avoids it where it makes sense to do so. CICS maintains statistics of excess TCB management and TCB stealing activities in the CICS dispatcher TCB mode and TCB pool statistics.

If the number of TCBs is at the limit for the pool and there is no free TCB to steal, the task is suspended with an OPENPOOL wait until a TCB becomes free, or the limit for the pool is increased.

To minimize the impact on storage, CICS attempts to balance the number of open TCBs in each pool against current needs. If CICS finds free TCBs in a pool, it gradually reduces the excess number by detaching them, freeing the resources used by the excess TCBs.