START TRACE on z/OS

Use the MQSC command START TRACE to start traces.

Using MQSC commands

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

You can issue this command from sources 12CR. For an explanation of the source symbols, see Using commands on z/OS®.

Syntax diagram
Usage notes
Parameter descriptions for START TRACE
Destination block
Constraint block

Synonym: STA TRACE

START TRACE

Destination block

Constraint block

Notes:

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

Usage notes

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.

Parameter descriptions for START TRACE

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

ACCTG

Enables accounting data which provides information about how applications are interacting with the queue manager in the form of SMF 116 records. 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 Using 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 you 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

Enables high level statistics about the state of the queue manager in the form of SMF 115 records. The synonym is S.

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.
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 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 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 1. 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
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:

Table 2. 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
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:

(*): 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, except when you are using the START TRACE(STAT) command with no class where the default is to start class 1 and 2.

Table 3. Descriptions of trace events and classes.
Table showing the different trace events produced for the various trace classes.
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
03	Queue manager storage detail summary
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. You 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. You can use up to 8 of the allowed resource manager identifiers; do not use the same one twice.

Table 4. 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
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. You 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. You 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.