dspmqrte (display route information)

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

Purpose

The IBM MQ display route application (dspmqrte) command can be run on all platforms except z/OS . We can run the IBM MQ display route application as a client to an IBM MQ for z/OS queue manager by specifying the -c parameter when issuing the dspmqrte command.

The IBM MQ display route application generates and puts a trace-route message 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 by the IBM MQ display route application and displayed. For more information, and examples of using the IBM MQ display route application, see IBM MQ display route application.

Syntax

• ¹ If Persistence is specified as yes, and is accompanied by a request for a trace-route reply message ( -ar ), or any report generating options ( -ro ReportOption ), then we must specify the parameter -rq ReplyToQ. The reply-to queue must not resolve to a temporary dynamic queue.
• ² 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 . By default, activity report messages are requested.

Required parameters

-q TargetQName

If the IBM MQ display route application is being used to send a trace-route message into a queue manager network, TargetQName specifies the name of the target queue.

If the IBM MQ display route application is being used to view previously gathered activity information, TargetQName specifies the name of the queue where the activity information is stored.

Optional parameters

-c

Specifies that the IBM MQ display route application connects as a client application. For more information about how to set up client machines, see:

• Installing an IBM MQ client on an AIX workstation
• Installing an IBM MQ client on a Linux workstation
• Installing an IBM MQ client on a Windows workstation
• Installing an IBM MQ client on an IBM i workstation

This parameter can be used only if the client component is installed.

-i CorrelId

This parameter is used when the IBM MQ display route application is used to display previously accumulated activity information only. There can be many activity reports and trace-route reply messages on the queue specified by -q TargetQName. CorrelId is used to identify the activity reports, or a trace-route reply message, related to a trace-route message. Specify the message identifier of the original trace-route message in CorrelId.

The format of CorrelId is a 48 character hexadecimal string.

-m QMgrName

The name of the queue manager to which the IBM MQ display route application connects. The name can contain up to 48 characters.

If we do not specify this parameter, the default queue manager is used.

Generation options

The following parameters are used when the IBM MQ display route application is used to put a trace-route message into a queue manager network.

-ac

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

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

-ar

Requests 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 IBM WebSphere MQ Version 7.0 queue manager.
• The trace-route message is put to a local queue (target queue or dead-letter queue) by a IBM WebSphere MQ Version 7.0 queue manager.
• The number of activities performed on the trace-route message exceeds the value of specified in -s Activities.

For more information about trace-route reply messages, see Trace-route reply message reference.

If we 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. Possible values for Deliver are:

Value	Description
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.

If we do not specify this parameter, the trace-route message is not put to the target queue.

-f Forward

Specifies the type of queue manager that the trace-route message can be forwarded to. Queue managers use an algorithm when determining whether to forward a message to a remote queue manager. For details of this algorithm, see The cluster workload management algorithm. The possible values for Forward are:

Value	Description
all	The trace-route message is forwarded to any queue manager. Warning: If forwarded to an IBM WebSphere MQ queue manager before Version 6.0, the trace-route message is not recognized and can be delivered to a local queue despite the value of the -d Deliver parameter.
supported	The trace-route message is only forwarded to a queue manager that honors the Deliver parameter from the TraceRoute PCF group.

If we do not specify this parameter, the trace-route message is only forwarded to a queue manager that honors the Deliver parameter.

-l Persistence

Specifies the persistence of the generated trace-route message. Possible values for Persistence are:

Value	Description
yes	The generated trace-route message is persistent. (MQPER_PERSISTENT).
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.

If Persistence is specified as yes, we must specify the parameter -rq ReplyToQ. The reply-to queue must not resolve to a temporary dynamic queue.

If we do not specify this parameter, the generated trace-route message is not persistent.

-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 we 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.

If we do not specify this parameter, the priority value is taken from the queue specified by -q TargetQName.

-qm TargetQMgrName

Qualifies the target queue name; normal queue manager name resolution applies. The target queue is specified with -q TargetQName.

If we do not specify this parameter, the queue manager to which the IBM MQ display route application is connected is used as the reply-to queue manager.

-ro none|ReportOption

Value	Description
none	Specifies no report options are set.
ReportOption	Specifies report options for the trace-route message. Multiple report options can be specified using a comma as a separator. Possible values for ReportOption are: 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.

If -ro ReportOption or -ro none are not specified, then the MQRO_ACTIVITY and MQRO_DISCARD_MSG report options are specified.

-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, for the IBM MQ display route application, 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 we do not specify this parameter, the queue manager to which the IBM MQ display route application 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 we 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. The possible values for Detail are:

Value	Description
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.

If we do not specify this parameter, medium level activities are recorded.

-ts TopicString

Specifies a topic string to which the IBM MQ display route application is to publish a trace-route message, and puts this application into topic mode. In this mode, the application traces all of the messages that result from the publish request.

-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. Possible values for PassExpiry are:

Value	Description
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. This parameter is the default value.
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.

If we do not specify this parameter, the MQRO_PASS_DISCARD_AND_EXPIRY report option is not specified in the trace-route message.

-xs Expiry

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

If we do not specify this parameter, the expiry time is specified as 60 seconds.

-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 from ( -ro ReportOption), then a specific (non-model) reply-to queue must be specified using -rq ReplyToQ. By default, activity report messages are requested.

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 IBM MQ display route application to display the activity information for the trace-route message at a later time. This can be done using the -i CorrelId parameter.

If we do not specify this parameter, activity information returned for the trace-route message is displayed in the form specified by the -v parameter.

Display options

The following parameters are used when the IBM MQ display route application is used to display collected activity information.

-b

Specifies that the IBM MQ display route application 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 we do not specify this parameter, the IBM MQ display route application gets activity reports and deletes them, or a trace-route reply message related to a message.

-v summary | all | none | outline DisplayOption

Value	Description
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. Multiple display options can be specified using a comma as a separator. If no values are supplied the subsequent information is displayed: The application name The type of each operation Any operation-specific parameters Possible values for DisplayOption are: 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 overrides msgdelta. message All non-PCF group parameters in Message PCF groups are displayed. When this value is specified, we 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, we 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 we do not specify this parameter, a summary of the message route is displayed.

-w WaitTime

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

If we do not specify this parameter, the wait time is specified as the expiry time of the trace-route message, plus 60 seconds.

-u UserId

The ID of the user authorized to determine the route that a message has taken through a queue manager network.

Return codes

Examples

1. 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 IBM MQ display route application orders and displays the activity information.

2. 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 IBM MQ display route application orders and displays the activity information that was accumulated in the trace-route message.

For more examples of using the IBM MQ display route application and its output, see IBM MQ display route application examples.