mqsichangetrace command

Supported platforms

  • Windows
  • Linux and UNIX systems
  • z/OS

Purpose

Use the mqsichangetrace command to set the tracing characteristics for a component. This command is valid for:
  • User trace. Specify the -u option.
  • Service trace. Specify the -t option. You are recommended to use this option only if directed to do so by the action described in a BIPxxxx message, or by your IBM Support Center.

You can initiate, modify, or terminate user tracing for a broker, or initiate, modify, or terminate service tracing for a broker, a Configuration Manager, or the User Name Server (identified by component name). You cannot use this command to initiate service tracing for the workbench.

On Windows platforms, Linux, and UNIX systems, you can also start and stop tracing activity for execution groups and message flows using the facilities of the workbench. See User trace for more information.

On z/OS, you can also start, modify, or stop a trace using the console commands or using the facilities of the workbench.

If you specify a broker, or any of its resources (execution group or message flow), you must have deployed them before you can start trace.

The trace output generated by these commands is written to trace files in the log subdirectory. When you have completed the work you want to trace, use mqsireadlog to retrieve the log as an XML format file. Use either mqsiformatlog (to produce a formatted file) or an XML browser to view the XML records.

When you set tracing on, you cause additional processing to be executed for every activity in the component you are tracing. You must expect to see some impact on performance when trace is active.

If you want to trace the command processes themselves, set the environment variables MQSI_UTILITY_TRACE and MQSI_UTILITY_TRACESIZE before you initiate trace.

Ensure that you reset these variables when tracing for the selected command is complete. If you do not do so, all subsequent commands are also traced, and their performance degraded.

Syntax

Windows platforms, Linux, and UNIX systems

User trace

Service trace

z/OS

User trace

Service trace

Parameters

component
(Required - Windows platforms, Linux, and UNIX systems) The name of the component for which trace parameters are to be changed. This can either be the name of a broker, or of a Configuration Manager, or the fixed value, UserNameServer (all are case sensitive on UNIX systems and on Linux).

Start of changeKey words workbench and utility are reserved and must not be used as a component name.End of change

-u
Start of change(Required for user trace only if the component is a broker) Specifies that user trace options are to be modified. This option is only valid if you have:
  • Specified a broker name as the component name on Windows platforms, Linux, and UNIX systems.
  • Issued this command against a broker (that is, not a Configuration Manager or User Name Server) on z/OS.
.End of change
-e egName
Start of change(Required for user trace; optional for service trace) Identifies the execution group for which trace options are to be modified (for example, started or stopped). This option is only valid for a broker.

On z/OS, this name is case sensitive and you should include the names in single quotes if they contain mixed case characters.

End of change
-f messageflow
(Optional) Identifies the message flow for which trace options are to be modified. This option is only valid if you have specified an execution group (flag -e).

On z/OS, this name is case sensitive and you should include the names in single quotes if they contain mixed case characters.

-r
(Optional) This option requests that the trace log is reset: that is, all current records are discarded. Use this option when you start a new trace to ensure that all records in the log are unique to the new trace.

This option is only valid if you have specified an execution group (flag -e).

-l level
(Optional) Set the level of the trace. This must be one of:
  • normal. This provides a basic level of trace information.
  • none. This sets tracing off.
  • debug. This provides a more comprehensive trace.

Each component is created with a default value of none. If you do not specify this parameter, the current value is unchanged. Once you successfully change this value, it is persistent.

This is valid for all components.

-m mode
(Optional) Indicate the way trace information is to be buffered:
  • safe. This mode causes trace entries to be written to file when they are generated.
  • fast. This mode causes trace entries to be buffered, and only written to file in batches.

Each component starts with a default value of safe. If you do not specify this parameter, the current value is unchanged.

This option is only valid if the component you have specified is:
  • A broker. If you change this value, it affects tracing for the execution group (if you have specified one), or for the agent component (if you have not specified an execution group).
  • The User Name Server. If you change this value, it affects tracing for the entire component. (This is only valid for service trace.) Once you successfully change this value, it is persistent.
-c size
(Optional) The size of the trace file in KB (kilobytes). If you do not specify this parameter, the current value is left unchanged. Each component starts with a default value of 4096 KB. Specify this option to reset the value. The maximum value you can specify depends on how you subsequently intend to read the log, using the mqsireadlog command.

On HP-UX you are recommended to set this value below 500 MB.

  • If you use mqsireadlog with the -f option set, the log file is read directly from the file system. In this case, the maximum value that can be specified here is 2097151, which will allow a trace file up to 2 GB (gigabyte) to be created.
  • If you use mqsireadlog without setting the -f option, a WebSphere MQ message is sent to the broker to retrieve the log. In this case, the trace file size should not exceed 70 MB (megabytes). The maximum value that you can set here, should not be appreciably more than 70000.

However you intend to retrieve the trace file, you are recommended to keep its size as small as possible, either by using a low value for this parameter or by using the reset (-r) option on this command to clear the trace log. The benefit of adopting this approach is that the formatting process (mqsiformatlog) is much faster and requires less resource to carry out its task.

This option is only valid if the component you have specified is:
  • A broker. If you change this value, it affects tracing for the execution group (if you have specified one), or for the agent component (if you have not specified an execution group).
  • The User Name Server. If you change this value, it affects tracing for the entire component. (This is only valid for service trace.)

If you change the trace size, the new value is persistent over a restart of the broker or User Name Server.

Additional parameters exclusive to service trace

Use these options only when directed to do so by your IBM Support Center or by a BIPxxxx message.

-t
Start of change(Required) Specifies that service trace options are to be modified.End of change
-b
Start of change(Required) Specifies that service trace options for the agent subcomponent of the component specified are to be modified (for example, started or stopped). You can only specify this flag if -t is also specified.End of change

Authorization

The user ID used to issue the command must have mqbrkrs authority.

Responses

This command returns the following responses:
  • BIP2595 Error casting character string '...' to an integer (z/OS only)
  • BIP8002 Selected flags incompatible (z/OS only)
  • BIP8003 Duplicate flag detected (z/OS only)
  • BIP8013 Component does not exist
  • BIP8020 Unable to access database
  • BIP8029 Broker not configured
  • BIP8031 Invalid flag supplied
  • BIP8032 Unable to connect to queue
  • BIP8033 Message send failure
  • BIP8035 Response not received before time-out
  • BIP8036 Negative response received
  • BIP8037 Unsupported flag
  • BIP8039 Execution group not available
  • BIP8040 Unable to connect to database
  • BIP8045 Message flow not found
  • BIP8068 Integer argument required
  • BIP8158 Invalid format for command (z/OS only)
  • BIP8159 Unknown parameter "..." (z/OS only)

Examples

Windows platforms, Linux, and UNIX systems:

To collect and process a user trace for the default execution group use the command:
mqsichangetrace WBRK_BROKER -u -e default -l normal -c 5000
To collect and process a service trace for flow f1 in the default execution group use the command:
mqsichangetrace WBRK_BROKER -u -e default -m fast
To collect and process a service trace for an agent use the command:
mqsichangetrace WBRK_BROKER -t -b -m -l normal

z/OS:

To collect and process a user trace for the default execution group use the command:
F MQP1BRK,ct u=yes,e='default',l=normal,c=5000
and in the PDSE member BIPJLOG, set the option for mqsireadlog to
-u -e default
To collect and process a service trace for flow f1 in the default execution group use the command:
F MQP1BRK,ct u=yes,e='default',f='f1',m=fast
and in the PDSE member BIPJLOG, set the option for mqsireadlog to
-t -e default -f f1-
To collect and process a service trace for an agent use the command:
F MQP1BRK,ct t=yes,b=yes,m=fast,l=debug
and in the PDSE member BIPJLOG, set the option for mqsireadlog to
-t -b agent
Related tasks
Using trace