dspmqrte (display route information)

Determine the route that a message has taken through a queue manager network.

Purpose

You can use the dspmqrte to generate a trace-route message and put it into a queue manager network. As the trace-route message travels through the queue manager network, activity information is recorded. When the trace-route message reaches its target queue, the activity information is collected and displayed.

Syntax

Generation options

Display options

Parameters

-q TargetQName: Specifies the name of the target queue to send the trace-route message to.; If the command is being used to view previously gathered activity information, TargetQName specifies the name of the queue where the activity information is stored.; This parameter is required.
-c: Specifies that the command connects as a client application.
-i CorrelId: Specifies the message identifier of the original trace-route message when displaying previously accumulated activity information.; There can be many activity reports and trace-route reply messages on the queue specified by -q TargetQName. Therefore, -i can be used to identify the activity reports, or a trace-route reply message, related to a specific trace-route message.; Specify CorrelId as a 48 character hexadecimal string.
-m QMgrName: Specifies the name of the queue manager to which the command connects.; The name can contain up to 48 characters.; The default value is the default queue manager.

The following parameters are used when the command is used to put a trace-route message into a queue manager network. That is, the parameters are the generation options:

-ac

Specifies that activity information is to be accumulated within the trace-route message.

If you do not specify this parameter, activity information is not accumulated within the trace-route message.

-ar

Specifies that a trace-route reply message containing all accumulated activity information is generated in the following circumstances:

The trace-route message is discarded by a queue manager.
The trace-route message is put to a local queue (target queue or dead-letter queue) by a queue manager.
The number of activities performed on the trace-route message exceeds the value of specified in -s Activities.

If you do not specify this parameter, a trace-route reply message is not requested.

-d Deliver

Specifies whether the trace-route message is to be delivered to the target queue on arrival.

Deliver can be one of the following values:

yes: On arrival, the trace-route message is put to the target queue, even if the queue manager does not support trace-route messaging
no: On arrival, the trace-route message is not put to the target queue.

The default value is no.

-f Forward

Specifies the type of queue manager that the trace-route message can be forwarded to.

Forward can be one of the following values:

all: The trace-route message is forwarded to any queue manager.; If forwarded to a queue manager before IBM WebSphere MQ 6.0, the trace-route message is not recognized and can be delivered to a local queue despite the value of the -d parameter.
supported: The trace-route message is only forwarded to a queue manager that honors the value of the -d parameter.

The default value is supported.

-l Persistence

Specifies the persistence of the generated trace-route message.

Persistence can be one of the following values:

yes: The generated trace-route message is persistent. (MQPER_PERSISTENT); If you use this value, you must specify the parameter -rq ReplyToQ. The reply-to queue must not resolve to a temporary dynamic queue.
no: The generated trace-route message is not persistent. (MQPER_NOT_PERSISTENT).
q: The generated trace-route message inherits its persistence value from the queue specified by -q TargetQName. (MQPER_PERSISTENCE_AS_Q_DEF).

A trace-route reply message, or any report messages, returned shares the same persistence value as the original trace-route message.

The default value is no.

-o

Specifies that the target queue is not bound to a specific destination.

Typically this parameter is used when the trace-route message is to be put across a cluster. The target queue is opened with option MQOO_BIND_NOT_FIXED.

If you do not specify this parameter, the target queue is bound to a specific destination.

-p Priority

Specifies the priority of the trace-route message.

The value of Priority is either greater than or equal to 0, or MQPRI_PRIORITY_AS_Q_DEF. MQPRI_PRIORITY_AS_Q_DEF specifies that the priority value is taken from the queue specified by -q TargetQName.

The default is that the priority value is taken from the queue specified by -q TargetQName.

-qm TargetQMgrName

Specifies the target queue manager for the target queue.

The target queue is specified with -q TargetQName.

The default is that the queue manager to which the command is connected is used as the reply-to queue manager.

-ro ReportOption

ReportOption can be one or more of the following values specified in a comma-separated list:

none: Specifies that no report options are set.
activity: The report option MQRO_ACTIVITY is set.
coa: The report option MQRO_COA_WITH_FULL_DATA is set.
cod: The report option MQRO_COD_WITH_FULL_DATA is set.
exception: The report option MQRO_EXCEPTION_WITH_FULL_DATA is set.
expiration: The report option MQRO_EXPIRATION_WITH_FULL_DATA is set.
discard: The report option MQRO_DISCARD_MSG is set.

The default value is activity, discard.

-rq ReplyToQ

Specifies the name of the reply-to queue that all responses to the trace-route message are sent to.

If the trace-route message is persistent, or if the -n parameter is specified, a reply-to queue must be specified that is not a temporary dynamic queue.

If you do not specify this parameter, the system default model queue, SYSTEM.DEFAULT.MODEL.QUEUE is used as the reply-to queue. Using this model queue causes a temporary dynamic queue to be created.

-rqm ReplyToQMgr

Specifies the name of the queue manager where the reply-to queue is located.

The name can contain up to 48 characters.

If you do not specify this parameter, the queue manager to which the command is connected is used as the reply-to queue manager.

-s Activities

Specifies the maximum number of recorded activities that can be performed on behalf of the trace-route message before it is discarded.

This parameter prevents the trace-route message from being forwarded indefinitely if caught in an infinite loop.

The value of Activities is either greater than or equal to 1, or MQROUTE_UNLIMITED_ACTIVITIES. MQROUTE_UNLIMITED_ACTIVITIES specifies that an unlimited number of activities can be performed on behalf of the trace-route message.

If you do not specify this parameter, an unlimited number of activities can be performed on behalf of the trace-route message.

-t Detail

Specifies the activities that are recorded.

Detail can be one of the following values:

low: Activities performed by user-defined application are recorded only.
medium: Activities specified in low are recorded. Additionally, activities performed by MCAs are recorded.
high: Activities specified in low, and medium are recorded. MCAs do not expose any further activity information at this level of detail. This option is available to user-defined applications that are to expose further activity information only. For example, if a user-defined application determines the route a message takes by considering certain message characteristics, the routing logic can be included with this level of detail.

The default value is medium.

-ts TopicString

Specifies a topic string to which the command is to publish a trace-route message, and puts the command into topic mode.

In this mode, the command traces all of the messages that result from the publish request.

-u userID

User ID to use for connecting to a queue manager.

-xp PassExpiry

Specifies whether the report option MQRO_DISCARD_MSG and the remaining expiry time from the trace-route message is passed on to the trace-route reply message.

PassExpiry can be one the following values:

yes: The report option MQRO_PASS_DISCARD_AND_EXPIRY is specified in the message descriptor of the trace-route message.; If a trace-route reply message, or activity reports, are generated for the trace-route message, the MQRO_DISCARD_MSG report option (if specified), and the remaining expiry time are passed on.
no: The report option MQRO_PASS_DISCARD_AND_EXPIRY is not specified.; If a trace-route reply message is generated for the trace-route message, the discard option and remaining expiry time from the trace-route message are not passed on.

The default value is yes.

-xs Expiry

Specifies the expiry time for the trace-route message, in seconds.

The default value is 60.

-n

Specifies that activity information returned for the trace-route message is not to be displayed.

If this parameter is accompanied by a request for a trace-route reply message (-ar), or any of the report generating options (-ro ReportOption), then a specific (non-model) reply-to queue must be specified using -rq ReplyToQ.

After the trace-route message is put to the specified target queue, a 48 character hexadecimal string is returned containing the message identifier of the trace-route message. The message identifier can be used by the command to display the activity information for the trace-route message at a later time. This can be done using the -i CorrelId parameter.

By default, activity report messages are requested.

The following parameters are used when the command is used to display collected activity information. That is, the parameters are the display options:

-b

Specifies that the command only browses activity reports or a trace-route reply message related to a message.

This parameter allows activity information to be displayed again at a later time.

If you do not specify this parameter, the command gets activity reports or a trace-route reply message related to a message, and deletes them.

-v summary | all | none | outline DisplayOption

The values can be the following values:

summary

The queues that the trace-route message was routed through are displayed.

all

All available information is displayed.

none

No information is displayed.

outline DisplayOption

Specifies display options for the trace-route message.

DisplayOption can be one or more of the following values, using a comma as a separator:

activity: All non-PCF group parameters in Activity PCF groups are displayed.
identifiers: Values with parameter identifiers MQBACF_MSG_ID or MQBACF_CORREL_ID are displayed.; This value overrides msgdelta.
message: All non-PCF group parameters in Message PCF groups are displayed.; When this value is specified, you cannot specify msgdelta.
msgdelta: All non-PCF group parameters in Message PCF groups, that have changed since the last operation, are displayed.; When this value is specified, you cannot specify message.
operation: All non-PCF group parameters in Operation PCF groups are displayed.
traceroute: All non-PCF group parameters in TraceRoute PCF groups are displayed.

If no values are supplied for DisplayOption the application name, the type of each operation, and any operation specific parameters are displayed.

The default value is summary.

-w WaitTime

Specifies the time, in seconds, that the command waits for activity reports, or a trace-route reply message, to return to the specified reply-to queue.

The default value is the expiry time of the trace-route message, plus 60 seconds.

Usage notes

This command must be run from the IBM® MQ administration mode. If the system is in the IBM MQ administration mode the prompt includes mqa(mqcli)#. To enter the IBM MQ administration mode, enter mqcli on the command line. To exit the IBM MQ administration mode, enter exit on the command line.
For more information about this command in IBM MQ, see dspmqrte in the IBM MQ documentation.

Examples

The following command puts a trace-route message into a queue manager network with the target queue specified as TARGET.Q. Providing queue managers on route are enabled for activity recording, activity reports are generated. Depending on the queue manager attribute, ACTIVREC, activity reports are either delivered to the reply-to queue ACT.REPORT.REPLY.Q, or are delivered to a system queue. The trace-route message is discarded on arrival at the target queue.
```
dspmqrte -q TARGET.Q -rq ACT.REPORT.REPLY.Q
```
Providing one or more activity reports are delivered to the reply-to queue, ACT.REPORT.REPLY.Q, the command orders and displays the activity information.
The following command puts a trace-route message into a queue manager network with the target queue specified as TARGET.Q. Activity information is accumulated within the trace-route message, but activity reports are not generated. On arrival at the target queue, the trace-route message is discarded. Depending on the value of the target queue manager attribute, ROUTEREC, a trace-route reply message can be generated and delivered to either the reply-to queue, TRR.REPLY.TO.Q, or to a system queue.
```
dspmqrte -ac -ar -ro discard -rq TRR.REPLY.TO.Q -q TARGET.Q
```
Providing a trace-route reply message is generated, and delivered to the reply-to queue TRR.REPLY.TO.Q, the command orders and displays the activity information that was accumulated in the trace-route message.