strmqtrc

Purpose

Use the strmqtrc command to enable tracing.

You must use the strmqtrc command from the installation associated with the queue manager that you are working with. You can find out which installation a queue manager is associated with using the dspmq -o installation command. This does not apply to a client product (for example, HP Integrity NonStop Server ) because there are no queue managers from which to request direct output.

Description

For the IBM MQ client on HP Integrity NonStop Server, you must direct your trace commands to specific processors. For example, if your client is running on processor 2 and your shell is on processor 1, initiating trace with strmqtrc <options> does not trace the client. In this case, run -cpu=2 strmqtrc is required.

Optional parameters

-m QMgrName

The name of the queue manager to trace. This parameter applies to server products only.

The following wildcards are allowed: asterisk (*), replacing zero or more characters, and question mark (?), replacing any single character. In command environments such as the UNIX shell, where the asterisk (*) and question mark (?) characters have special meaning, you must either escape the wildcard character or enclose it in quotation marks to prevent the command environment from operating on the wildcard character.

-e

Requests early tracing of all processes, making it possible to trace the creation or startup of a queue manager. If you include this flag, any process belonging to any component of any queue manager traces its early processing. The default is not to perform early tracing.

Use the following command to trace a client:

strmqtrc -e

You cannot use the -e flag with the -m flag, -i flag, the -p flag, the -c flag, or the -b flag. If you try to use the -e flag with the -m flag, the -i flag, the -p flag, the -c flag, or the -b flag, then an error message is issued.

-t TraceType

The points to trace and the amount of trace detail to record. By default all trace points are enabled and a default-detail trace is generated.

Alternatively, you can supply one or more of the options in the following list. For each tracetype value you specify, including -t all, specify either -t parms or -t detail to obtain the appropriate level of trace detail. If you do not specify either -t parms or -t detail for any particular trace type, only a default-detail trace is generated for that trace type.

Attention: When using the -t api option, you will see trace of the MQI calls, with all the input and output data blocks dumped in hexadecimal form.

You should be aware that IBM MQ internal programs also make MQI calls, and you will see trace files for those programs. Normally, the program names begin amq or runmq.

You should be aware that amqrmppa programs host many threads, some of which receive MQI calls over the network from client applications. In these threads you will see MQI calls in the -t api traces, but you must remember that the input arguments to those MQI calls traced in the amqrmppa program might not match every detail of the MQI calls made originally by the client.

Therefore, if you need to know, reliably, the input arguments to MQI calls made by the client application, you must use -t api tracing on the client machine directly.

If you supply multiple trace types, each must have its own -t flag. You can include any number of -t flags, if each has a valid trace type associated with it.

It is not an error to specify the same trace type on multiple -t flags.

Table 1. TraceType parameter values.

Value	Description
all	Output data for every trace point in the system (the default). The all parameter activates tracing at default detail level.
api	Output data for trace points associated with the MQI and major queue manager components.
commentary	Output data for trace points associated with comments in the IBM MQ components.
comms	Output data for trace points associated with data flowing over communications networks.
csdata	Output data for trace points associated with internal data buffers in common services.
csflows	Output data for trace points associated with processing flow in common services.
detail	Activate tracing at high-detail level for flow processing trace points.
Explorer	Output data for trace points associated with the IBM MQ Explorer.
java	Output data for trace points associated with applications using the IBM MQ classes for Java API.
lqmdata	Output data for trace points associated with internal data buffers in the local queue manager.
lqmflows	Output data for trace points associated with processing flow in the local queue manager.
mqxr	Output data for the Telemetry (MQXR) service
otherdata	Output data for trace points associated with internal data buffers in other components.
otherflows	Output data for trace points associated with processing flow in other components.
parms	Activate tracing at default-detail level for flow processing trace points.
remotedata	Output data for trace points associated with internal data buffers in the communications component.
remoteflows	Output data for trace points associated with processing flow in the communications component.
servicedata	Output data for trace points associated with internal data buffers in the service component.
serviceflows	Output data for trace points associated with processing flow in the service component.
spldata	Output data for trace points associated with buffers and control blocks that use a security policy (AMS) operation.
splflows	Output data for trace points associated with entry and exit data for functions that use a security policy (AMS) operation.
soap	Output data for trace points associated with IBM MQ Transport for SOAP.
ssl	Output data associated with using GSKit to enable Secure Sockets Layer (SSL) channel security.
versiondata	Output data for trace points associated with the version of IBM MQ running.

-x TraceType

The points not to trace. By default all trace points are enabled and a default-detail trace is generated. The trace points you can specify are those listed for the -t flag.

You can use the -x flag with tracetype values to exclude those entry points you do not want to record. This is useful in reducing the amount of trace produced.

If you supply multiple trace types, each must have its own -x flag. You can include any number of -x flags, if each has a valid tracetype associated with it.

-l MaxSize

The maximum size of a trace file ( AMQppppp.qq.TRC) in megabytes (MB), where ppppp refers to the operating system process ID of the particular IBM MQ process being traced and qq is a sequence number if there is already a file with that name. For example, if you specify a MaxSize of 1, the size of the trace is limited to 1 MB.

When a trace file reaches the specified maximum, it is renamed to AMQppppp.qq.TRS and a new AMQppppp.qq.TRC file is started. If a previous copy of an AMQppppp.qq.TRS file exists, it is deleted.

The highest value that MaxSize can be set to is 2048 MB.

-d 0

Trace no user data.

-d -1 or all

Trace all user data.

-d NumOfBytes

• For a communication trace; trace the specified number of bytes of data including the transmission segment header (TSH).
• For an MQPUT or MQGET call; trace the specified number of bytes of message data held in the message buffer.
• Values in the range 1 through 15 are not allowed.

-i PidTids

Process identifier (PID) and thread identifier (TID) to which the trace generation is restricted. You cannot use the -i parameter with the -e parameter. If you try to use the -i parameter with the -e parameter, then an error message is issued.

The precise format of this parameter is PID[.TID]. For example:

• Coding -i 12345 traces all threads in PID 12345, whereas
• Coding -i 12345.67 traces only thread 67 in PID 12345

This parameter is not supported for .NET clients if NMQ_MQ_LIB is set to managed, so that the client uses managed IBM MQ problem diagnostics.

-p Apps

The named processes to which the trace generation is restricted. Apps is a comma-separated list. You must specify each name in the list exactly as the program name would be displayed in the "Program Name" FDC header. Asterisk (*) or question mark (?) wildcards are allowed. You cannot use the -p flag with the -e flag. If you try to use the -p flag with the -e flag, then an error message is issued.

This parameter is not supported for .NET clients if NMQ_MQ_LIB is set to managed, so that the client uses managed IBM MQ problem diagnostics.

-s

Reports the tracing options that are currently in effect. You must use this parameter on its own with no other parameters.

A limited number of slots are available for storing trace commands. When all slots are in use, then no more trace commands can be accepted unless they replace an existing slot. Slot numbers are not fixed, so if the command in slot number 0 is removed, for example by an endmqtrc command, then all the other slots move up, with slot 1 becoming slot 0, for example. An asterisk (*) in a field means that no value is defined, and is equivalent to the asterisk wildcard.

An example of the output from this command is as follows:

Listing Trace Control Array

Used slots = 2 of 15

EarlyTrace    [OFF]
TimedTrace    [OFF]
TraceUserData [0]
MaxSize       [0]
Trace Type    [1]

Slot position 1

Untriggered
Queue Manager [avocet]
Application   [*]
PID.TID       [*]
TraceOptions  [1f4ffff]
TraceInterval    [0]
Trace Start Time [0]
Trace Stop  Time [0]
Start Trigger [KN346050K]
Start Trigger [KN346080]

Slot position 2

Untriggered
Queue Manager [*]
Application   [*]
PID.TID       [*]
TraceOptions  [1fcffff]
TraceInterval    [0]
Trace Start Time [0]
Trace Stop  Time [0]
Start Trigger [KN346050K]
Start Trigger [KN346080]

This parameter is not supported for .NET clients if NMQ_MQ_LIB is set to managed, so that the client uses managed IBM MQ problem diagnostics.

-b Start_Trigger

FDC probe IDs for which tracing must be turned on. Start_Trigger is a comma-separated list of FDC probe IDs. You can use asterisk (*) and question mark (?) wildcards in the specification of probe IDs. You cannot use the -b flag with the -e flag. If you try to use the -b flag with the -e flag, then an error message is issued. This parameter must only be used under the guidance of IBM Service personnel.

Start_Trigger	Effect
FDC=comma-separated list of FDC probe IDs.	Turns on tracing when any FDCs with the specified FDC probe IDs are generated.

This parameter is not supported for .NET clients if NMQ_MQ_LIB is set to managed, so that the client uses managed IBM MQ problem diagnostics.

-c Stop_Trigger

FDC probe IDs for which tracing must be turned off, or interval in seconds after which tracing must be turned off. Stop_Trigger is a comma-separated list of FDC probe IDs. You can use asterisk (*) and question mark (?) wildcards in the specification of probe IDs. This parameter should be used only under the guidance of IBM Service personnel.

Stop_Trigger	Effect
FDC=comma-separated list of FDC probe IDs.	Turns tracing off when any FDCs with the specified FDC probe IDs are generated.
interval=n where n is an unsigned integer between 1 and 32,000,000.	Turns tracing off n seconds after it starts or, if it tracing is already enabled, turns tracing off n seconds after this instance of the command is issued.

This parameter is not supported for .NET clients if NMQ_MQ_LIB is set to managed, so that the client uses managed IBM MQ problem diagnostics.

Return codes

Related commands