DSNC DISPLAY

Use DSNC DISPLAY to display information about active CICS® Db2® threads and the CICS transaction using them, or to display statistical information associated with DB2ENTRY resources and the DB2CONN resource.

Abbreviation

DSNC DISP
DISP (using the DISP transaction from the CICS Db2 sample group DFH$DB2®)

Environment

This command can be issued only from a CICS terminal.

Authorization

Access to this command is controlled by CICS transaction security for the DSNC transaction and by CICS command security for the DB2CONN resource. This command requires READ access.

For more information about CICS security, see Security in a CICS Db2 environment.

Syntax

Parameters

PLAN planname

Displays information about the threads for planname. planname is a valid plan name for which information is displayed.

If you do not specify planname, or if you specify an asterisk (*), information is displayed for all active threads.

For example, the following command displays information on all active CICS Db2 plan IDs and sends the display information to another terminal designated as MTO2.

DSNC DISP PLAN * MTO2

Tran transactionID

Contains the transaction ID for which thread information is displayed. transactionID is a valid transaction ID for which thread information is displayed.

If you do not specify a transaction ID, information is displayed for all active threads.

For example, the following command displays information about all active CICS Db2 transactions.

DSNC DISP TRAN

STAT

Displays the statistical counters associated with each CICS Db2 resource definition. The counters concern the usage of the available connections of the CICS Db2 attachment facility to Db2.

Note that you can obtain a more detailed set of CICS Db2 statistics by using standard CICS statistics interfaces such as the EXEC CICS COLLECT STATISTICS and EXEC CICS PERFORM STATISTICS commands or by using the DFH0STAT sample program.

destination

Specify a different terminal to receive the requested information. destination is the identifier of another terminal to receive the requested display information. It must be a valid terminal that is defined to CICS and supported by basic mapping support (BMS).

Because the optional destination is sometimes preceded by an optional plan name or transaction ID in the command, each parameter must be unique and separately identifiable as either a name or a terminal identifier. If only one parameter is entered, it is first checked to see whether it is a plan name or a transaction ID, and it is then checked as a destination. To use a character string that is both a plan name or transaction ID and also a valid terminal identifier, you must use both the name and destination parameters to display the required information at the required terminal.

When an alternate destination is specified to receive the requested display information, the following message is sent to the requesting terminal:

DFHDB2032 date time applid alternate destination display command complete

Usage notes

If you issue this command from CICS while the CICS Db2 attachment facility is active but the Db2 subsystem is not, a statistics display is produced with no obvious indication that the subsystem is not operational.

Message DFHDB2037 appears in the CICS message log to indicate that the attachment facility is waiting for Db2 to start.

DISPLAY PLAN or DISPLAY TRAN output

The output of the DSNC DISPLAY PLAN or DSNC DISPLAY TRANSACTION command includes the name of the DB2ENTRY, *POOL, or *COMMAND for the DSNC command call.

Figure 1 shows an example of the output for the DSNC DISPLAY (PLAN or TRANSACTION) command. For each created thread, the output shows the name of the DB2ENTRY, *POOL for the pool, or the *COMMAND for the DSNC command call.

Figure 1. Sample output from DSNC DISPLAY (PLAN or TRANSACTION) command

 
DFHDB2013 07/09/** 15:26:47 IYK4Z2G1 Display report follows for threads
accessing DB2 DB3A
DB2ENTRY S PLAN     PRI-AUTH SEC-AUTH CORRELATION  TRAN TASK  UOW-ID
*POOL    A TESTC05  JTILLI1           POOLXC050001 XC05 01208 AEEEC0321ACDCE00
XC06     * TESTC06  JTILLI1           ENTRXC060003 XC06 01215 AEEEC0432F8EFE01
XP05     A TESTP05  JTILLI1           ENTRXP050002 XP05 01209 AEEEC03835230C00
XP05     I TESTP05  JTILLI1           ENTRXP050004
DFHDB2020 07/09/** 15:26:47 IYK4Z2G1 The display command is complete.

Field

S

The column named S denotes the status of the thread, and can take the following values:

*: The thread is active within a unit of work, and is currently executing in Db2.
A: The thread is active within a unit of work, but is not currently executing in Db2.
I: The thread is inactive; it is a protected thread that is waiting for new work.

PLAN

The PLAN associated with the thread is displayed. There is no plan for command threads.

PRI-AUTH

The PRI-AUTH field shows the primary authorization ID used for the thread. The SEC-AUTH field shows the secondary authorization ID (if any) for the thread.

CORRELATION

The CORRELATION fields shows the 12-byte thread correlation ID which is made up as eeeettttnnnn where

eeee is either COMD, POOL or ENTR indicating whether it is a command, pool or DB2ENTRY thread.
tttt is the transaction ID.
nnnn is a unique number.

Note: A correlation ID passed to Db2 can be changed only by the CICS Attachment Facility issuing a sign-on to Db2. If sign-on reuse occurs by a thread using a primary authorization ID which remains constant across multiple transactions (for example, by using AUTHID(name)) only one sign-on will occur. In this instance the tttt in the correlation ID does not match the running transaction ID. It is the ID of the transaction for which the initial sign-on occurred.

If the thread is active within a unit of work, the CICS transaction name, its task number and finally the CICS local unit of work ID is displayed.

The correlation ID used in this display is also output on Db2 commands such as DISPLAY LOCK. For example, by using this display in conjunction with a display locks command you can find out which CICS task is holding a lock within Db2.

DISPLAY STATISTICS output

Figure 2 is a sample output of the DSNC DISPLAY STATISTICS command.

Figure 2. Sample output from DSNC DISPLAY STATISTICS command

 
DFHDB2014 07/09/** 14:35:45 IYK4Z2G1 Statistics report follows for RCTJT
accessing DB2 DB3A
                                                           -----COMMITS----
DB2ENTRY PLAN        CALLS    AUTHS    W/P HIGH   ABORTS   1-PHASE  2-PHASE
*COMMAND                1        1      1    1       0          0       0
*POOL    ********       4        1      0    1       0          2       0
XC05     TESTP05       22        1     11    2       0          7       5
XP05     ********       5        2      0    1       0          1       1
DFHDB2020 01/17/** 15:45:27 IYKA4Z2G1  The display command is complete.

Field

DB2ENTRY

Name of the DB2ENTRY, or *COMMAND for DSNC command calls, or *POOL for pool statistics.

PLAN

The plan name associated with this entry. Eight asterisks in this field indicate that this transaction is using dynamic plan allocation. The command processor transaction DSNC does not have a plan associated with it.

If a plan name associated with an entry is dynamically changed, the last plan name is the one put into use.

CALLS

The total number of SQL statements issued by transactions associated with this entry.

AUTHS

The total number of sign-on invocations for transactions associated with this entry. A sign-on does not indicate whether a new thread is created or an existing thread is reused. If the thread is reused, a sign-on occurs only if the authorization ID or transaction ID has changed.

W/P

The number of times that all available threads for this entry were busy. This value depends on the value of THREADWAIT for the entry. If THREADWAIT is set to POOL, W/P indicates the number of times the transaction overflowed to the pool. An overflow to the pool only shows up in the statistics for the individual DB2ENTRY, and is not reflected in the pool statistics.

If THREADWAIT is set to YES, this reflects the number of times that either the transaction had to wait for a thread (because the number of active threads had reached THREADLIMIT), or the transaction could not use a new thread TCB (because the number of TCBs in use running threads had reached TCBLIMIT).

HIGH

The maximum number of threads acquired by transactions associated with this entry at any time since the connection was started, that is, a high-water mark of threads. The HIGH value represents threads created on the entry.

ABORTS

The total number of units of recovery which were rolled back. It includes both abends and syncpoint rollbacks, including syncpoint rollbacks generated by -911 SQL codes.

COMMITS

One of the following two fields is incremented each time a Db2 transaction associated with this entry has a real or implied (such as EOT) syncpoint. Units of recovery that do not process SQL calls are not reflected here.

1-PHASE: The total number of single-phase commits for transactions associated with this entry. This total does not include any two-phase commits (see the explanation for 2-PHASE). This total does include read-only commits as well as single- phase commits for units of recovery which have performed updates. A two-phase commit is needed only when the application has updated recoverable resources other than DB2.
2-PHASE: The total number of two-phase commits for transactions associated with this entry. This number does not include single phase commit transactions.