INQUIRE DB2CONN

Defines the attributes of the connection made between CICS and DB2.

Read syntax diagramSkip visual syntax diagramINQUIRE DB2CONN
 
                    .-----------------------------.
                    V                             |
>>-INQUIRE DB2CONN----+-ACCOUNTREC(cvda)--------+-+------------><
                      +-AUTHID(data-area)-------+
                      +-AUTHTYPE(cvda)----------+
                      +-COMAUTHID(data-area)----+
                      +-COMAUTHTYPE(cvda)-------+
                      +-COMTHREADLIM(data-area)-+
                      +-COMTHREADS(data-area)---+
                      +-CONNECTERROR(cvda)------+
                      +-CONNECTST(cvda)---------+
                      +-DB2GROUPID(data-area)---+
                      +-DB2ID(data-area)--------+
                      +-DB2RELEASE(data-area)---+
                      +-DROLLBACK(cvda)---------+
                      +-MSGQUEUE1(data-area)----+
                      +-MSGQUEUE2(data-area)----+
                      +-MSGQUEUE3(data-area)----+
                      +-NONTERMREL(cvda)--------+
                      +-PLAN(data-area)---------+
                      +-PLANEXITNAME(data-area)-+
                      +-PRIORITY(cvda)----------+
                      +-PURGECYCLEM(data-area)--+
                      +-PURGECYCLES(data-area)--+
                      +-RESYNCMEMBER(cvda)------+
                      +-SIGNID(data-area)-------+
                      +-STANDBYMODE(cvda)-------+
                      +-STATSQUEUE(data-area)---+
                      +-TCBLIMIT(data-area)-----+
                      +-TCBs(data-area)---------+
                      +-THREADS(data-area)------+
                      +-THREADERROR(cvda)-------+
                      +-THREADLIMIT(data-area)--+
                      '-THREADWAIT(cvda)--------'
 

Conditions: NOTAUTH, NOTFND

This command is threadsafe.

Description

The INQUIRE DB2CONN command allows you to inquire about attributes of the currently installed DB2CONN which defines the connection to DB2.

Note that because there can be only one DB2CONN installed at a time, the name of the DB2CONN is not required on input.

Options

ACCOUNTREC
returns 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:
UOW
The CICS DB2 attachment facility causes an accounting record to be produced by DB2 for each UOW, assuming that the thread is released at the end of the UOW.
TASK
The CICS DB2 attachment facility causes a minimum of one accounting record to be produced by DB2 for each CICS task.

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 the production of an accounting record for each UOW. For example, an accounting record is produced if a thread terminates after being released, or if a thread is reused but the primary AUTHID is changed.

TXID
The CICS DB2 attachment facility causes an accounting record to be produced by DB2 when the transaction ID 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 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 for each UOW.For example, an accounting record is produced if a thread terminates after being released, or if a thread is reused but the primary AUTHID is changed.

NONE
No accounting records are required for transactions using pool threads.

DB2 nevertheless produces at least one accounting record for each thread when the thread is terminated. Additionally, authorization changes cause accounting records to be produced.

AUTHID
returns an id to be used for security checking when using pool threads. If an AUTHID is returned, AUTHTYPE is not applicable.
AUTHTYPE
returns the type of id to be used for security checking when using pool threads. If an AUTHType is returned, AUTHid is blank. CVDA values are:
GROUP
The 8-character USERID and the connected group name are used 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.

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
The SIGNID parameter of the DB2CONN is used as the resource authorization ID.
TERM
The terminal identification (four characters padded to eight) is used 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
The transaction identification (four characters padded to eight) is used as the authorization ID.
OPID
The user operator identification associated with the userid, 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 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 AUTHTYPE(USERID) and AUTHTYPE(GROUP).

COMAUTHID
returns an ID to be used for security checking when using command threads. If COMAUTHType is returned, COMAUTHid is not applicable.
COMAUTHTYPE
returns the type of ID to be used for security checking when using command threads. If COMAUTHType is returned, COMAUTHid is blank. CVDA values are:
CGROUP
The 8-character USERID and the connected group name are used 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.

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
The SIGNID parameter of the DB2CONN is used as the resource authorization ID.
CTERM
The terminal identification (four characters padded to eight) is used 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, COMAUTHTYPE(CTERM) should not be used.

CTX
The transaction identification (four characters padded to eight) is used as the authorization ID.
COPID
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).
CUSERID
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 COMAUTHTYPE(CUSERID), 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).

COMTHREADS
returns the current number of active command threads.
COMTHREADLIM
returns the current maximum number of command threads the CICS DB2 attachment allows active before requests overflow to the pool.
CONNECTERROR
returns how the fact that CICS is not connected to DB2 because the adapter is in 'standby mode' is reported back to an application that has issued a SQL request. CVDA values are:
ABEND
The application is abended with abend AEY9.
SQLCODE
The application receives a -923 SQLCODE.
CONNECTST
returns the status of the CICS DB2 connection. CVDA values are:
CONNECTED
CICS is connected to DB2.
NOTCONNECTED
CICS is not connected to DB2.
CONNECTING
CICS is currently attempting to connect to DB2.
DISCONNING
CICS is currently disconnecting from DB2.
DB2GROUPID
If you are using group attach, this returns the name of a data sharing group of DB2 subsystems that you have specified. CICS attempts to connect to any active member of this group. If the CICS DB2 attachment is connected, the name of the DB2 subsystem that was chosen from the group appears in the DB2ID field. If CICS is waiting to reconnect to a specific DB2 subsystem within the data sharing group, because it is holding outstanding units of work for that subsystem, the name of the specific DB2 subsystem appears in the DB2ID field, and the status CONNECTING is returned. (For this situation to arise, RESYNCMEMBER(RESYNC) must be specified.)
DB2ID
If you are not using group attach, this returns the name of the DB2 subsystem that the CICS DB2 attachment is connected to, or if the CICS DB2 attachment is not connected, the name of the DB2 subsystem that you have specified for CICS to connect to. If you are using group attach and the CICS DB2 attachment is connected, this returns the name of the DB2 subsystem that the CICS DB2 attachment is connected to. If you are using group attach and the CICS DB2 attachment is not connected, this field is normally blank. However, if CICS is waiting to reconnect to a specific DB2 subsystem, because RESYNCMEMBER(YES) is specified and the DB2 subsystem for which CICS is holding outstanding units of work is unavailable, the command returns the DB2ID of that subsystem with the status CONNECTING.
DB2RELEASE
returns a four-character value indicating the version and release level of the DB2 subsystem CICS is connected to. When CICS is not connected to DB2, blanks are returned.
DROLLBACK
returns a value showing whether the CICS DB2 attachment is to initiate a SYNCPOINT ROLLBACK in the event of a transaction being selected as victim of a deadlock resolution. CVDA values are:
ROLLBACK
the attachment facility issues a sync point rollback before returning control to the application. An SQL return code of -911 is returned to the program.
NOROLLBACK
the attachment facility is not to initiate a rollback for a transaction. An SQL return code of -913 is returned to the application.
MSGQUEUE1
returns the name of the first transient data destination to which unsolicited messages from the CICS DB2 attachment are sent.
MSGQUEUE2
returns the name of the second transient data destination to which unsolicited messages from the CICS DB2 attachment are sent.
MSGQUEUE3
returns the name of the third transient data destination to which unsolicited messages from the CICS DB2 attachment are sent.
NONTERMREL
retuns a value showing whether non-terminal transactions are to release threads for reuse at intermediate syncpoints. CVDA values are:
RELEASE
non-terminal transactions release threads for reuse at intermediate syncpoints.
NORELEASE
non-terminal transactions do not release threads for reuse at intermediate syncpoints.
PLAN
returns the name of the plan used for the pool. If a plan name is returned, PLANEXITNAME is blank.
PLANEXITNAME
returns the name of the dynamic plan exit used for pool threads. If a PLANEXITNAME is returned, PLAN is blank.
PRIORITY
returns the priority of the pool thread TCBs relative to the CICS main TCB (QR TCB). If CICS is connected to DB2 Version 6 or later, the thread TCBs are CICS open L8 TCBs. If CICS is connected to DB2 Version 5 or earlier, the thread TCBs are private TCBs created by the CICS-DB2 Attachment Facility. 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
returns in minutes the length of the protected thread purge cycle. The range for PURGECYCLEM is 0-59.

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. Hence if the purge cycle is set to 30 seconds after it is released, a protected thread is purged 30 - 60 seconds after it is released. An unprotected thread is terminated when it is released (at syncpoint or end of task) if there are no other transactions waiting for a thread on that DB2ENTRY.

PURGECYCLES
returns in seconds the length of the protected thread purge cycle. The range for PUrgecycles is 30-59.

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. Hence if the purge cycle is set to 30 seconds after it is released, a protected thread is purged 30 - 60 seconds after it is released. An unprotected thread is terminated when it is released (at syncpoint or end of task) if there are no other transactions waiting for a thread on that DB2ENTRY.

RESYNCMEMBER
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 will occur when CICS has resynchronized with its remote coordinator.) CVDA values are:
RESYNC
CICS connects to the same DB2 data sharing group member.
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.
If you perform an INQUIRE DB2CONN RESYNCMEMBER command and are not using group attach, a Not Applicable value is returned.
SIGNID
returns the authorization ID to be used by the CICS DB2 attachment when signing on to DB2 for pool and DB2 entry threads specifying AUTHTYPE(SIGN) and command threads specifying COMAUTHTYPE(CSIGN).
STANDBYMODE
returns 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 terminates.
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 subsequently fails the CICS DB2 attachment reverts to standby mode again and subsequently reconnects to DB2 when it comes up again.
STATSQUEUE
returns the transient data destination for CICS DB2 attachment statistics produced when the CICS DB2 attachment is shutdown.
TCBS
returns a number indicating the TCBs currently used by the CICS DB2 attachment facility. The number returned is the number of TCBs that are associated with DB2 connections (command, pool or DB2ENTRY threads), so the interpretation of the number depends on the release of DB2 to which CICS is connected, as follows:
Connected to DB2 Version 5 or earlier (therefore not using the open transaction environment)
Subtask TCBs are created and managed by the CICS DB2 attachment facility to service DB2 requests, and remain permanently associated with DB2 connections (command, pool or DB2ENTRY threads). In this case, the TCBS option returns the high-water mark of TCBs created to access DB2.
Connected to DB2 Version 6 or later (therefore using the open transaction environment)
The TCBs used by the CICS DB2 attachment facility are allocated by CICS from the pool of L8 mode TCBs. A DB2 connection is not permanently assigned to the same L8 TCB, and between CICS tasks, it can move from one L8 mode TCB to another. In this environment, the TCBS option returns the number of L8 mode TCBs that are using a DB2 connection at the time of the inquiry, and this value varies depending on workload.
TCBLIMIT
returns the maximum number of TCBs that can be used to process DB2 requests. When connected to DB2 Version 5 or earlier, the CICS DB2 attachment facility creates the TCBs in the form of subtasks up to the limit specified by TCBLIMIT. Each of these subtasks identifies to DB2 and creates a connection into DB2. When connected to DB2 Version 6 or later, CICS creates open TCBs (up to the limit specified in the system initialization parameter MAXOPENTCBS). 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.
THREADERROR
returns the processing that is to occur following a create thread error. CVDA values are:
ABEND
For a second or subsequent SQL error the transaction is abended with abend code AD2S, AD2T, or AD2U, dependent on the type of error that occurred. The transaction must be terminated and reinitialized before it is allowed to issue another SQL request.
N906D
A transaction dump is to be taken and the DSNCSQL RMI associated with the transaction is not to be disabled. The transaction receives a -906 SQLCODE if another SQL is issued, unless the transaction issues SYNCPOINT ROLLBACK. SYNCPOINT without the ROLLBACK option results in an ASP3 or ASP7 abend. The transaction dump records an abend of AD2S, AD2T, or AD2U.
N906
The DSNCSQL RMI associated with the transaction is not to be disabled. The transaction receives a -906 SQLCODE if another SQL request is issued, unless the transaction issues a SYNCPOINT ROLLBACK. SYNCPOINT without the ROLLBACK option results in an ASP3 or ASP7 abend.
THREADLIMIT
returns the current maximum number of pool threads the CICS DB2 attachment allows active before requests are made to wait or are rejected (see THREADWait).
THREADS
returns the current number of active pool threads.
THREADWAIT
returns whether or not transactions should wait for a pool thread or be abended should the number of active pool threads reach the threadlimit number. CVDA values are:
TWAIT
If all threads are busy, a transaction waits until one becomes available.
NOTWAIT
If all threads are busy, a transaction is terminated with an abend code AD3T.

Conditions

NOTFND
RESP2 values:
1
The DB2CONN cannot be found.
NOTAUTH
RESP2 values:
100
Command authorization failure
[[ Contents Previous Page | Next Page Index ]]