SET DB2CONN
Change information about the attributes of the CICS® DB2® Connection.
Conditions: NORMAL, NOTAUTH, NOTFND, INVREQ
This command is threadsafe.
For more information about the use of CVDAs, see CICS-value data areas (CVDAs).
Description
The SET DB2CONN command also specifies the attributes of the pool and command threads.
Restriction: This command cannot be used in a remote program
that is linked by a distributed program link command.
Options
- ACCOUNTREC(cvda)
- Specifies the minimum amount of DB2 accounting
required for transactions using pool threads. The specified minimum
can 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 transaction ID that is 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) uses a different thread for each UOW (assuming that the thread is released at sync point). In this case an accounting record can 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 that the thread is released at sync point) can use a different thread for each of its UOWs. The result can 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(data-value)
- Specifies, as an 8-character name, what ID should be used for security checking for pool threads. If AUTHID is specified, AUTHTYPE cannot be specified.
- AUTHTYPE(cvda)
- Specifies the type of ID that can be used for pool threads. If
AUTHTYPE is specified AUTHID cannot be specified. CVDA values are:
- GROUP
- Specifies the 8-character user ID 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 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 userid that is associated with the CICS transaction is used as the authorization ID (three characters padded to eight).
- USERID
- The 8-character user ID 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)
- This parameter is valid only with CONNECTST when setting the CICS DB2 connection
NOTCONNECTED. CVDA values are:
- FORCE
- This is like issuing DSNC STOP FORCE; that is, any CICS transactions currently using DB2 are abnormally terminated, and the CICS DB2 attachment facility is stopped. FORCE is mutually exclusive to WAIT and NOWAIT.
- NOWAIT
- Makes the request asynchronous in nature. Control is returned before the request is complete. NOWAIT is mutually exclusive to WAIT and FORCE.
- WAIT
- The request is synchronous in nature. Control is only returned
when the request is complete. WAIT is mutually exclusive to NOWAIT
and FORCE.
A SET DB2CONN NOTCONNECTED WAIT|NOWAIT is a quiesce stop of the CICS DB2 interface. The quiesce waits for existing transactions to finish before stopping the interface. WAIT is the default value.
- COMAUTHID(data-value)
- Specifies, as an 8-character name, which ID should be used for security checking when using command threads. If COMAUTHID is specified, COMAUTHTYPE cannot be specified.
- COMAUTHTYPE(cvda)
- Specifies the type of ID that can be used for security checking
when using command threads. If COMAUTHTYPE is specified, COMAUTHID
cannot be specified. CVDA values are:
- CGROUP
- Specifies the 8-character user ID 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 CGROUP 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, an 8-character field of blanks is passed to DB2 as the group ID.
- CSIGN
- Specifies the SIGNID parameter of the DB2CONN should be used as the resource authorization ID.
- CTERM
- 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 COMAUTHTYPE(TERM) should not be used.
- CTX
- Specifies the transaction identification (four characters padded to eight) as the authorization ID.
- COPID
- The operator identification associated with the user ID that is associated with the CICS transaction sign-on facility is used as the authorization ID (three characters padded to eight).
- CUSERID
- The 8-character user ID 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 USERID 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 COMAUTHTYPE(CUSERID) and COMAUTHTYPE(CGROUP).
- COMTHREADLIM(data-value)
- Specifies, as a fullword binary value, the current maximum number of command threads that the CICS DB2 attachment allows to be active before requests overflow to the pool.
- CONNECTERROR(cvda)
- If CICS is not connected
to DB2 because the adapter is
in standby mode, describes how this is reported back to an application
that has issued a SQL request. CVDA values are:
- ABEND
- The application is stopped with abend code AEY9.
- SQLCODE
- The application receives a -923 SQLCODE.
- CONNECTST(cvda)
- Sets the status of the CICS DB2 connection; that is whether,
to start or stop the CICS DB2 connection. CVDA values are:
- CONNECTED
- This is equivalent to issuing DSNC STRT to start the CICS DB2 attachment. If the requested DB2 subsystem is active, control returns when CICS and DB2 have been connected. If the requested DB2 subsystem is not active, the response returned is dependent on the setting of STANDBYMODE: If DB2 is not initialized, and STANDBYMODE(NOCONNECT) is specified on the DB2CONN, INVREQ, and RESP2=39 is returned. If you specify STANDBYMODE(CONNECT) or STANDBYMODE(RECONNECT), NORMAL with RESP2=38 is returned indicating that the CICS DB2 attachment is in standby mode and connects to DB2 as soon as it becomes active.
- NOTCONNECTED
- NOTCONNECTED with NOWAIT means initiate quiesce stop of the connection, but return control immediately. NOTCONNECTED WAIT means that control does not return to the application until the CICS DB2 attachment has been stopped. NOTCONNECTED FORCE force stops the connection by force purging transactions currently using DB2. Control is not returned until the connection is stopped.
- DB2GROUPID(data-value)
- Specifies the 4-character name of a data sharing group of DB2 subsystems. CICS attempts to connect to any active member
of this group, using group attach. With DB2 Version
10, the 4-character name can be a subgroup name identifying a subset
of the data sharing group.
DB2GROUPID can only be changed when CICS is not connected to a DB2 system. Specifying a DB2GROUPID causes the DB2ID in the installed DB2CONN definition to be blanked out. If an individual subsystem's DB2ID is specified in a CEMT or EXEC CICS SET DB2CONN command, or in a DSNC STRT command, this overrides any DB2GROUPID that is set in the installed DB2CONN definition. The DB2GROUPID is blanked out, and must be set again (using CEDA or a SET DB2CONN command) to use group attach. Also note that you cannot set a DB2GROUPID and a DB2ID in the same command — this causes the command to fail.
- DB2ID(data-value)
- Specifies the 4-character name of the DB2 subsystem that the CICS DB2 attachment should connect to. DB2ID can only be changed when CICS is not connected to a DB2 system. Specifying a DB2ID causes the DB2GROUPID in the installed DB2CONN definition to be blanked out, and the DB2GROUPID must be set again to use group attach. If a DB2GROUPID is specified in a CEMT or EXEC CICS SET DB2CONN command, this overrides any DB2ID that is set in the installed DB2CONN definition, and the DB2ID is blanked out. Also note that you cannot set a DB2ID and a DB2GROUPID in the same command — this causes the command to fail.
- MSGQUEUE1(data-value)
- Specifies, as a 4-character name, the first transient data destination to which unsolicited messages from the CICS DB2 attachment are sent.
- MSGQUEUE2(data-value)
- Specifies, as a 4-character name, the second transient data destination to which unsolicited messages from the CICS DB2 attachment are sent.
- MSGQUEUE3(data-value)
- Specifies, as a 4-character name, the third transient data destination to which unsolicited messages from the CICS DB2 attachment are sent.
- NONTERMREL(cvda)
- Specifies whether non-terminal transactions release threads for
reuse at intermediate sync points. CVDA values are:
- RELEASE
- Non-terminal transactions release threads for reuse at intermediate sync points.
- NORELEASE
- Non-terminal transactions do not release threads for reuse at intermediate sync points.
- PLAN(data-value)
- Specifies the 8-character name of the plan to be used for all threads in the pool. If PLAN is specified, PLANEXITNAME cannot be specified.
- PLANEXITNAME(data-value)
- Specifies the 8-character name of the dynamic plan exit to be used for pool threads. If you change the PLAN and PLANExitname while there are active transactions for the pool, 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(cvda)
- Specifies the priority of the pool thread TCBs 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.
- PURGECYCLEM(data-value)
- Specifies, as a fullword binary value, the number of minutes (in the range 00 - 59) in the protected thread purge cycle time. Use this parameter in conjunction with PURGECYCLES.
- PURGECYCLES(data-value)
- Specifies, as a fullword binary value, the number of seconds (in
the range 00 - 59) in the protected thread purge cycle time. Use this
parameter in conjunction with PURGECYCLEM. The minimum protected
thread purge cycle time is 5 seconds and the default is 30 seconds.
A protected thread is not terminated immediately when it is released. It is terminated only after two completed purge cycles, if it has not been reused in the meantime. For example, if the protected thread purge cycle is set to 30 seconds, a protected thread is purged 30 - 60 seconds after that thread is released. An unprotected thread is terminated when it is released (at sync point or end of task) if there are no other transactions waiting for a thread on that DB2ENTRY.
- RESYNCMEMBER(cvda)
- This applies only if you are using group attach, and specifies
the strategy that CICS adopts
if outstanding units of work are being held for the last DB2 data sharing group member to which CICS was connected. (Units of work
which are shunted indoubt are not included in this process, because CICS itself is unable to resolve
those units of work at this time. Resynchronization for those UOWs
occurs when CICS has resynchronized
with its remote coordinator.) CVDA values are:
- RESYNC
- CICS connects to the same DB2 data sharing group member to resynchronize the outstanding units of work.
- NORESYNC
- CICS makes one attempt to connect to the same DB2 data sharing group member, and if that attempt fails, CICS connects to any member of the DB2 data sharing group and issues a warning about the outstanding units of work.
- REUSELIMIT(data-value)
- Specifies, as a fullword binary value, a value in the range 0
- 10000 representing the maximum number of times a thread can be reused
before it is terminated. The default is 1000. A value of 0 means that
there is no limit on the number of times that a thread can be reused.
The reuse limit applies to unprotected threads both in the pool and on a DB2ENTRY, and to protected DB2ENTRY threads.
- SECURITY(REBUILD)
- Specifies that the CICS DB2 attachment should force all
existing threads to signon again at the next thread reuse. It should
be used when RACF profiles
have been updated by issuing the following commands:
- CEMT PERFORM SECURITY REBUILD for RACF 1.9.2 or earlier
- TSO SETROP TS RACLIST(xxxxxxxx) REFRESH for RACF 2.1 or later
- SIGNID(data-value)
- Specifies the 8-character authorization ID to be used by the CICS DB2 attachment when signing on to DB2 for pool and DB2ENTRY threads specifying AUTHTYPE(SIGN), and command threads specifying COMAUTHTYPE(CSIGN).
- STANDBYMODE(cvda)
- Specifies the action to be taken by the CICS DB2 attachment
if DB2 is not active when an
attempt is made to start the connection from CICS to DB2.
CVDA values are:
- NOCONNECT
- The CICS DB2 attachment should terminate.
- CONNECT
- The CICS DB2 attachment goes into standby mode to wait for DB2.
- RECONNECT
- The CICS DB2 attachment goes into standby mode and waits for DB2. Having connected to DB2, if DB2 later fails the CICS DB2 attachment reverts again to standby mode and then reconnects to DB2 when it comes up again.
- STATSQUEUE(data-value)
- Specifies the 4-character transient data destination for CICS DB2 attachment statistics produced when the CICS DB2 attachment is shut down.
- TCBLIMIT(data-value)
- Specifies, as a fullword binary value, the maximum number of TCBs that can be used to process DB2 requests. CICS uses open TCBs to process DB2 requests. The TCBLIMIT attribute of the DB2CONN definition governs how many of the open TCBs can be used to access DB2; that is, how many of them can identify to DB2 and create a connection into DB2.
- THREADLIMIT(data-value)
- Specifies, as a fullword binary value, the current maximum number of pool threads the CICS DB2 attachment allows active before requests are made to wait or are rejected according to the THREADWAIT parameter.
- THREADWAIT(cvda)
- Specifies whether transactions should wait for a pool thread or
be abended if the number of active pool threads reach the THREADLIMIT
number. The CICS DB2 attachment issues a unique abend code AD3T, and message DFHDB2011 when THREADWAIT=NO is coded and the number of pool threads is exceeded. CVDA values are:
- TWAIT
- 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.
- NOTWAIT
- If all threads are busy the transaction is terminated with an abend code AD3T.
Notes:
- When you change the value of AUTHID, AUTHTYPE, COMAUTHID, COMAUTHTYPE, or SIGNID, a surrogate user security check is invoked if security is active. This ensures that the user ID associated with the task is authorized to act on behalf of the user ID being set.
- When you issue a SET DB2CONN CONNECTST (NOTCONNECTED) command to stop the CICS-DB2 connection the CEX2 internal CICS DB2 transaction is also shut down, and, if security is active, a started transaction resource security check is invoked. This ensures that the user ID associated with the task is authorized to manipulate the CEX2 transaction. This is achieved by cancelling its timer, which causes it to shut down.
- When the SET DB2CONN command is specified all parameters except DB2ID (the connected subsystem) and DB2GROUPID (the group of data sharing DB2 subsystems of which the connected subsystem is a member) can be set when the CICS DB2 attachment is active. DB2ID and DB2GROUPID can only be changed by stopping and restarting the attachment.
- If you change the PLAN and PLANEXITNAME while there are active transactions for that entry, or the pool, the next time the transaction releases the thread, the plan, or exit is determined using the new rules.
Conditions
- NORMAL
- RESP2 values:
- 38
- Waiting for DB2 (this can occur following a CONNECTST with a CVDA of CONNECT)
- 55
- Temporarily connected to a DB2 restart-light member for resynchronization purposes only
- 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
- 102
- Surrogate authorization failure
- 103
- Authtype authorization failure
- 104
- DB2 authorization failure - the CICS region userid is not authorized to connect to DB2
- NOTFND
- RESP2 values:
- 1
- There is no DB2CONN currently installed.
- INVREQ
- RESP2 values:
- 1
- Invalid ACCOUNTREC value
- 2
- Invalid AUTHTYPE value
- 3
- Invalid BUSY value
- 4
- Invalid COMAUTHTYPE value
- 5
- Invalid CONNECTERROR value
- 6
- Invalid CONNECTST value
- 7
- Invalid NONTERMREL value
- 9
- Invalid PRIORITY value
- 10
- Invalid SECURITY value
- 11
- Invalid STANDBYMODE value
- 12
- Invalid THREADWAIT value
- 13
- Bad characters in AUTHID
- 14
- Bad characters in COMAUTHID
- 15
- Bad characters in DB2ID
- 16
- Bad characters in MSGQUEUE1
- 17
- Bad characters in MSGQUEUE2
- 18
- Bad characters in MSGQUEUE3
- 19
- Bad characters in PLAN
- 20
- Bad characters in PLANEXITNAME
- 21
- Bad characters in SIGNID
- 22
- Bad characters in STATSQUEUE
- 23
- Both AUTHID and AUTHTYPE specified
- 24
- Both COMAUTHID and COMAUTHTYPE specified
- 25
- STANDBYMODE(NOCONNECT) and CONNECTERROR(SQLCODE) specified or CONNECTERROR(SQLCODE) specified when STANDBYMODE is NOCONNECT.
- 26
- Both PLAN and PLANEXITNAME specified.
- 27
- Invalid ACCOUNTREC value
- 28
- COMTHREADLIM exceeds TCBLIMIT or COMTHREADLIM > 2000 or COMTHREADLIM < 0
- 29
- Purge cycle too low; that is, < 30 seconds
- or Purge cycle minutes < 0
- or Purge cycle seconds < 0
- or Purge cycle minutes > 59
- or Purge cycle seconds > 59
- 32
- Tcblimit > 2000 or Tcblimit < 4
- 33
- Threadlimit exceeds tcblimit or Threadlimit > 2000 or Threadlimit < 3
- 34
- Already connected
- 39
- DB2 not active
- 40
- Insufficient authorization
- 41
- Connection error
- 42
- Invalid init parms
- 43
- DB2ID cannot be set, connection active
- 44
- DB2CONN partially discarded
- 46
- SET NOTCONNECTED when the FORCE or WAIT option has been specified, but this transaction is itself using the CICS DB2 interface.
- 47
- Bad characters in DB2GROUPID
- 48
- Both DB2ID and DB2GROUPID specified
- 49
- DB2GROUPID cannot be set, connection active
- 50
- DB2 module DSNAPRH cannot be found
- 51
- TCBLIMIT > MAXOPENTCBS (when connected to DB2 Version 6 or later)
- 52
- DB2GROUPID not found
- 53
- DB2ID not found
- 54
- Invalid RESYNCMEMBER option
- 57
- REUSELIMIT > 10000 or REUSELIMIT < 0