dspmqrte (display route information)

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

Purpose

[z/OS]The IBM® MQ display route application (dspmqrte) command can be run on all platforms except z/OS®. You 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

Read syntax diagramSkip visual syntax diagram dspmqrte  -c Generation options -i CorrelIdDisplay options  -q TargetQName  -m QMgrName -u UserId
Generation options
Read syntax diagramSkip visual syntax diagram -ac  -ar  -d Deliver -f Forward -l Persistence1 -o  -p Priority -qm TargetQMgrName -ro  none ,ReportOption -rq ReplyToQ -rqm ReplyToQMgr -s Activities -t Detail -ts TopicString -xp PassExpiry -xs ExpiryDisplay options -n 2
Display options
Read syntax diagramSkip visual syntax diagram -b  -v summary  -v  all  none  outline , DisplayOption  -w WaitTime
Notes:
  • 1 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 you must specify the parameter -rq ReplyToQ. The reply-to queue must not resolve to a temporary dynamic queue.
  • 2 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:

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 you 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 you 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 an IBM WebSphere® MQ 7.0 queue manager.
  • The trace-route message is put to a local queue (target queue or dead-letter queue) by an IBM WebSphere MQ 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 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. Possible values for Deliver are:
Table 1. Delivery parameter values.
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 you 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:
Table 2. Forward parameter values.
Value Description
all The trace-route message is forwarded to any queue manager.
Warning: If forwarded to a pre-IBM WebSphere MQ 6.0 queue manager, 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 you 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:
Table 3. Persistence parameter values.
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, you must specify the parameter -rq ReplyToQ. The reply-to queue must not resolve to a temporary dynamic queue.

If you 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 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.

If you 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 you 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
Table 4. ReportOption parameter values.
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 you 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 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. The possible values for Detail are:
Table 5. Detail parameter values.
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 you 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:
Table 6. PassExpiry parameter values.
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 you 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 you 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 you 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 you 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
Table 7. DisplayOption parameter values.
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, 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 you 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 you 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

Table 8. Return code identifiers and descriptions
Return code Description
0 Command completed normally
10 Invalid arguments supplied
20 An error occurred during processing

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.