SET DB2ENTRY

Sets the attributes of a particular DB2ENTRY used to define resources to be used by a specific transaction or by a group of transactions when accessing DB2®.

SET DB2ENTRY

Read syntax diagramSkip visual syntax diagramSET DB2ENTRY (data-area) ACCOUNTREC(cvda)UOWTASKTXIDNONEAUTHID(data-area)AUTHTYPE(cvda)GROUPSIGNTERMTXOPIDUSERIDBUSY(cvda)WAITNOWAITFORCEDISABLEDACT(cvda)ABENDSQLCODEPOOLENABLESTATUS(cvda)ENABLEDDISABLEDPLAN(data-area)PLANEXITNAME(data-area)PRIORITY(cvda)HIGHEQUALLOWPROTECTNUM(data-area)THREADLIMIT(data-area)THREADWAIT(cvda)TWAITNOTWAITTPOOL

Conditions: NOTAUTH, NOTFND, INVREQ

This command is threadsafe.

For more information about the use of CVDAs, see CICS-value data areas (CVDAs).

Description

The entry is identified by the name it was defined with in CEDA.

Options

ACCOUNTREC
Specifies the minimum amount of DB2 accounting required for transactions using pool threads. The specified minimum may be exceeded as described in the following options. CVDA values are:
NONE
No accounting records are required for transactions using pool threads.

DB2 produces at least one accounting record for each thread when the thread is terminated. Authorization changes additionally cause accounting records to be produced.

TXID
The CICS DB2 attachment facility causes an accounting record to be produced when the transid using the thread changes.

Because pool threads are typically used by a number of different transaction IDs, there is an increased chance that a transaction containing multiple units of work (UOWs) will use a different thread for each UOW (assuming the thread is released at syncpoint). In this case an accounting record may be produced per UOW.

TASK
The CICS DB2 attachment facility causes a minimum of one accounting record for each CICS task to be produced.

A transaction containing multiple UOWs (assuming the thread is released at syncpoint) may use a different thread for each of its UOWs. The result may be an accounting record produced for each UOW.

UOW
The CICS DB2 attachment facility causes an accounting record to be produced for each UOW, assuming that the thread is released at the end of the UOW.
AUTHID
specifies the id to be used for security checking when using this DB2ENTRY. If AUTHId is specified, AUTHTYpe may not be specified.
AUTHTYPE
returns the type of id that can be used for security checking when using this DB2ENTRY. If AUTHTYpe is specified, AUTHid may not be specified. CVDA values are:
GROUP
Specifies the 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, 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 RACF external security SEC=YES specified in the CICS system initialization table (SIT).

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

SIGN
Specifies the SIGNID parameter of the DB2CONN should be used as the resource 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, AUTHTYPE(TERM) should not be used.

TX
Specifies the transaction identification (four characters padded to eight) as the authorization ID.
OPID
The operator identification associated with the CICS transaction is used as the authorization ID (three characters padded to eight).
USERID
The 8-character USERID associated with the CICS transaction is used as the authorization ID.

When the DB2 sample sign-on exit DSN3@.SGN is used with AUTHTYPE(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 AUTHTYPE(USERID) and AUTHTYPE(GROUP).

BUSY(Cvda)
specifies what CICS is to do if a SET DB2ENTRY DISABLED is issued and the entry is busy when the set command is issued. CVDA values are:
WAIT
CICS must wait for all activity on the DB2ENTRY to be quiesced before setting the DB2ENTRY disabled. CICS then returns control to the application.

Note that when a DB2ENTRY is quiescing, all existing transactions are allowed to complete. Transactions already queued against the entry are also allowed to complete. New transactions that try to access the DB2ENTRY are routed to the POOL, or abended, or sent a SQLCODE depending on the setting of DISABLEDACT.

NOWAIT
is the same as WAIT except that control returns to the application as soon as the SET DISABLED request is queued.
FORCE
all tasks using the DB2ENTRY, and those queued against the DB2ENTRY are forcepurged. The DB2ENTRY is then DISABLED and control returns to the application.
DISABLEDACT
specifies what CICS is to do with new transactions that access a DB2ENTRY when it has been disabled or disabling. CVDA values are:
POOL
The CICS DB2 attachment facility routes the request to the pool. Message DFHDB2072 is sent to the transient data destination specified by MSGQUEUEn on the DB2CONN for each transaction routed to the pool.
ABEND
The CICS DB2 attachment facility abends the transaction.The abend code is AD26.
SQLCODE
An SQLCODE is returned to the application indicating that the DB2ENTRY is disabled.
ENABLESTATUS(cvda)
specifies whether the DB2ENTRY can be accessed by applications. CVDA values are:
ENABLED
The DB2ENTRY can be accessed by applications.
DISABLED
The DB2ENTRY cannot be accessed by applications. A DB2ENTRY has to be disabled before it can be reinstalled or discarded.
PLAN
specifies the name of the plan to be used for this DB2ENTRY.

If PLAN is specified, PLANEXITNAME cannot be specified.

PLANEXITNAME
specifies the name of the dynamic plan exit to be used for this DB2ENTRY. If you change the PLAN and PLANExitname while there are active transactions for the DB2ENTRY the next time the transaction releases the thread, the plan/exit is determined using the new rules. If PLANExitname is specified, PLAN cannot be specified.
PRIORITY
specifies the priority of the thread TCBs for this DB2ENTRY relative to the CICS main TCB (QR TCB). The thread TCBs are CICS open L8 TCBs. CVDA values are:
HIGH
Thread TCBs have a higher priority than the CICS QR TCB.
EQUAL
Thread TCBs have equal priority with the CICS QR TCB.
LOW
Thread TCBs have a lower priority than the CICS QR TCB.
PROTECTNUM
specifies the maximum number of protected threads for this DB2ENTRY.
THREADLIMIT
specifies the maximum number of threads for this DB2ENTRY that the CICS DB2 attachment allows active before requests are made to wait or are rejected.
THREADWAIT
specifies whether or not transactions should wait for a DB2ENTRY thread, be abended, or overflow to the pool should the number of active DB2ENTRY threads reach the THREADLimit number. CVDA values are:
TWAIT
If all threads are busy, a transaction waits until one becomes available.
NOTWAIT
If any threads are busy, a transaction is terminated with an abend code AD2P.
TPOOL
If all threads are busy, the transaction is diverted to use the pool of threads. If the pool is also busy, and NOTWAIT has been specified for the THREADWAIT parameter on the DB2CONN. The transaction is terminated with abend code AD3T.
Notes:
  1. When you change the value of AUTHId or AUTHType, a surrogate user security check is invoked if security is active. This ensures that the userid under which SET is being executed is authorized to act on behalf of the userid being set.
  2. All parameters on SET DB2ENTRY can be set while the CICS DB2 attachment is active and the transactions are active.

Conditions

NOTAUTH
The user associated with the issuing task is not authorized to use this command, or is not authorized to access this resource.
RESP2 values:
100
Command authorization failure
101
Resource authorization failure
102
Surrogate authorization failure
103
Authtype authorization failure
NOTFND
RESP2 values:
1
There is no DB2ENTRY currently installed with the specified name.
INVREQ
RESP2 values:
2
Invalid action value
3
Invalid Authtype value
4
Invalid busy value
5
Invalid enablestatus value
7
Invalid priority value
8
Invalid Threadwait value
9
Bad characters in Authid
10
Bad characters in Plan
11
Bad characters in Planexitname
12
Both Authid and Authtype specified
13
Both Plan and Planexitname specified
14
Entry is disabling
15
Protectnum greater than Threadlimit or protectnum < 0 or protectnum > 2000
16
Threadwait must be tpool with Threadlimit=0
17
Threadlimit > 2000 or Threadlimit < 0 or Threadlimit > TCBLIMIT
18
Invalid Accountrec value
19
SET DISABLED when the FORCE or WAIT option has been specified, but this transaction is itself using the DB2ENTRY.