CEMT INQUIRE DB2CONN

Retrieves information about the CICS DB2 connection.

In the CICS Explorer, the Db2 connections operations view provides a functional equivalent to this command.

Description

INQUIRE DB2CONN returns information about the attributes of the currently installed DB2CONN, which defines the connection to DB2.

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

The resource signature

You can use this command to display the resource signature fields. You can use these fields to manage resources by capturing details of when the resource was defined, installed, and last changed. For more information, see Auditing resources. The resource signature fields are CHANGEAGENT, CHANGEAGREL, CHANGETIME, CHANGEUSRID, DEFINESOURCE, DEFINETIME, INSTALLAGENT, INSTALLTIME, and INSTALLUSRID. See Summary of the resource signature field values for detailed information about the content of the resource signature fields.

Input

Press the Clear key to clear the screen, and type CEMT INQUIRE DB2CONN. The current status is displayed. You can then tab to the highlighted or blank fields and overtype them with the required values.

CEMT INQUIRE DB2CONN

Displayed fields

ACCOUNTREC

Returns the minimum amount of DB2 accounting required for transactions using pool threads. The specified minimum can be exceeded, as described in the following options. The values are as follows:

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.
TASK: The CICS DB2 attachment facility causes a minimum of one accounting record to be produced for each CICS task.
A transaction containing multiple UOWs can use a different thread for each of its UOWs, assuming the thread is released at sync point. The result may be an accounting record produced for each UOW.
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 UOWs will use a different thread for each UOW (assuming the thread is released at sync point. In this case, an accounting record can be produced for each UOW.
NONE: No accounting records are required for transactions using pool threads.
DB2 does, however, produce at least one accounting record for each thread when the thread is ended. 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. The values are as follows:

GROUP

The 8-character user ID 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 user ID, an 8-character field of blanks is passed to DB2 as the group ID.

SIGN: The SIGNID field of the DB2 connection 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 user ID, 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).

CHANGEAGENT(value)

Displays a value that identifies the agent that made the last change to the resource definition. You cannot use CEMT to filter on some of these values because they are duplicated. The possible values are as follows:

CREATESPI: The resource definition was last changed by an EXEC CICS CREATE command.
CSDAPI: The resource definition was last changed by a CEDA transaction or the programmable interface to DFHEDAP.
CSDBATCH: The resource definition was last changed by a DFHCSDUP job.
DREPAPI: The resource definition was last changed by a CICSPlex SM BAS API command.

CHANGEAGREL(value)

Displays the 4-digit number of the CICS release that was running when the resource definition was last changed.

CHANGETIME(date time)

Displays the date and time when the resource definition was last changed. The format of the date depends on the value that you selected for the DATFORM system initialization parameter for your CICS region. The format of the time is hh:mm:ss.

CHANGEUSRID(value)

Displays the 8-character user ID that ran the change agent.

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. The values are as follows:

CGROUP

The 8-character user ID 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 user ID, 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) must 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 user ID that is associated with the CICS transaction 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 COMAUTHTYPE(CUSERID), 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 COMAUTHTYPE(CUSERID) and COMAUTHTYPE(CGROUP).

COMTHREADLIM

Returns the current maximum number of command threads that the CICS DB2 attachment allows to be active before requests overflow to the pool.

COMTHREADS

Returns the current number of active command threads.

CONNECTERROR

Returns a value when CICS is not connected to DB2 because the adapter is in standby mode. The value shows how this information is to be passed back to an application that has issued a SQL request. The values are as follows:

ABEND: The application is abended with abend AEY9.
SQLCODE: The application receives a -923 SQLCODE.

CONNECTST

Returns the status of the CICS DB2 connection. The values are as follows:

CONNECTED: CICS is connected to DB2.
NOTCONNECTED: CICS is not connected to DB2.

DB2GROUPID

If you are using group attach, this field returns the name (up to four characters) of a data sharing group, or subgroup of DB2 subsystems that you have specified. CICS tries 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 in the data sharing group for which it is holding outstanding units of work, the name of the specific DB2 subsystem appears in the DB2ID field, and CEMT displays the message Waiting for DB2. For this situation to arise, Resyncmember(Resync) must be specified.

DB2ID

If you are not using group attach, this field 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(Resync) is specified and the DB2 subsystem for which CICS is holding outstanding units of work is unavailable, this field gives the name of the DB2 subsystem, and CEMT displays the message Waiting for DB2.

DB2RELEASE

Returns a 4-character value indicating the version and release level of the DB2 subsystem to which CICS is connected. When CICS is not connected to DB2, blanks are returned.

DEFINESOURCE(value)

Displays the source of the resource definition. The DEFINESOURCE value depends on the CHANGEAGENT option. For details, see Summary of the resource signature field values.

DEFINETIME(date time)

Displays the date and time when the resource was created. The format of the date depends on the value that you selected for the DATFORM system initialization parameter for your CICS region. The format of the time is hh:mm:ss.

DROLLBACK

Returns a value showing whether the CICS DB2 attachment is to initiate a sync point rollback if a transaction is adversely affected by a deadlock resolution. The values are as follows:

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 does not initiate a rollback for a transaction. An SQL return code of -913 is returned to the application.

INSTALLAGENT(value)

Displays a value that identifies the agent that installed the resource. You cannot use CEMT to filter on some of these values because they are duplicated. The possible values are as follows:

CREATESPI: The resource was installed by an EXEC CICS CREATE command.
CSDAPI: The resource was installed by a CEDA transaction or the programmable interface to DFHEDAP.
GRPLIST: The resource was installed by GRPLIST INSTALL.

INSTALLTIME(date time)

Displays the date and time when the resource was installed. The format of the date depends on the value that you selected for the DATFORM system initialization parameter for your CICS region. The format of the time is hh:mm:ss.

INSTALLUSRID(value)

Displays the 8-character user ID that installed the resource.

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

Returns a value showing whether non-terminal transactions are to release threads for reuse at intermediate sync points:

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

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). The thread TCBs are CICS open L8 TCBs. The values are as follows:

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 the number of minutes in the protected thread purge cycle time (the number of seconds is returned by PURGECYCLES). 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. 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.

PURGECYCLES

Returns the number of seconds in the protected thread purge cycle time (the number of minutes is returned by PURGECYCLEM). The range for PURGECYCLES is 0 - 59. If PURGECYCLEM is zero, the minimum value of PURGECYCLES is 5 seconds.

RESYNCMEMBER

This field applies only if you are using group attach (with a DB2 group ID specified), and returns 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 that are shunted indoubt are not included in this process, because CICS itself cannot resolve those units of work at this time. Resynchronization for those UOWs occurs when CICS has resynchronized with its remote coordinator.) If you are not using group attach, a blank field is returned.

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.

REUSELIMIT

Returns 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. Long-running CICS DB2 threads that are constantly being reused build up resources in DB2 that can cause storage problems.

The reuse limit applies to unprotected threads both in the pool and on a DB2ENTRY, and to protected DB2ENTRY threads.

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(SIGNID) and command threads specifying COMAUTHTYPE(CSIGN).

SECURITY

Has no meaning for INQUIRE. It is supplied to allow overtyping with the REBUILD option, to initiate a CEMT SET DB2CONN. See SECURITY PURGECYCLES in CEMT SET SECURITY.

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. The values are as follows:

NOCONNECT: The CICS DB2 attachment ends.
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 then fails, the CICS DB2 attachment reverts again to standby mode and later reconnects to DB2 when it starts again.

STATSQUEUE

Returns the transient data destination for CICS DB2 attachment statistics produced when the CICS DB2 attachment is shut down.

TCBLIMIT

Returns the maximum number of TCBs that can be used to process DB2 requests. CICS creates 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.

TCBS

Returns a number indicating the TCBs currently used by the CICS DB2 attachment facility. 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.

THREADERROR

Returns the processing that is to occur following a create thread error. The values are as follows:

ABEND: For a second or subsequent SQL error, the transaction abends with abend code AD2S, AD2T, or AD2U, depending on the type of error that occurred. The transaction must be stopped and reinitialized before it is allowed to issue another SQL request.
N906D: A transaction dump is taken and the DSNCSQL RMI associated with the transaction is not to be disabled. The transaction receives a -906 SQLCODE error 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 error 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 to be active before requests are made to wait or are rejected. See Threadwait.

THREADS

Returns the current number of active pool threads.

THREADWAIT

Returns a value showing whether transactions wait for a pool thread or are abended if the number of active pool threads reaches the threadlimit number. The values are as follows:

TWAIT: If all threads are busy, a transaction waits until one becomes available.
NOTWAIT: If all threads are busy, a transaction is stopped with an abend code AD3T.