START TRACE on z/OS

Use the MQSC command START TRACE to start traces.


Use MQSC commands

For information on how we use MQSC commands, see Performing local administration tasks using MQSC commands.

We can issue this command from sources 12CR. For an explanation of the source symbols, see Sources from which we can issue MQSC commands on z/OS .

Synonym: STA TRACE


START TRACE

START TRACE ( GLOBALACCTGCHINITSTAT ) CMDSCOPE(' ')CMDSCOPE(qmgr-name)1destination blockconstraint blockCOMMENT(string)Destination block DEST ( ,GTFRESSMFSRV ) Constraint blockCLASS(*)CLASS(,integerinteger:integer)IFCID(*)IFCID(,ifcid)RMID(*)RMID(,integer)TDATA(string)USERID(*)USERID(,string)Notes:

  • 1 Valid only when the queue manager is a member of a queue sharing group.


Usage notes

When we issue this command, a trace number is returned in message number CSQW130I. We can use this trace number (TNO) in ALTER TRACE, DISPLAY TRACE, and STOP TRACE commands.


Parameter descriptions for START TRACE

If we 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 our queue manager. The synonym is A.

    Class(4) statistics are supported for channel accounting, that is, SMF116 subtype 10 records.

    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 Use IBM MQ trace.

    CHINIT
    This includes data from the channel initiator. The synonym is CHI or DQM. If tracing for the channel initiator is started, it stops if the channel initiator stops.

    Note that we cannot issue START TRACE(CHINIT) if the command server or the channel initiator is not running.

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

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

    Class(4) statistics are supported for channel initiator statistics, that is, SMF115 subtype 231 records.

    CMDSCOPE
    This parameter specifies how the command runs 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 runs on the queue manager on which it was entered. This is the default value.

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

      We can specify a queue manager name, other than the queue manager on which the command was entered, only if we 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 CHINIT.

      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 IBM MQ are 115 and 116. For SMF record type 115, subtypes 1, 2, and 215 are provided for the performance statistics trace.

      SRV
      A serviceability routine reserved for IBM use only; not for general use. Note: If the IBM support center need you to use this destination for the 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 we issue the START TRACE command.

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

Type GTF RES SMF SRV
GLOBAL Allowed Default No Allowed
STAT No No Default Allowed
ACCTG Allowed No Default Allowed
CHINIT No Default No 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:

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

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

      (*)

      For GLOBAL and CHINIT traces, starts traces for all classes of data.

      For ACCTG and STAT traces, starts traces for classes 1 to 3. Channel initiator statistics and channel accounting data are not started with CLASS(*), and must be started with CLASS(4).

      ( integer )
      Any number in the class column of the table that follows. We 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 we do not specify a class, the default is to start class 1.

    Class Description
      Global trace
    01 Reserved for IBM service
    02 User parameter error detected in a control block
    03 User parameter error detected on entry to MQI
    User parameter error detected on exit from MQI
    User parameter error detected in a control block
    04 Reserved for IBM service
    Statistics trace
    01 Subsystem statistics
    Queue manager statistics
    02 Queue manager storage summary statistics.

    Class 1 statistics must also be enabled to collect this class of data.
    03 Queue manager storage detail summary.

    Class 1 statistics must also be enabled to collect this class of data.
    04 Channel initiator statistics
    Accounting trace
    01 The processor time spent processing MQI calls and a count of MQPUT, MQPUT1 and MQGET calls
    03 Enhanced accounting and statistical data
    04 Channel accounting data
    CHINIT trace
    01 Reserved for IBM service
    04 Reserved for IBM service

    IFCID
    Reserved for IBM service.

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

      (*)
      Starts a trace for all resource managers.

      This is the default.

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

    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
    163 Topic 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
    242 IBM 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. We cannot use this option for STAT, ACCTG, or CHINIT traces.

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

      ( userid )
      Names a user ID. We can use up to 8 user IDs; a separate trace is started for each. The user ID is the primary authorization ID of the task, used by IBM MQ inside the queue manager. This is the userid displayed by the MQSC command DISPLAY CONN.

Parent topic: MQSC commands