DSNC DISPLAY

The CICS® DB2® attachment facility command DSNC DISPLAY displays information on active CICS DB2 threads and the corresponding CICS transaction using them, or statistical information associated with DB2ENTRYs and the DB2CONN.

Environment

This command can be issued only from a CICS terminal.

Syntax

Read syntax diagramSkip visual syntax diagramDISPLAY syntax
 
>>-DSNC DISPlay  --+-PLAN-planname--------------+--------------->
                   +-TRANsaction-transactionID--+
                   '-STATistics-----------------'
 
>--+---------------+-------------------------------------------><
   '-destination  -'
 

Abbreviation

DSNC DISP or DISP (using the DISP transaction from the CICS DB2 sample group DFH$DB2).

Authorization

Access to this command can be controlled using the following CICS authorization checks:

Parameter description

planname
Displays information about threads by 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.

Example
Display information on all active plan IDs listed in the resource control table. The display information is to be sent to another terminal designated as MTO2.
 
         DSNC DISP PLAN * MTO2

Parameter description

transactionID
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.

Example
Display information about all active transactions listed in the resource control table.
 
           DSNC DISP TRAN

Parameter description

Displays the statistical counters associated with each entry in the resource control table. The counters concern the usage of the available connections of the CICS DB2 attachment facility to DB2.

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.

Example
Display statistical counters associated with each entry in the resource control table.
 
         DSNC DISP STAT

Note that a more detailed set of CICS DB2 statistics can be obtained using standard CICS statistics interfaces, for example, the commands EXEC CICS COLLECT STATISTICS and EXEC CICS PERFORM STATISTICS, or using the DFH0STAT sample program.

Alternative destination

destination
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
 

DISPLAY PLAN or TRAN

Figure 8 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 or ‘*POOL’ for the pool, or the ‘*COMMAND’ for which it has been created.

Figure 8. Sample output from DSNC DISPLAY (PLAN or TRANSACTION) command
 
DFHDB2013 07/09/98 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/98 15:26:47 IYK4Z2G1 The display command is complete.
 

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.

The PLAN associated with the thread is displayed (there is no plan for command threads).

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.

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 transid, and nnnn is a unique number.

Note:
A correlation ID passed to DB2 can be changed only by the CICS Attachment Facility issuing a signon to DB2. If signon reuse occurs by a thread using a primary authorization ID which remains constant across multiple transactions (for example, by using AUTHID(name)) only one signon 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 signon 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

Output of a DSNC DISPLAY STATISTICS command is as follows:

Figure 9. Sample output from DSNC DISPLAY STATISTICS command
 
DFHDB2014 07/09/98 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/98 15:45:27 IYKA4Z2G1  The display command is complete.
 
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 signon invocations for transactions associated with this entry. A signon does not indicate whether a new thread is created or an existing thread is reused. If the thread is reused, a signon 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 watermark of threads.
Note:
In releases of CICS before CICS Transaction Server for OS/390®, Version 1 Release 2, the HIGH value also included the transactions forced to wait for a thread or those diverted to the pool. From CICS Transaction Server for OS/390, Version 1 Release 2 onwards, the HIGH value only represents threads actually 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 below). 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.

Related concepts
CICS-supplied transactions for CICS DB2
Issuing commands to DB2 using DSNC
DSNC DISCONNECT
DSNC MODIFY
DSNC STOP
DSNC STRT
[[ Contents Previous Page | Next Page Index ]]