System initialization parameters for open TCBs

The open transaction environment (OTE) function was added to CICS® Transaction Server for OS/390®, Version 1 Release 3 and later versions.

In earlier releases of CICS, CICS ran all user transactions under a single z/OS® TCB, the CICS quasi-reentrant (QR) TCB. Direct invocation of other services outside the scope of the CICS permitted interfaces could interfere with the use by CICS of the QR TCB. In particular, requests that resulted in the suspension ("blocking") of the QR TCB, which happens when an MVS™ wait is issued, would cause all CICS tasks to wait. For example, some services provided by DB2®, MVS, UNIX System Services, or TCP/IP, might result in TCB blocking.

The open transaction environment is an environment where CICS application code can use non-CICS services (facilities outside the scope of the CICS API) within the CICS address space, without interference with other transactions. Applications that exploit the open transaction environment run on their own open TCB, rather than on the QR TCB. Unlike the QR TCB, CICS does not perform sub-dispatching on an open TCB. If the application running on an open TCB invokes a non-CICS service that blocks the TCB, the TCB blocking does not affect other CICS tasks.

There are several open TCB modes, each given 2-character identifiers. Each mode has a specific purpose, and is handled by CICS in a different way:

J8 mode TCBs and J9 mode TCBs
are both used to run Java™ programs under a Java Virtual Machine (JVM). The JVM is created on the TCB. J8 TCBs are used for JVMs in CICS key, and J9 mode TCBs are used for JVMs in user key. "How CICS manages JVMs in the JVM pool" in Java Applications in CICS has more information about how CICS manages JVMs and their TCBs.
Start of changeL8 mode TCBs and L9 mode TCBsEnd of change
Start of changeare both used to run OPENAPI programs, that is those defined as OPENAPI by their PROGRAM resource definition. End of change
L8 mode TCBs
are Start of change also End of change used when programs need access to a resource manager through a task-related user exit (TRUE) enabled using the OPENAPI option on the ENABLE PROGRAM command.

When CICS is connected to DB2, the CICS DB2 task-related user exit operates in OPENAPI mode (it is an open API TRUE). In this situation, the CICS DB2 attachment facility uses L8 TCBs for DB2 request processing. (Prior to this, the CICS DB2 attachment facility had to create and manage its own subtask thread TCBs with which to access DB2 resources, so that waits for DB2 resources would not block the QR TCB.) "Overview: How threads work" in the CICS DB2 Guide has more information about how CICS uses open TCBs as thread TCBs for the CICS DB2 attachment facility. "Enabling CICS DB2 applications to exploit the open transaction environment (OTE) through threadsafe programming" in the CICS DB2 Guide explains what your CICS DB2 application programs must do in order to gain performance benefits by continuing to run on the L8 mode TCB after the DB2 request has been completed.

L8 mode TCBs
are also used by CICS itself, because CICS uses OPENAPI CICSKEY programs which run on L8 TCBs:
Start of changeSP mode TCB and S8 mode TCBsEnd of change
Start of changeare used by CICS to manage SSL connections. The S8 TCBs run within a single enclave, which is owned by the SP TCB and also contains the SSL cache. An S8 TCB is allocated to a task from the SSL pool, but is only locked for the period of time it takes to perform SSL functions such as the SSL handshake. After the SSL negotiation is complete, the TCB is released back into the SSL pool to be reused.

Start of changeIn UNIX System Services, 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 should therefore ensure that the values of these USS parameters exceed 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.End of change

End of change
Start of changeX8 mode TCBs and X9 mode TCBsEnd of change
Start of changeare both used to run C and C++ programs compiled with the XPLINK option. X8 TCBs are used for programs in CICS key, and X9 mode TCBs are used for programs in user key. Each instance of an XPLink program uses one X8 or X9 TCB. in the CICS Application Programming Guide has more information about using XPLink.End of change

Start of changeA CICS task is allowed as many J8, J9, X8 and X9 TCBs as it requires, and these TCBs are only kept until program termination, but 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. The TCBs then become free, and CICS can allocate them to another task, or destroy them.End of change

CICS manages open TCBs in pools. A pool contains open TCBs that are used for the same purpose; for example, there is a pool of L8- and L9-mode open TCBs and a pool of J8- and J9-mode open TCBs (which is known as the JVM pool). The priority of the open TCBs in the JVM pool is set lower than that of the main CICS QR TCB, to ensure that the J8 and J9 TCB activity does not affect the main CICS workload that is being processed on the CICS QR TCB.

The maximum number of TCBs allowed in each pool is specified by a MAXxxxxTCBS parameter:

The minimum permitted value for any of the MAXxxxxTCBS parameters is 1, meaning that CICS is always able to create at least 1 open TCB in each mode. CICS can create (or attach) open TCBs in each pool up to the limit set by the corresponding MAXxxxxTCBS parameter.

At any one time, 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. For example, if the maximum number of open TCBs for JVMs (J8- or J9-mode) is set to 10, at a particular time the pool could consist of 5 TCBs, not all of which are allocated.

When an application makes a request that involves the use of an open TCB (for example, a request to execute a Java program in a JVM), CICS first tries to find a suitable TCB that is available for reuse in the appropriate pool of open TCBs. CICS can match a request with an available TCB of the correct mode only if the TCB has matching attributes. For example, in the case of a request for a J8- or J9-mode TCB, a free JVM TCB can be allocated only if the JVM profile names also match.

CICS attaches a new TCB if it can't find a suitable match with a free TCB, provided that the MAXxxxxTCBS limit for the pool has not been reached. For the JVM pool, where the creation of a JVM can involve a large amount of MVS storage, an additional safeguard is provided by the CICS storage monitor for MVS storage, which prevents the creation of new JVMs if MVS storage is severely constrained.

If CICS cannot find a suitable match, and the MAXxxxxTCBS limit for the pool has been reached, CICS might fulfil the request by destroying a free TCB that has the wrong attributes, and replacing it with a TCB that has the right attributes. 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. For L8 mode TCBs (used by task-related user exits enabled with OPENAPI), the cost of stealing a TCB is low, so CICS always steals a TCB if it receives a request for which it cannot find a suitable match with a free TCB or attach a new TCB. However, for J8- and J9-mode (JVM) TCBs, the cost of TCB stealing is high, because CICS needs to destroy and re-initialize the JVM as well as the TCB; so CICS has a selection mechanism to decide if stealing the TCB is worthwhile, or if the request should be made to wait. CICS maintains statistics of excess TCB management and TCB stealing activities.

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

When specifying any of the MAXxxxxTCBS parameters, take into account TCB storage requirements. All TCBs use real storage, and virtual storage below 16MB, so the number of open TCBs that a CICS region can support is restricted by the amount of storage available both above and below 16MB. JVMs, which run on J8- and J9-mode TCBs, use a large amount of storage above 16MB in addition to the cost of the TCB. "Managing your JVM pool for performance" in the CICS Performance Guide has guidance for calculating the number of JVMs that your CICS region can support.

Related tasks
Specifying CICS system initialization parameters
Specifying DFHSIT macro parameters
The default system initialization table
Assembling the SIT
Selecting versions of CICS programs and tables
Processing system initialization parameters
Related reference
The system initialization parameter descriptions
[[ Contents Previous Page | Next Page Index ]]