Entries in resource control table—DSNCRCT TYPE=ENTRY

The TYPE=ENTRY form of the macro defines overrides to values set in the TYPE=POOL definition and provides dedicated threads to a transaction or group of transactions.

The plan name identifies the DB2® resource being accessed by a CICS® application. A dynamic plan exit program is a way of allocating plans to CICS dynamically at execution time. For more information about dynamic plan exit programs, see the CICS DB2 Guide. In entry threads, all the transactions assigned to the same RCT entry use the plan name or dynamic plan allocation exit program specified for that entry.

Allocation deadlocks might occur if more than one thread is allowed for an RCT entry that uses a plan containing exclusive locking (table space locks). (See the THRDA and TWAIT parameters explanations for more information.)
Read syntax diagramSkip visual syntax diagram
>>-DSNCRCT--TYPE=ENTRY--+------------------------+-------------->
                        |         .-USERID-----. |   
                        '-,AUTH=--+------------+-'   
                                  '-identifier-'     

>--+--------------------+--------------------------------------->
   |           .-HIGH-. |   
   '-,DPMODE=--+------+-'   
               +-EQ---+     
               '-LOW--'     

>--+-----------------------------------------------------+------>
   '-,PLNEXIT=--+-NO--PLAN=plan-name-------------------+-'   
                |                .-DSNCUEXT----------. |     
                '-YES--PLNPGME=--+-------------------+-'     
                                 '-exit-program-name-'       

>--+--------------------+--+------------------+----------------->
   '-,RDONAME=entryname-'  |          .-YES-. |   
                           '-,ROLBE=--+-----+-'   
                                      '-NO--'     

>--+----------------------+--+----------------------+----------->
   |          .-0-------. |  |          .-0-------. |   
   '-,THRDA=--+---------+-'  '-,THRDM=--+---------+-'   
              '-integer-'               '-integer-'     

>--+----------------------+--+-------------------+-------------->
   |          .-0-------. |  '-,TOKENE=--+-YES-+-'   
   '-,THRDS=--+---------+-'              '-NO--'     
              '-integer-'                            

>--+-------------------+--+----------------------------+-------><
   |          .-YES--. |  '-,TXID=(transaction-id,...)-'   
   '-,TWAIT=--+------+-'                                   
              +-NO---+                                     
              '-POOL-'                                     

AUTH=identifier
Specifies an explicit character string (authorization ID) or directs the attachment facility to use names associated with the CICS transaction. Permissible values for identifier are:
character-string
Specifies a character string that is used as a DB2 authorization ID. For character-string, substitute a character string of no more than eight characters, except for the reserved words USERID, USER, TERM, TXID, GROUP, and SIGNID.
GROUP
Specifies the RACF® sign-on user ID (1 to 8-character USERID) and the connected group name as the authorization ID. The following table shows how these two values are interpreted by DB2.
IDs passed to DB2 How DB2 interprets values
CICS sign-on user ID (USERID) Represents the primary DB2 authorization ID.
RACF connected group name If the RACF list of group options is not active, then DB2 uses the connected group name supplied by the CICS attachment facility as the secondary DB2 authorization ID. If the RACF list of group options is active, DB2 ignores the connected group name supplied by the CICS attachment facility, but the value appears in the DB2 list of secondary DB2 authorization IDs.

To use the GROUP option, the CICS system must have SEC=YES specified in the CICS system initialization table (SIT).

If no RACF group ID is available for this USERID, then an 8-character field of blanks is passed to DB2 as the group ID.

SIGNID
Specifies that the value specified for SIGNID on the TYPE=INIT macro is to be used as the authorization ID.
TERM
Specifies the terminal identification (four characters padded to eight) as an authorization ID. An authorization ID cannot be obtained in this manner if a terminal is not connected with the transaction.

If a transaction is started (using a CICS command) and has no terminal associated with it, the AUTH=TERM parameter should not be used.

TXID
Specifies the transaction ID (four characters padded to eight) as the authorization ID.
USER
Specifies the operator identification associated with the userid that is associated with the CICS transaction as the authorization ID (three characters padded to eight).
USERID
Specifies the 8-character USERID associated with the CICS transaction as the authorization ID.

When the sample sign-on exit DSN3@SGN is used with AUTH=USERID, the exit sends the user ID to DB2 as the primary authorization ID and the RACF group ID to DB2 as the secondary ID. When the sample sign-on exit is used, there is no difference between AUTH=USERID and AUTH=GROUP.

Default: USERID

DPMODE=HIGH|EQ|LOW
Specifies the priority of thread subtasks relative to CICS main task priority.
HIGH
Specifies that subtasks can attain a higher priority than the CICS main task from which the subtask was generated. Use this option for high priority and high volume transactions.
EQ
Specifies that CICS must allow for subtasks to attain equal priority.
LOW
Specifies that subtasks have a lower priority than the CICS main task priority.
PLNEXIT=NO|YES
Specifies whether a dynamic plan allocation exit program is invoked. For more information on dynamic plan allocation, see the CICS DB2 Guide.
NO
Specifies that this transaction ID entry does not use a plan exit. The CICS attachment facility obtains the plan name using the name specified on the option PLAN=. Specifying NO means you must code the option PLAN=plan-name.
YES
Specifies that this transaction ID can dynamically allocate the plan name when the first SQL statement is processed for the application program. This is accomplished by means of the dynamic plan exit specified on the option PLNPGME=. Specifying YES means you must NOT code the option PLAN=.
PLAN=plan-name
Specifies the plan ID to be associated with this transaction when it is different from the transaction ID. For plan-name, substitute a valid application plan name.

The PLAN ID specified with a TYPE=ENTRY macro is used even if the POOL provides the thread. The PLAN parameter is a required parameter when the TXID parameter is coded as a list of two or more transaction IDs.

If PLAN= is not specified and PLNEXIT=NO, TXID is the default plan if only one transaction is specified on the TXID keyword. See the description of the TXID parameter.

PLNPGME=exit-program-name
Specifies the name of the exit program this entry uses. The default is set by the PLNPGMI parameter on the TYPE=INIT statement. For information on how to write your own exit program, see the CICS DB2 Guide.
RDONAME=entryname
Specifies the name to be used for the DB2ENTRY (and DB2TRAN if one transid is present) when migrating this RCTE to the CSD.
ROLBE=YES|NO
Specifies a disposition for transactions defined by this entry if a transaction is selected by DB2 as the victim in a deadlock resolution. The specification of ROLBE overrides the specification of the ROLBI parameter on the TYPE=INIT macro.
YES
Specifies that the attachment facility is to issue a syncpoint rollback before returning control to the application. A SQL return code of -911 is returned to the program. Specifying YES provides compatibility with SQL/DS.
NO
Specifies that the attachment facility is not to initiate a rollback for this transaction. A SQL return code of -913 is returned to the application.
THRDA=integer
Specifies the maximum number of threads that the attachment facility allows connected for this transaction, group, or pool before requests are either made to wait or are diverted to the pool. (See the description of the TWAIT parameter.)

For integer, substitute a value that does not exceed 99 or the THRDM value. The general restriction is (THRDS ≤ THRDA ≤ THRDM ≤ 99). When THRDA=0, TWAIT=YES or TWAIT=POOL causes all threads to be diverted to the pool. Forcing low-use transactions into the pool this way might save MVS™ ATTACH overhead if pool threads are available.

If a plan specified for an RCT entry has exclusive locking, set the value of the THRDA parameter to 1 and the value of the TWAIT parameter to YES to prevent allocation deadlock.

For information about using threads in conjunction with dynamic plan selection, see the CICS DB2 Guide.

Default: 0

THRDM=integer
Specifies the maximum number of threads the attachment facility is prepared to connect for this transaction group. For integer, substitute an integer value that does not exceed 99. The general restriction is (THRDS ≤ THRDA ≤ THRDM ≤ 99).

You can associate a CICS transaction with a plan name without allocating it to an entry thread by specifying no threads (THRDM=0) and overflow to the pool (TWAIT=POOL). The entry thread uses the plan name associated with its TYPE=ENTRY parameter when it overflows to the pool.

For information about using threads in conjunction with dynamic plan selection, see the CICS DB2 Guide.

Default: 0

THRDS=integer
specifies the maximum number of protected threads. For integer, substitute a value that does not exceed the THRDA value or 99. The general restriction is (THRDS ≤ THRDA ≤ THRDM ≤ 99).

A thread released by a transaction when no other work is queued can be protected. It will not be terminated immediately. A protected thread is terminated only after two complete purge cycles if it has not been reused in the meantime. The purge cycle is specified using the PURGEC parameter of the TYPE=INIT statement.

Threads are protected only while they are inactive. If a transaction reuses a protected thread, the thread becomes active and the current number of protected threads is decremented.

For information about using threads in conjunction with dynamic plan selection, see the CICS DB2 Guide.

Default: 0

TOKENE=NO|YES
Specifies whether the CICS attachment facility produces a DB2 accounting record for every CICS transaction, even those transactions that are reusing threads. It also specifies whether the CICS attachment facility passes the CICS LU6.2 (protected) token to DB2 for inclusion in the DB2 accounting trace records. You might receive more than one DB2 accounting record for a CICS transaction that has more than one DB2 unit of recovery, but you can correlate the CICS and DB2 records with the matching LU6.2 tokens.

Because CICS produces accounting records on a transaction basis, and DB2 produces accounting records on a thread basis, it can be difficult to correlate the two. This parameter gives you the option of producing a DB2 accounting record for each CICS transaction, even for transactions that are reusing threads.

If you do not specify YES or NO for TOKENE, then it assumes the value specified in TOKENI on the TYPE=INIT statement.

YES
Specifies that the CICS attachment facility requests that DB2 (using SIGNON) produce an accounting record after each transaction. It also indicates that the attachment facility passes the CICS LU6.2 token to DB2 for inclusion in the DB2 accounting trace records. Specifying YES makes it easier to correlate DB2 and CICS accounting and trace records.

Specifying YES slightly increases the overhead of a SQL request that reuses threads because of additional SIGNON activity. In a thread reuse situation, the transaction rate can degrade by no more than 5%. For additional information on the CICS task scope and DB2 thread scope, see Volume 2 of the DB2 Administration Guide.

NO
Specifies that the CICS attachment facility does not produce a DB2 accounting record during thread reuse. When TOKENE=NO is specified, it is more difficult to correlate DB2 and CICS accounting and trace records.
TWAIT=YES|NO|POOL
Specifying TWAIT overrides the value of the TWAITI parameter on the TYPE=INIT macro.
YES
Specifies that, if all threads are busy, a transaction must wait until one becomes available. A transaction can wait as long as CICS allows it to wait, generally until a thread becomes available.

The number of transactions waiting can be limited by using a TRANCLASS.

If TWAIT=YES is specified with THRDA=0, the attachment facility routes the transaction to the pool. Otherwise, a DB2 transaction could wait indefinitely for a thread.

An alternative to using TRANCLASS is to use TWAIT=POOL. The task picks up a pool thread rather than waiting for an entry thread to become available.

NO
Specifies that, if all threads are busy, a transaction is terminated with an abend. If NO is specified, or if TWAIT=NO has been specified on the TYPE=POOL macro, you should closely coordinate the number of threads specified with the MAXACTIVE number on the TRANCLASS being used. This helps to prevent abends when threads are unavailable.
POOL
Specifies that, if all threads are busy, a transaction must be diverted to use the pool of threads. If the pool is also busy, and NO has been specified for the TWAIT parameter on the TYPE=POOL form of the macro, a transaction is terminated with an abend. See the description of the TWAIT=NO parameter.
TXID=(transaction-ID)
Specify the transaction identification, or identifications for this entry. For transaction ID, substitute the transaction identifications found in the CSD transaction definition. The way you code this option depends on how many transactions you have and on whether:
  • You have different plans for each transaction.
  • You want to use dynamic plan allocation.
  • You want separate statistics for each transaction.
For example:
  1. If you have several transactions that use the same plan, you can code a list of transaction IDs, to be indexed to the same RCT entry. Code your entry as in this example:
    DSNCRCT TYPE=ENTRY,TXID=(TXI1,TXI2,TXIn),
             PLAN=(PLNA)
    You cannot code more than one plan per entry. To specify a different plan for each transaction, you must code a separate DSNCRCT entry for each plan, as follows:
    DSNCRCT TYPE=ENTRY,TXID=(TXI1),PLAN=(PLNA)
    DSNCRCT TYPE=ENTRY,TXID=(TXI2),PLAN=(PLNB)
    DSNCRCT TYPE=ENTRY,TXID=(TXIn),PLAN=(PLNC)
  2. With dynamic plan selection, DB2 selects a plan based on the DBRM of the first SQL statement, or based on a user-defined exit routine for dynamic plan selection. You can use the PLNEXIT and PLNPGME parameters to specify a user-defined exit routine.
    To use dynamic plan selection for your transactions, code one or more transactions per entry, and optionally add pointers to the PLNEXIT and PLNPGME parameters, as follows:
    DSNCRCT TYPE=ENTRY,TXID=(TXI1,TXI2,TXIn),
             PLNEXIT=YES
     
    or
     
    DSNCRCT TYPE=ENTRY,TXID=(TXI1),PLNEXIT=YES
    DSNCRCT TYPE=ENTRY,TXID=(TXI2),PLNEXIT=YES
    DSNCRCT TYPE=ENTRY,TXID=(TXI3),PLNEXIT=YES
  3. If you want separate CICS attachment facility statistics for each transaction, you must code a separate entry for each transaction, as in this example:
    DSNCRCT TYPE=ENTRY,TXID=(TXI1)
    DSNCRCT TYPE=ENTRY,TXID=(TXI2)
    DSNCRCT TYPE=ENTRY,TXID=(TXIn)