-STOP TRACE (Db2)

Environment

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

Authorization

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.

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.

Syntax

constraint block

Notes:

• ¹ You cannot specify CLASS or IFCID with AUDTPLCY. AUDTPLCY applies to trace type AUDIT.

filtering block

Option descriptions

SCOPE

Specifies the scope of the command.

( LOCAL )

Stops the trace only on the local Db2 subsystem.

(GROUP)

Stops the trace on all members of a data sharing group.

FL 509 You cannot specify SCOPE(GROUP) to stop audit traces that use tamper-proof audit policies.

ASID(x'dddd')

Specifies that the trace for an address space is to be stopped.

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

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.

COMMENT ( string )

Gives a comment that is reproduced in the trace output record for the STOP TRACE command (except in the resident trace tables).

string is any SQL string; it must be enclosed between apostrophes if it includes a blank, comma, or special character.

DEST

Limits stopping to traces started for particular destinations. You can use more than one value, but do not use the same value twice. If you do not specify a value for DEST, Db2 does not use destination to limit which traces to stop.

Abbreviation: D

Possible values and their meanings are:

Value

Trace destination

GTF

The generalized trace facility

SMF

The System Management Facility

SRV

An exit to a user-written routine

OP n

A specific destination.

n can be an integer from 1 to 8.

See -START TRACE (Db2) for a list of allowable destinations for each trace type.

CLASS( integer , …)

Limits stopping to traces started for particular classes. For descriptions of the allowable classes, see -START TRACE (Db2). You cannot specify a class if you did not specify a trace type.

Abbreviation: C

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

TNO( integer , …)

Limits stopping to particular traces, identified by their trace numbers (1 to 32, 01 to 09). You can use up to eight trace numbers. If you use more than one number, you can use only one value each for PLAN, AUTHID, and LOCATION.

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

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( * ).

( * )

Stops 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( * ).

( * )

Stops 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 stop 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 stop 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 stop a trace for a client with the LUNAME of LULA, enter the following command:

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

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

-STOP 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

Stops the IFCIDs that correspond to the categories specified in the listed audit policies. 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

Stopping specific traces

Each option that you use, except TNO, limits the effect of the command to active traces that were started using the same option, either explicitly or by default, with exactly the same parameter values. For example, the following command stops only the active traces that were started using the options PERFM and CLASS (1,2):

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

This command does not stop, for example, any trace started using CLASS(1).

You must specify a trace type or an asterisk. For example, the following command stops all active traces:

-STOP TRACE (*)

Traces that use monitor trace class 6

When stopping trace classes, a special circumstance occurs if monitor trace class 6 is active. Monitor trace class 6 enables and disables data propagation. To avoid accidentally stopping this trace class, the commands STOP TRACE(*) and STOP TRACE(MON) CLASS(*) fail if monitor trace class 6 is active.

To stop monitor trace class 6, you must explicitly specify it as one of the arguments of the CLASS option of the STOP TRACE command, including any other monitor trace classes that were started with monitor trace class 6. For example, if monitor trace class 6 was started with the command -START TRACE(MON) CLASS(1,3,6), the following command stops it:

-STOP TRACE(MON) CLASS(1,3,6)

In the case where monitor trace class 6 was started with the command -START TRACE(MON) CLASS(*), you must explicitly specify all 32 monitor trace classes to have monitor trace class 6 stopped:

-STOP TRACE(MON) CLASS(1,2,3,4,5,6,...32)

However, if monitor trace class 6 is not active the STOP TRACE(*) command stops all active traces.

Audit traces that use tamper-proof audit policies

FL 509 If you specify the STOP TRACE(*) command with the SCOPE(GROUP) option to stop an audit trace that uses a tamper-proof audit policy, the tamper-proof audit policy is not stopped for the data sharing group and message DSNW122I is issued. You cannot use SCOPE(GROUP) to stop tamper-proof audit policies.

Recommendation: FL 509 Stop all tamper-proof audit policies in one trace number group by using the STOP TRACE command. Doing so helps avoid the possibility of mismatching trace numbers among data sharing members if the SCOPE(GROUP) option is used to stop a tamper-proof audit policy.

To stop a tamper-proof audit policy on all members of a data sharing group, issue the STOP TRACE command on each member of the data sharing group.

Do not stop traces that were started by a IFI/IFC program

Before you stop an active trace, ensure that an IFI application program or the IFC Selective Dump utility (DSN1SDMP) did not start the trace. If you stop a trace started by DSN1SDMP, the DSN1SDMP utility abnormally terminates.

Stopping a trace for specific threads using the * wildcard

You can use the wildcard suffix, "*" to stop traces for certain threads. For example, if you specify -STOP TRACE PLAN (A,B,C*), Db2 will stop traces for threads "A", "B" and all threads starting with "C".

Stopping a trace for specific threads using the positional, (_) wildcard

You can use the positional wildcard, which is represented by the, "_" character, to stop traces for threads with a specific character in the middle, or when you want to stop the trace for threads of a specific length. For example, if you specify -STOP TRACE PLAN (A_C), all traces will be stopped for threads that are three characters that have "A" as the first character, and "C" as the third. If you want to stop tracing threads for plan "A_C", issue -STOP TRACE PLAN (A/_C). The "/" before the "_" tells Db2 to stop the trace for plans with an underscore in the name, rather than treating the underscore as a wildcard. The same logic applies if you are trying to stop a trace for a thread whose plan includes a "/" or "*" character. Because the character "/" is an escape character, if you are trying to stop the trace for a thread whose plan has a "/" character in it, you can specify, for example, -STOP TRACE PLAN (A//C) to stop the trace for threads for plan "A/C". You can also specify -STOP TRACE PLAN (A/*C) to stop the trace for threads for plan name "A*C".

Stopping a trace for multiple threads at once using wildcards

You also have the option of stopping the trace of multiple threads based on multiple trace qualifications. For example, you can specify -STOP TRACE PLAN (A*, B*, C*) to simultaneously stop the trace for ALL threads for plans that start with "A", "B", and "C". The wildcard character, "*" stops the trace for all threads. You can specify more complex combinations such as -STOP TRACE PLAN (A_B*, C*, AND C/_D*), which will stop the trace for 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)

Traces for all of the possible thread combinations listed above will be stopped with the command above.

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

Filtering threads using exclude functionality

When you specify an "X" with any constraint keyword, such as "XPLAN", you are using the exclude functionality for the –STOP TRACE command. You have the option of excluding specific types of threads when you are stopping traces. You can use the "X" character to exclude specific combinations of characters when you are stopping a trace. For example, you can specify -STOP TRACE XPLAN(A), to stop the trace for all 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 -STOP TRACE XPLAN (A*, B*) to stop the trace for all 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 (*) excludes all threads from your search, and is not allowed. You also cannot use the wildcard in the middle of a STOP TRACE command with exclude functionality, such as -STOP TRACE XPLAN (A*C). You can, however, specify -STOP TRACE XPLAN (A_ _ C *), which will stop the trace for 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 stop two traces at once. For example, you can specify -STOP TRACE XPLAN (A, B, C) USERID (D). This tells Db2 to stop tracing all threads for plans except "A", "B", or "C", only where the user ID is "D".

Combining trace qualifiers

You can customize the threads for which you stop a trace by specifying some threads, and excluding other threads. For example, you can specify -STOP TRACE USERID (A,B) XPLAN (C). This criterion only stops the trace for threads where the user ID is equal to "A" or "B", and the plan is not equal to "C". In this example, the trace for a thread where the user ID is "A" and the plan is equal to "D" would be stopped, but a trace for a thread where the user ID is "A" and plan is "C" would not be stopped.

You can introduce wildcards into your STOP TRACE commands to further customize the traces that are to be stopped. For example, you can specify -STOP TRACE PLAN (C*) USER ID (Z, X) XPLAN (C, D, E). In this example, for the trace to be stopped, 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. Therefore, a trace for a plan of CB, with a user ID of Z would be stopped, but a trace for a plan C with a user ID of X would not be stopped because the command specifies not to stop the trace for threads where the plan is "C", without additional characters in the thread.

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.

Examples

-STOP TRACE (*) DEST (GTF)

-STOP TRACE (ACCTG)
  PLAN (DSN8BC81)
  LOCATION (USIBMSTODB21)
  COMMENT('ACCTG TRACE FOR DSN8BC81')

-STOP TRACE (P) TNO(4)

-STOP TRACE (*) LOCATION (USIBMSTODB22)

-STOP TRACE=P

-STOP TRACE(MON)

-STOP TRACE(MON) SCOPE(GROUP)

-STO TRACE(AUDIT) DEST(GTF) AUDTPLCY(AUDITADMIN)