-DISPLAY TRACE command (Db2)

Environment for -DISPLAY TRACE

This command can be issued from a z/OS® console, a DSN session, a DB2I panel (DB2 COMMANDS), an IMS or CICS® terminal, or a program using the instrumentation facility interface (IFI).

Data sharing scope: Group or member

Authorization for -DISPLAY TRACE

Db2 commands that are issued from a logged-on z/OS console or TSO SDSF can be checked by Db2 authorization using primary and secondary authorization IDs. A logged-on z/OS user ID must be defined in RACF or a similar security server.

Option descriptions for -DISPLAY TRACE

-DISPLAY TRACE (PERFM) CLASS (1,2)

( * )

Does not limit the list of traces. The default is ( * ).

The CLASS option cannot be used with DISPLAY TRACE (*).

Each of the following keywords limits the list to traces of the corresponding type.

Type (Abbrev)

Description

PERFM (P)

Performance records of specific events

ACCTG (A)

Accounting records for each transaction

STAT (S)

Statistical data

AUDIT (AU)

Audit data

MONITOR (MON)

Monitor data

DETAIL ( output-type )

Limits the information that a trace displays based on the output type specified within parentheses.

The possible values for output-type are:

1

Display summary trace information: TRACE NUMBER, TYPE, CLASS, DEST

2

Display qualification trace information: TRACE NUMBER, AUTHID, LOCATION, PACKAGE, PLAN, TXACT, USERID, WORKSTATION

1,2

Display both summary and qualification information

*

Display both summary and qualification information

If no parameter follows DETAIL, type 1 trace information is displayed.

An additional column, QUAL, is also displayed, indicating whether the trace is qualified. Part of the summary trace information, the QUAL column can be used to determine if further qualification information for the trace is available. This information can be obtained by specifying DETAIL (2) or DETAIL (*). A QUAL column value of YES indicates that additional information for this particular trace exists in the qualification trace information; a value of NO indicates that no additional information for this trace exists.

COMMENT ( string )

Specifies that comment string appears in the trace output, except for the output in the resident trace tables.

string is any character string; it must be enclosed between apostrophes if it includes a blank, comma, or special character. The comment does not appear in the display; it can be recorded in trace output, but only if commands are being traced.

SCOPE

Specifies the scope of the command.

( LOCAL )

Displays the trace for the local member only.

(GROUP)

Displays the trace for all members in the data sharing group.

DEST

Limits the list to traces that were started for particular destinations. More than one value can be specified, but do not use the same value twice. If you do not specify a value for DEST, Db2 does not use the destination of where trace output is recorded to limit the list of traces displayed.

Abbreviation: D

Possible values and their meanings are:

Value

Trace destination

GTF

z/OS generalized trace facility (GTF).

SMF

z/OS System Management Facilities (SMF)

SRV

An exit to a user-written routine

OP n

FL 504 A specific destination. n can be a value from 1 to 16.

DEST n

FL 505 The destination is Db2ZAI.

RMID

Specifies resource manager identifier. You can specify up to 8 valid RMIDs, which are one or two digit identifiers. You cannot specify RMID for accounting or statistic traces.

ASID(x'dddd')

Specifies that information about the trace for an address space is to be displayed.

dddd is a four-byte hexadecimal address space ID (ASID).

CLASS( integer , …)

Limits the list to traces that were started for particular classes.

The default is CLASS( * ), which does not limit the list.

TNO( integer , …)

FL 506 Limits the list to particular traces, identified by their trace numbers (1 to 64, 01 to 09). Up to eight trace numbers can be used. If more than one number is used, only one value each for PLAN, AUTHID, and LOCATION can be used.

The default is TNO( * ), which does not limit the list.

PLAN( plan-name , …) or XPLAN( plan-name , …)

Introduces a list of specific plans for which trace information is gathered. Use PLAN to constrain the trace to the specified plans or XPLAN to exclude the specified plans. You cannot use this option for a STAT trace.

The default is PLAN( * ).

( * )

Displays a trace for all plans.

plan-name

The name of an application plan. You can use up to eight names. If you use more than one name, you can use only one value for AUTHID and LOCATION.

PKGLOC or XPKGLOC

Specifies the location name where the package is bound. Use PKGLOC to constrain the trace to the specified locations or XPKGLOC to exclude the specified locations.

PKGCOL or XPKGCOL

Specifies the package collection name. Use PKGCOL to constrain the trace to the specified collections or XPKGCOL to exclude the specified collections.

PKGPROG or XPKGPROG

Specifies the DBRM or program name. Use PKGPROG to constrain the trace to the specified programs or XPKGPROG to exclude the specified programs.

AUTHID( authorization-id , …) or XAUTHID( authorization-id , …)

Introduces a list of specific authorization IDs for which trace information is gathered. Use AUTHID to constrain the trace to the specified authorization IDs or XAUTHID to exclude the specified authorization IDs. The authorization IDs specified must be the primary authorization IDs. You cannot use this option for a STAT trace.

The default is AUTHID( * ).

( * )

Displays a trace for all authorization IDs.

authorization-id

Specifies an authorization ID. You can use up to eight identifiers. If you use more than one identifier, you can use only one value for PLAN and LOCATION.

LOCATION( location-name , …) or XLOC( location-name , …)

Specifies a list of location names for which trace information is gathered. Use LOCATION to constrain the trace to the specified locations or XLOC to exclude the specified locations. The use of the LOCATION or XLOC option precludes tracing threads that have no distributed data relationship.

location-name

Identifies the Db2 subsystems whose distributed threads you want to trace. Activates the Db2 trace for the remote TCP/IP or SNA location that you specify by location-name.

You can specify up to eight locations. You can specify only one location if you use more than one plan name or authorization ID.

<luname>

Activates the Db2 trace for the remote clients that are connected to DDF through the remote SNA LU name that you specified in luname.

ipaddr

Activates the Db2 trace for the remote clients that are connected to DDF through the remote TCP/IP host.ipaddr is the IP address.

(*)

Indicates that you want to display trace events that occur under distributed threads regardless of which location they are connected to. Specifying the local location name is equivalent to specifying LOCATION(*).

Clients other than Db2 for z/OS: Db2 for z/OS does not receive a location name from clients that are not Db2 for z/OS subsystems. To display a trace for a client that is not a Db2 for z/OS subsystem, enter its LUNAME or IP address. Enclose the LUNAME by the less-than (<) and greater-than (>) symbols. Enter the IP address in the form nnn.nnn.nnn.nnn. For example, to display a trace for a client with the LUNAME of LULA, enter the following command:

-DISPLAY TRACE (*) LOCATION (<LULA>)

To display a trace for a client with the IP address of 123.34.101.98, enter the following command:

-DISPLAY TRACE (*) LOCATION (::FFFF:123.34.101.98)

USERID or XUSERID

Specifies the user ID. Use USERID to constrain the trace to the specified user IDs or XUSERID to exclude the specified user IDs. You can specify multiple values and wildcard values as described in Usage notes.

USERID and XUSERID can be up to 16 characters.

APPNAME or XAPPNAME

Specifies the application name. Use APPNAME to constrain the trace to the specified applications or XAPPNAME to exclude the specified applications. You can specify multiple values and wildcard values as described in Usage notes.

APPNAME and XAPPNAME can be up to 32 characters.

WRKSTN or XWRKSTN

Specifies the workstation name. Use WRKSTN to constrain the trace to the specified workstations or XWRKSTN to exclude the specified workstations. You can specify multiple values and wildcard values as described in Usage notes.

WRKSTN and XWRKSTN can be up to 18 characters.

CONNID or XCONNID

Specifies the connection ID. Use CONNID to constrain the trace to the specified connections or XCONNID to exclude the specified connections.

CORRID or XCORRID

Specifies the correlation ID. Use CORRID to constrain the trace to the specified correlation IDs or XCORRID to exclude the specified correlation IDs.

ROLE or XROLE

Specifies the connection roles. Use ROLE to constrain the trace to the specified roles or XROLE to exclude the specified roles.

AUDTPLCY

A 128-byte area that contains the policy name. You can specify up to eight audit policy names. AUDTPLCY applies to trace type AUDIT. You cannot specify CLASS or IFCID with AUDTPLCY.

Usage notes for -DISPLAY TRACE

Displaying traced threads using the * wildcard

You can use the wildcard suffix, “*” to filter threads that you want to display. For example, if you specify “-DISPLAY TRACE PLAN (A,B,C*)”, Db2 will display traces A, B, CDE, CDEFG, CDEFGH, and so on. It will display traced threads “A”, “B” and all threads starting with “C”.

Displaying traced threads using the positional, (_) wildcard

You can use the positional wildcard, which is represented by the, “_” character, to display traced threads when you want the wildcard in the middle, or when you want to trace threads of a specific length. For example, if you specify “-DISPLAY TRACE PLAN (A_B), all display all traced threads that have “A” as the first character, any character for the "_," and “C” as the plan filter.

Displaying multiple traced threads at once using wildcards

You also have the option of displaying multiple traced threads based on multiple trace qualifications. For example, you can specify, “-DISPLAY TRACE PLAN (A*, B*, C*) to simultaneously display all traced threads for plan that start with “A”, “B”, and “C”. The wildcard character, “*” will display all traced threads. You can specify more complex combinations such as, “-DISPLAY TRACE PLAN (A_B*, C*, AND C/_D*)”, which will return all threads that:

• begin with “A”, have a one character wild card as the second character in the thread, have a “B” as the third character in the thread, and end with any type or number of characters (ADBIOP, AOBTYJDP,)
• begin with “C”, and end with any combination of characters (CDE, CGHKO)
• begin with “C_D” and end with any type of character combination (C_DEFGH, C_DlMNOP)

All of the possible thread combinations listed above will be returned with the command above.

You have the ability to filter multiple threads at the same time, setting specific criteria for the trace. For example, you can specify, “-DISPLAY TRACE PLAN (A) USERID (B)." This will display all traced threads where the plan thread is "A," and the user ID is "B." Note: When displaying traced threads, you can only specify one thread criteria for each filter for the display trace command. For example, you can specify “-DISPLAY TRACE PLAN(A,B) USERID (B) WRKSTN (E),” but you cannot specify “-DISPLAY TRACE PLAN(A, B) USERID(A, B) WRKSTN(E) because, in this example, two of the filter qualifications have two elements defined to be traced, and Db2 only allows for one attribute to have more than one trace element to be defined per trace.

Filtering traced threads that you want to display using exclude functionality

When you specify an “X” with any constraint keyword, such as “XPLAN”, when you are filtering threads, you are using the exclude functionality for the display trace command. You have the option of excluding specific types of threads you want to display when you are running trace commands. You can use the “X” character to exclude specific combinations of characters when you are running a display trace command. For example, you can specify “-DISPLAY TRACE XPLAN(A), to display all traced threads EXCEPT “A”. In this instance B, BCD, BCDE, or CD could possibly be returned.

You also have the option of excluding multiple types of threads from your trace. For example, you can specify, “-DISPLAY TRACE XPLAN (A*, B*) to display all traced threads EXCEPT those starting with “A”, with any combination of characters following “A”, and all those characters starting with “B”, with any combination of characters following “B”. Note: Specifying XPLAN (*) will exclude all threads from your search, and is not allowed. You also cannot use the wildcard in the middle of a display trace command with exclude functionality, such as, “-DISPLAY TRACE XPLAN (A*C).” You can, however, specify “-DISPLAY TRACE XPLAN (A_ _ C *)”, which will return all threads EXCEPT those starting with “A”, a variety of TWO characters next, a “C” in the fourth space, and a variety of characters at the end. The wildcard symbol cannot be placed in the middle of trace criteria.

You have the ability to display two traces at once, in order to help you optimize your tracing capabilities. For example, you can specify (-DISPLAY TRACE XPLAN (A, B, C) USERID (D))”. This tells Db2 to display all threads that are being traced for “plan” EXCEPT threads “A”, “B”, or “C”, only where the user ID = “D”.

You can introduce wildcards into your display trace commands to add more customization to your traces. For example, you can specify “-DISPLAY TRACE PLAN (C*) USERID (Z, X) XPLAN (C, D, E)”. In this example, for the thread to be traced, the plan must begin with "C," the user ID must be equal to "Z" or to "X," and the plan cannot be "C," "D," or "E." So a plan of "CB," with a user ID of "Z" would pass, and the thread being traced would be displayed, but plan C with a user ID of "X" would fail because the command specifies not to trace threads where the plan is “C”, without additional characters in the thread.

Combining trace qualifiers

You can customize the threads you trace by commanding Db2 to trace specific threads, while excluding other specific threads. For example, you can specify, “-DISPLAY TRACE USERID(A,B) XPLAN (C)” . This criteria only traces threads where the user ID is equal to “A” or “B”, and plan is NOT equal to “C”. In this example, a thread where the user ID is “A” and the plan is equal to “D” would pass, and be traced, but a thread where the user ID is “A” and plan is “C” would not pass, and would not be traced.

DISPLAY TRACE return code when there are no active traces

If you run DISPLAY TRACE in a batch environment, and no traces are active, the return code for the job step is 12.

Trace information for commands issued with group scope

If this command is issued with options that specify group scope in a Db2 data sharing member, it also runs on all other active members. IFICID 090 trace records for other group members can show that the same command was issued by the SYSOPR authorization ID from the 016.TLPKN5F correlation ID, in addition to the trace records from the member where the original command was issued. See Command scope in Db2 data sharing.

Output for -DISPLAY TRACE

The DSNW127I message displays output from the DISPLAY TRACE command. The format of the output depends on the value of the DETAIL option that was specified on the command.

DSNW127I  CURRENT TRACE ACTIVITY IS -                
TNO           TYPE        CLASS       DEST         QUAL      IFCID                    
trace-number  trace-type  type-class  destination  qualified ifcid
trace-number  trace-type  type-class  destination  qualified ifcid
*********END OF DISPLAY TRACE SUMMARY DATA*********                       

DSNW143I  CURRENT TRACE QUALIFICATIONS ARE -
DSNW152I  BEGIN TNO trace-number QUALIFICATIONS   
NO QUALIFICATIONS
END TNO trace-number QUALIFICATIONS
DSNW185I BEGIN TNO trace-number AUDIT POLICIES
NO AUDIT POLICIES ACTIVE
END TNO trace-number AUDIT POLICIES

DSNW152I  BEGIN TNO trace-number QUALIFICATIONS   
PLAN: plan-qualification
AUTHID: authid-qualification
LOCATION: location-qualification
USERID: userid-qualification
APPLICATION/TRANSACTION NAME: application/transaction-name-qualification
WORKSTATION: workstation-qualification
PACKAGE LOCATION: package-location-qualification
PACKAGE COLLECTION ID: package-collection-ID-qualification
PACKAGE PROGRAM NAME: package-program-name-qualification
ROLE: role-qualification
RMID: rmid-qualifications
CONNECTION ID: connection-ID-qualification
CORRELATION ID: correlation-ID-qualification
EXCLUDE PLAN: xplan qual1,xplan qual2,...,xplan qual8
EXCLUDE AUTHID: xauthid qual1,xauthid qual2,...,authid qual8
EXCLUDE LOCATION: xloc qual1,xloc qual2,...,xloc qual8 
EXCLUDE USERID: xuserid qual1,xuserid qual2,...,xuserid qual8
EXCLUDE APP/TXACT NAME: xappname qual1,xappname qual2,...,xappname qual8 
EXCLUDE WORKSTATION: xwrkstn qual1,xwrkstn qual2,...,xwrkstn qual8
EXCLUDE PACKAGE LOC: xpkgloc qual1,xpkgloc qual2,...,xpkgloc qual8
EXCLUDE PACKAGE COLLID: xpkgcol qual1,xpkgcol qual2,...,xpkgcol qual8
EXCLUDE PACKAGE PROGNAME: xpkgprog qual1,xpkgprog qual2,...,xpkgprog qual8
EXCLUDE CONNECTION ID: xconnid qual1,xconnid qual2,...,xconnid qual8
EXCLUDE CORRELATION ID: xcorrid qual1,xcorrid qual2,...,xcorrid qual8
EXCLUDE ROLE: xrole qual1,xrole qual2,...,xrole qual8
END TNO trace-number QUALIFICATIONS
DSNW185I BEGIN TNO trace-number AUDIT POLICIES
AUDIT POLICY: policy-name
END TNO trace-number AUDIT POLICIES

DSNW148I  ******END OF DISPLAY TRACE QUALIFICATION

DSNW198I DISPLAY TRACE OUTPUT TO BE CONTINUED (CMDID=command-id)

DSNW199I DISPLAY TRACE OUTPUT CONTINUED (CMDID=command-id)

DSN9022I  '-DISPLAY TRACE' NORMAL COMPLETION