Tuesday, November 26, 2019

Clearing Some Things Up Regarding the CICS-Db2 for z/OS Interface

Not long ago, a very experienced Db2 for z/OS person contacted me with some questions about the CICS-Db2 interface. He mentioned that he did this because he was having trouble finding the information he was seeking in the product documentation. I provided this person with answers to his questions, and then thought to myself, "If a veteran Db2 for z/OS technical professional was challenged in getting a clear picture of the CICS-Db2 interface, perhaps other people are in the same boat." In this blog entry, I'll try to explain how the piece parts of the relationship between a CICS region and a Db2 subsystem fit together, and in doing that I'll aim as well to clarify some of the terminology one might encounter in this domain.

The specific questions

There were a couple of questions that sparked my exchange with the Db2 person. First, he noted that when he and a CICS colleague of his displayed information about CICS-Db2 threads for a certain CICS region (using either a performance monitor or the Db2 command -DISPLAY THREAD), they'd see that a lot of the threads were in IDENTIFY status, and they weren't sure as to what that meant.

Second, they saw that the total number of threads appeared to equal the value of the TCBLIMIT parameter for the CICS region in question (more on TCBLIMIT to come), and they also observed that the TCBLIMIT values for the CICS regions that access a Db2 subsystem added up to a number that exceeded the CTHREAD value in the Db2 subsystem's ZPARM module, and this caused them some concern (CTHREAD is the maximum number of "local to Db2" threads - i.e., not DDF threads - that can be allocated at one time).

Where is the interface between a CICS region and a Db2 subsystem defined?

The veteran Db2 person who directed these questions to me referenced a parameter in "the RCT." I knew exactly what he meant, and "RCT" is an acronym often used in describing a CICS-Db2 set-up; however, it is a technically outdated term. Here's the deal: RCT, which is short for resource control table, refers to a macro that, long ago, provided the specifications for the interface between a CICS region and a Db2 subsystem. More than 20 years ago, the specifications pertaining to this interface moved from the RCT to CICS RDO, which is short for resource definition online. You have a DB2CONN resource in which things like the maximum number of CICS-Db2 subtask TCBs ("subtask TCBs" is explained below) and the maximum number of pool threads for the CICS region are defined, and one or more DB2ENTRY resources where a plan can be associated with a CICS transaction (or a group of transactions) and where the number entry threads for a transaction (or group of transactions) - including, perhaps, protected entry threads - is specified (another CICS resource, called DB2TRAN, can be used to associate a CICS transaction with a DB2ENTRY resource, when that transaction is not explicitly specified in the DB2ENTRY resource).

Answering the questions: IDENTIFY status

In spite of being something you see in a Db2 monitor display of thread information, or in the output of the Db2 command -DISPLAY THREAD, IDENTIFY status is something I think of more in terms of tasks than of threads. Here, I'm referring specifically to the subtask TCBs that are used by CICS-Db2 transactions. When such a task is in IDENTIFY status, I see it as being a task is known to Db2 - known, I would say, as essentially a connection from a particular CICS region to the Db2 subsystem. When a CICS-Db2 transaction executes, it uses a subtask TCB, and that TCB in turn uses a Db2 thread.

When a CICS-Db2 transaction finishes, the Db2 thread it used goes away (unless it was a protected thread), but the subtask TCB it used remains. In my view, a CICS subtask TCB used for CICS-Db2 transactions is in IDENTIFY status when it is not being used. Note that when a CICS-Db2 transaction uses a protected entry thread, the thread persists when the transaction completes, and remains associated with the transaction's subtask TCB, so that the thread can be reused for another execution of the transaction (more information on how protected threads drive CICS thread reuse can be found in an entry I posted to this blog a few years ago).

Answering the questions: CICS's TCBLIMIT and Db2's CTHREAD

In the DB2CONN resource for a CICS region, there is a value, TCBLIMIT, that indicates the maximum number of CICS-Db2 subtask TCBs that can exist for the CICS region. If all of those subtask TCBs are being used by transactions and another transaction request is received, that request will be queued to wait for a subtask TCB to free up.

I referred previously to the CTHREAD parameter in the ZPARM module of a Db2 subsystem. The value of CTHREAD, as noted, specifies the maximum number of "local to Db2" threads (i.e., not DDF threads) that can be allocated at one time. Threads used by CICS-Db2 transactions are among those considered to be be "local to Db2."

Can the sum of the TCBLIMIT values for all of the CICS regions connected to a given Db2 subsystem exceed the Db2 subsystem's CTHREAD limit? Yes, because at any given time there could be a number of subtask TCBs that aren't being used by transactions, and those subtask TCBs don't need threads (though, as mentioned, a protected thread will remain associated with a subtask TCB as long as the protected thread exists).

How many Db2 threads can a particular CICS region use at once? That would be the sum of the THREADLIMIT values for all the DB2ENTRY resources and for the DB2CONN resource for the region (THREADLIMIT for the DB2CONN resource refers to CICS pool threads), plus the value of COMTHREADLIMIT in the DB2CONN resource (this value pertains to CICS command threads). Note that the TCBLIMIT value in a CICS region's DB2CONN resource should not be smaller that that sum of THREADLIMIT values plus the COMTHREADLIMIT value - having enough CICS-Db2 threads for a CICS region is not of much value if there are not enough subtask TCBs that can be used for CICS-Db2 transactions (it should be OK if the value of TCBLIMIT is a little higher than the sum of the THREADLIMIT values plus the COMTHREADLIMIT value).

Another thing to consider in this area: have enough CICS-Db2 pool threads, if you have Db2 transactions that always use pool threads, or that can overflow to the pool if all the transaction's entry threads are in-use. I recommend issuing the CICS command DSNC DISPLAY STATISTICS, and examining the output, which might look something like this (I added color highlighting):

DFHDB2014 07/09/98 14:35:45 IYK4Z2G1 Statistics report follows for RCTJT
accessing DB2 DB3A
*COMMAND             1       1     1    1       0         0       0
*POOL    ********    4       1     0    1       0         2       0
XC05     TESTP05    22       1    11    2       0         7       5
XP05     ********    5       2     0    1       0         1       1

DFHDB2020 01/17/98 15:45:27 IYKA4Z2G1 The display command is complete.

The row I highlighted in red is for the pool threads. In that row, check the number in the W/P column (I highlighted the W/P heading in blue above), which shows the number of times there was a wait or an overflow to the pool. For the pool threads, overflow is not relevant because you're already in the pool, so a non-zero number under W/P for the pool indicates a number of waits, and that suggests that the demand for pool threads exceeded the supply at times. In that case, it might be a good idea to increase THREADLIMIT for the DB2CONN resource (and doing that could potentially lead you to increase the TCBLIMIT value in DB2CONN).

As always, thanks for stopping by. I hope that this information will be helpful to you.


  1. Robert very clear as always.

    Sorry if I'm out of scope but I have a question with the thread number.
    Our goal is to increase the available threads, special for Cics. We have DB2 V12.
    Our reasoning is as follows:
    From the memory available for thread and footprint
    we obtain the maximum of the threads available in the analyzed interval.
    The available memory is obtained from the extend region size, currently it is 1162MB (we get it from omegamon or from the console))
    # 1 Do you agree with the reasoning?
    # 2 What parameter of ZOS or DB2 can be modified to increase the extend region size?
    Thank you,

    1. I believe that the region size for the Db2 for z/OS database services address space (DBM1) can be modified by changing that specification in the start-up procedure for that address space.

      The large majority of the virtual storage for threads in the DBM1 address space is in the extended private part of that address space, and I'm not sure that the region size applies to above-the-bar virtual storage. It appears that each thread consumes 298 bytes of virtual storage in DBM1 below the 16 MB line, as indicated by the formula on this page of the Db2 12 documentation on IBM's Web site: https://www.ibm.com/docs/en/db2-for-zos/12?topic=storage-calculating-virtual-below-16-mb-line.

      In my experience, the primary virtual storage concern related to Db2 threads does not have to do with DBM1; rather, it has to do with the extended common service area, or ECSA. The effect of threads on Db2 ECSA usage is documented on this page in the Db2 12 documentation online: https://www.ibm.com/docs/en/db2-for-zos/12?topic=zos-common-service-area-storage-requirements#db2z_calcecsastgreq.

      As for the idea of increasing the number of CICS-Db2 threads in a Db2 system, rather than make that number as large as it CAN be in your environment, I would make it as large as it NEEDS to be. Generally, you want enough CICS-Db2 threads to ensure that transactions will not have to queue up waiting for a Db2 thread because all of the available Db2 threads for the CICS region in question are tied up servicing other transactions. A CICS monitor should be able to inform you as to whether such queuing is happening in your system. Such a monitor generally can show you the high-water mark for concurrently executing Db2-accessing transactions for a given CICS region. If that number is greater than the number of threads available for the region (per specification in DB2ENTRY and DB2CONN resources, as explained in the blog entry, above), there is some queuing going on. If its only a little bit of transaction queuing happening, and that infrequently, probably not a big deal. If there is relatively more queuing happening on a fairly regular basis, you might need somewhat more Db2 threads for the CICS region. Would I ever NOT want to have more Db2 threads for a CICS region, even if I see more transaction queuing than I'd like? Perhaps, if the z/OS LPAR's general-purpose processors are running at a really high rate of utilization during times of CICS transaction queuing. In such a situation, I might leave the number of threads as-is, out of concern that allowing more CICS-Db2 transactions to execute concurrently (by providing more Db2 threads for those transactions) could cause a general-purpose CPU utilization rate that is already high to go so high as to really negatively impact application throughput and performance.

      One more thing: if you do provide more threads for a CICS-Db2 workload through CICS DB2ENTRY and/or DB2CONN parameter value changes, keep in mind that you might also need to increase the value of the Db2 ZPARM parameter CTHREAD (see https://www.ibm.com/docs/en/db2-for-zos/12?topic=1-max-users-field-cthread-subsystem-parameter).