DIAGNOSE

The DIAGNOSE online utility generates information that is useful in diagnosing problems. Use this utility only under the direction of IBM® Software Support.

At the direction of IBM Support, you can use the DIAGNOSE utility to complete the following tasks:

Obtain dumps for any utility abend, overriding any considerations that might suppress such a dump.
Send OBD and SYSUTIL information to SYSPRINT for review (DISPLAY option).
Dump both the Db2 MEPL and the application space (DSNUTILB) MEPL to SYSPRINT without forcing an SVC dump (DISPLAY MEPL option).
Dump an entry for a database in SYSIBM.SYSDATABASE to SYSPRINT (DISPLAY option).
Force Db2 to abend after a specific Db2 message is specified or when a module trace ID is encountered (ABEND option with the MESSAGE or TRACEID option).

Interpreting output

One intended use of this utility is to aid in determining and correcting system problems. When diagnosing Db2 problems, you might need to refer to licensed documentation to interpret output from this utility.

Authorization required

To execute this utility for options which access relational data, you must use a privilege set that includes one of the following authorizations:

REPAIR privilege for the database
DBADM or DBCTRL authority for the database. If the object on which the utility operates is in an implicitly created database, DBADM authority on the implicitly created database or DSNDB04 is required.
System DBADM authority
DATAACCESS authority
SQLADM authority
SYSCTRL or SYSADM authority

An ID with installation SYSOPR authority can execute the DIAGNOSE utility on a table space in the DSNDB01 or DSNDB06 database.

An ID with installation SYSADM authority can execute the DIAGNOSE utility with the WAIT statement option on any table space.

You can create a control statement with the ISPF/PDF edit function. After you create it, save it in a sequential or partitioned data set. When you create the JCL for running the job, use the SYSIN DD statement to specify the name of the data set that contains the utility control statement.

Syntax diagram

diagnose statement

display statement

wait statement

abend statement

Option descriptions

TYPE(integer, …)

Specifies one or more types of diagnose that you want to perform.

integer is the number of types of diagnoses. The maximum number of types is 32. IBM Support defines the types as needed to diagnose problems with IBM utilities.

ALLDUMPS(X'abend-code', …)

Forces a dump to be taken in response to any utility abend code.

X'abend-code' is a member of a list of abend codes to which the scope of ALLDUMPS is limited.

abend-code is a hexadecimal value.

NODUMPS(X'abend-code', …)

Suppresses the dump for any utility abend code.

X'abend-code' is a member of a list of abend codes to which the scope of NODUMPS is limited.

abend-code is a hexadecimal value.

DISPLAY

Formats the specified database items using SYSPRINT.

OBD database-name.table-space-name

Formats the object descriptor (OBD) of the table space.

database-name is the name of the database in which the table space belongs.

table-space-name is the name of the table space whose OBD is to be formatted.

ALL: Formats all OBDs of the table space. The OBD of any object that is associated with the table space is also formatted.
TABLES: Formats the OBDs of all tables in the specified table spaces.
INDEXES: Formats the OBDs of all indexes in the specified table spaces.

SYSUTIL

Formats every record from SYSIBM.SYSUTIL. This directory table stores information about all utility jobs.

MEPL

Dumps the module entry point lists (MEPLs) to SYSPRINT.

AVAILABLE

Displays the utilities that are installed on this subsystem in both bitmap and readable format. The presence or absence of the Db2 Utilities Suite for z/OS® (5698-DUT) affects the results of this display. Message DSNU862I displays the output from DIAGNOSE DISPLAY AVAILABLE.

Related information:

DSNU862I

RBLP

Displays the recovery-based log point RBA or LRSN that is the system restart and redo point.

DBET

Dumps the contents of a database exception table (DBET) to SYSPRINT.

DATABASE database-name

Dumps the DBET entry that is associated with the specified database.

database-name is the name of the database.

TABLESPACE database-name.table-space-name

Dumps the DBET entry that is associated with the specified table space.

database-name is the name of the database.

table-space-name is the name of the table space.

INDEX creator-name.index-name

Dumps the DBET entry that is associated with the specified index.

creator-name is the ID of the creator of the index.

index-name is the name of the index.

Enclose the index name in quotation marks if the name contains a blank.

CLONE

Indicates that DIAGNOSE is to display information for only the following specified objects:

Clone tables
Table spaces that contain clone tables
Indexes on clone tables
Index spaces that contain indexes on clone tables.

WAIT

Suspends utility execution when it encounters the specified utility message or utility trace ID. DIAGNOSE issues a message to the console. Utility execution does not resume until the operator replies to that message, the utility job times out, or the utility job is canceled. This waiting period allows events to be synchronized while you are diagnosing concurrency problems. The utility waits for the operator to reply to the message, allowing the opportunity to time or synchronize events.

If the utility message or trace ID is not encountered, processing continues.

ABEND

Forces an abend during utility execution if the specified utility message or utility trace ID is issued.

If the utility message or trace ID is not encountered, processing continues

NODUMP: Suppresses the dump that is generated by an abend of DIAGNOSE.

MESSAGE message-id

Specifies a DSNUxxx or DSNUxxxx message that causes a wait or an abend to occur when that message is issued.

message-id is the message, in the form of Uxxx or Uxxxx.

INSTANCE integer: Specifies that a wait or an abend is to occur when the MESSAGE option message is encountered a specified number of times. If INSTANCE is not specified, a wait or abend occurs each time that the message is encountered.
integer is the number of times that a message is to be encountered before a wait or an abend occurs.

TRACEID trace-id

Specifies a trace ID that causes a wait or an abend to occur when the ID is encountered. You can find valid trace IDs can be found in data set prefix.SDSNSAMP(DSNWEIDS).

trace-id is a trace ID that is associated with the utility trace (RMID21). You can specify trace-id in either decimal (integer) or hexadecimal (X'trace-id') format.

INSTANCE integer: Specifies that a wait or an abend is to occur when the TRACEID option is encountered a specified number of times. If INSTANCE is not specified, a wait or abend occurs each time that the trace ID is encountered.
integer is the number of times that a trace ID is to be encountered before a wait or an abend occurs.

END

Ends DIAGNOSE processing.

Data sets that DIAGNOSE uses

The following table lists the data sets that DIAGNOSE uses. The table lists the DD name that is used to identify the data set, a description of the data set, and an indication of whether it is required. Include statements in your JCL for each required data set.

Table 1. Data sets that DIAGNOSE uses
Data set	Description	Required?
SYSIN	Input data set that contains the utility control statement.	Yes
SYSPRINT	Output data set for messages.	Yes

The following objects are named in the utility control statement and do not require DD statements in the JCL:

Database: Database about which DIAGNOSE is to gather diagnosis information.
Table space: Table space about which DIAGNOSE is to gather diagnosis information.
Index space: Index about which DIAGNOSE is to gather diagnosis information.

Concurrency and compatibility

DIAGNOSE can run concurrently on the same target object with any SQL operation or utility, except a utility that is running on DSNDB01.SYSUTILX.

Termination or restart of DIAGNOSE

You can terminate a DIAGNOSE utility job by using the TERM UTILITY command if you submitted the job or have SYSOPR, SYSCTRL, or SYSADM authority.

You can restart a DIAGNOSE utility job, but it starts from the beginning again.

Example 1: Displaying Db2 MEPLs

The following DIAGNOSE utility control statement specifies that the Db2 MEPLs are to be displayed. You can use the output from this statement to find the service level of a specific Db2 module. The output lists each module, the most recent PTF or APAR that was applied to the module, and the date that the PTF or APAR was installed.

Important: Specify Db2 load libraries in the JOBLIB or STEPLIB of the DIAGNOSE DISPLAY MEPL job that are at the same maintenance level as the load libraries for the Db2 subsystem on which you execute the utility. Doing this ensures that the information that DIAGNOSE DISPLAY MEPL reports reflects the current state of the Db2 subsystem.

DIAGNOSE
 DISPLAY MEPL

Example 2: Forcing a dump

The following control statement forces a dump if an abend occurs with either of the following reason codes: X'00E40322' or X'00E40323'.

DIAGNOSE
 ALLDUMPS(X'00E40322',X'00E40323')

The following control statement forces a dump for any utility abend that occurs during the execution of the specified COPY job. The DIAGNOSE END option ends DIAGNOSE processing.

DIAGNOSE
 ALLDUMPS
 COPY TABLESPACE DSNDB06.SYSDDF
DIAGNOSE END

Example 3: Performing a diagnosis of a specific type

The following DIAGNOSE statement specifies that you want to perform a diagnosis of type 66. Run this job under the direction of IBM Support to diagnose problems with utility parallelism.

//STEP3    EXEC DSNUPROC,UID='JUOSU226.REBUI',                         
//            UTPROC='',SYSTEM='SSTR'                                  
//SYSIN    DD *   
DIAGNOSE TYPE(66)                                                    
    REBUILD INDEX (IDOS0302, IDOS0304, IPOS0301)                       
            SORTDEVT SYSDA SORTNUM 3                                   
DIAGNOSE END                                                         
/*

Example 4: Forcing a utility abend

The following DIAGNOSE statement forces an abend of the specified COPY job when one instance of message DSNU400 is issued. The NODUMP option indicates that DIAGNOSE is not to generate a dump in this situation.

//STEP1    EXEC DSNUPROC,UID='IUJMU116.COPY1',
//         UTPROC='',
//         SYSTEM='DSN'
//SYSCOPY1  DD DSN=IUJMU116.COPY.STEP1.SYSCOPY1,DISP=(NEW,CATLG,CATLG),
//         UNIT=SYSDA,SPACE=(4000,(20,20),,,ROUND)
//SYSIN    DD *
DIAGNOSE  ABEND MESSAGE U400
                 INSTANCE 1
                 NODUMP
                    COPY TABLESPACE DSN8D13A.DSN8S13E
                      COPYDDN SYSCOPY1
DIAGNOSE END
//*

The following DIAGNOSE statement forces an abend of the specified LOAD job when message DSNU311 is issued for the fifth time. The NODUMP option indicates that the DIAGNOSE utility is not to generate a dump in this situation.

DIAGNOSE
 ABEND MESSAGE U311 INSTANCE 5 NODUMP
LOAD DATA RESUME NO
  INTO TABLE TABLE1
   (NAME POSITION(1) CHAR(20))
DIAGNOSE END

Example 5: Suspending utility execution

The following DIAGNOSE statement indicates that the specified COPYTOCOPY job is to be suspended when it encounters 51 occurrences of the trace ID X'2E6F'.

//STEP2    EXEC DSNUPROC,UID='DH109012.C2C01',                           
//         UTPROC='',                                                    
//         SYSTEM='SSTR'                                                 
//COPY2    DD DSN=DH109012.C2C01.STEP2.COPY2,DISP=(MOD,CATLG,CATLG),     
//         UNIT=SYSDA,SPACE=(1000,(20,20),,,ROUND)                       
//COPY3    DD DSN=DH109012.C2C01.STEP2.COPY3,DISP=(MOD,CATLG,CATLG),     
//         UNIT=SYSDA,SPACE=(1000,(20,20),,,ROUND)                       
//COPY4    DD DSN=DH109012.C2C01.STEP2.COPY4,DISP=(MOD,CATLG,CATLG),     
//         UNIT=SYSDA,SPACE=(1000,(20,20),,,ROUND)                       
//SYSIN    DD *                                                          
   DIAGNOSE WAIT TRACEID X'2E6F' INSTANCE 51                             
    COPYTOCOPY TABLESPACE DBA91201.TPA91201 DSNUM 1                      
              FROMLASTFULLCOPY COPYDDN(,COPY2)                           
                               RECOVERYDDN(COPY3,COPY4)  
   DIAGNOSE END                                             
/*

Example 6: Displaying only CLONE data

The control statement indicates that the DIAGNOSE utility is to be display information for only the specified objects that are table clones, table spaces that contain clone tables, indexes on clone tables, or index spaces that contain indexes on clone tables.

DIAGNOSE DISPLAY DBET  
     DATABASE DBNI0501   
     CLONE