START TRACE

Use START TRACE to start traces. When you issue this command, a trace number is returned in message number CSQW130I. You can use this trace number (TNO) in ALTER TRACE, DISPLAY TRACE, and STOP TRACE commands.

Synonym: STA TRACE 

START TRACE
 
                  .-GLOBAL-.    .-CMDSCOPE(' ')------------.
>>-START TRACE--(-+--------+-)--+--------------------------+---->
                  +-ACCTG--+    |                     (1)  |
                  '-STAT---'    '-CMDSCOPE(qmgr-name)------'
 
>--+-----------------------+--+----------------------+---------->
   '-| destination block |-'  '-| constraint block |-'
 
>--+-----------------+-----------------------------------------><
   '-COMMENT(string)-'
 
Destination block
 
           .-,-------.
           V         |
|--DEST--(---+-GTF-+-+-)----------------------------------------|
             +-RES-+
             +-SMF-+
             '-SRV-'
 
Constraint block
 
   .-CLASS(*)---------------------.  .-IFCID(*)-----------.
|--+------------------------------+--+--------------------+----->
   |          .-,-------.         |  |        .-,-----.   |
   |          V         |         |  |        V       |   |
   '-CLASS(-+---integer-+-----+-)-'  '-IFCID(---ifcid-+-)-'
            '-integer:integer-'
 
   .-RMID(*)-------------.
>--+---------------------+--+---------------+------------------->
   |       .-,-------.   |  '-TDATA(string)-'
   |       V         |   |
   '-RMID(---integer-+-)-'
 
   .-USERID(*)------------.
>--+----------------------+-------------------------------------|
   |         .-,------.   |
   |         V        |   |
   '-USERID(---string-+-)-'

Notes:

  1. Valid only on full function WebSphere MQ for z/OS when the queue manager is a member of a queue-sharing group.

 

Parameter descriptions

If you do not specify a trace type to be started, the default (GLOBAL) trace is started. The types are:

ACCTG
Collects accounting data that can be used to charge your customers for their use of your queue manager. The synonym is A.

Note:
Accounting data can be lost if the accounting trace is started or stopped while applications are running. For information about the conditions that must be satisfied for successful collection of accounting data, see the WebSphere MQ for z/OS System Setup Guide.

GLOBAL
This includes data from the entire queue manager. The synonym is G.

STAT
Collects statistical data broadcast by various components of WebSphere MQ, at time intervals that can be chosen during installation. The synonym is S.

CMDSCOPE
This parameter specifies how the command is executed when the queue manager is a member of a queue-sharing group.

CMDSCOPE cannot be used for commands issued from the first initialization input data set CSQINP1.

' '
The command is executed on the queue manager on which it was entered. This is the default value.

qmgr-name
The command is executed on the queue manager you specify, providing the queue manager is active within the queue-sharing group.

You can specify a queue manager name, other than the queue manager on which the command was entered, only if you are using a queue-sharing group environment and if the command server is enabled.

COMMENT(string)
Specifies a comment that is reproduced in the trace output record (except in the resident trace tables). It can be used to record why the command was issued.

string is any character string. It must be enclosed in single quotation marks if it includes a blank, comma, or special character.

 

Destination block

DEST
Specifies where the trace output is to be recorded. More than one value can be specified, but do not use the same value twice.

The meaning of each value is as follows:

GTF
The z/OS Generalized Trace Facility (GTF). If used, the GTF must be started and accepting user (USR) records before the START TRACE command is issued.

RES
A wrap-around table residing in the ECSA, or a data space for RMID 231.

SMF
The System Management Facility (SMF). If used, the SMF must be functioning before the START TRACE command is issued. The SMF record numbers used by WebSphere MQ are 115 and 116.

SRV
A serviceability routine reserved for IBM use only; not for general use.

Note:
If your IBM support center need you to use this destination for your trace data they will supply you with module CSQWVSER. If you try to use destination SRV without CSQWVSER an error message is produced at the z/OS console when you issue the START TRACE command.

Allowed values, and the default value, depend on the type of trace started, as shown in the following table:

Table 12. Destinations allowed for each trace type

Type GTF RES SMF SRV
GLOBAL Allowed Default No Allowed
STAT No No Default Allowed
ACCTG Allowed No Default Allowed

 

Constraint block

The constraint block places optional constraints on the kinds of data collected by the trace. The allowed constraints depend on the type of trace started, as shown in the following table:

Table 13. Constraints allowed for each trace type

Type CLASS IFCID RMID USERID
GLOBAL Allowed Allowed Allowed Allowed
STAT Allowed No No No
ACCTG Allowed No No No

CLASS
Introduces a list of classes of data gathered. The classes allowed, and their meaning, depend on the type of trace started:

(*)
Starts a trace for all classes of data.

(integer)
Any number in the class column of the table that follows. You can use more than one of the classes that are allowed for the type of trace started. A range of classes can be specified as m:n (for example, CLASS(01:03)). If you do not specify a class, the default is to start class 1.


Table 14. Descriptions of trace events and classes

Class IFCID Description
Global trace
01 0000 Reserved for IBM service
02 0018 User parameter error detected in a control block
03 0016 User parameter error detected on entry to MQI
  0017 User parameter error detected on exit from MQI
  0018 User parameter error detected in a control block
04 Various Reserved for IBM service
    Statistics trace
01 0001 Subsystem statistics
  0002 Queue manager statistics
    Accounting trace
01 0003 The CPU time spent processing MQI calls and a count of MQPUT and MQGET calls
03 0025 Enhanced accounting and statistical data

IFCID
Reserved for IBM service.

RMID
Introduces a list of specific resource managers for which trace information is gathered. You cannot use this option for STAT or ACCTG traces.

(*)
Starts a trace for all resource managers. This is the default. If any of the conditions below for RMID 231 are true, tracing does not start for that resource manager.

(integer)
The identifying number of any resource manager in Table 15. You can use up to 8 of the allowed resource manager identifiers; do not use the same one twice.

If the list of RMIDs includes 231 explicitly, the command fails if the channel initiator is not started or if one of the following is true:

  • TRACE(STAT) or TRACE(ACCTG) is specified

  • The list of destinations does not include RES

  • This list of classes does not include 01 or 04

Also, comments are truncated to 120 characters.

If tracing for RMID 231 is started, it stops if the channel initiator is stopped.


Table 15. Resource Manager identifiers that are allowed

RMID Resource manager
1 Initialization procedures
2 Agent services management
3 Recovery management
4 Recovery log management
6 Storage management
7 Subsystem support for allied memories
8 Subsystem support for subsystem interface (SSI) functions
12 System parameter management
16 Instrumentation commands, trace, and dump services
23 General command processing
24 Message generator
26 Instrumentation accounting and statistics
148 Connection manager
197 CF manager
199 Functional recovery
200 Security management
201 Data management
211 Lock management
212 Message management
213 Command server
215 Buffer management
231 Channel Initiator
242 WebSphere MQ-IMS bridge
245 DB2 manager

TDATA
Reserved for IBM service.

USERID
Introduces a list of specific user IDs for which trace information is gathered. You cannot use this option for STAT or ACCTG traces.

(*)
Starts a trace for all user IDs. This is the default.

(userid)
Names a user ID. You can use up to 8 user IDs; a separate trace is started for each.

 

WebSphere is a trademark of the IBM Corporation in the United States, other countries, or both.

 

IBM is a trademark of the IBM Corporation in the United States, other countries, or both.