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.)

>>-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:
- 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)
- 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
- 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)