Generating trace-route messages
The WebSphere MQ display route application, dspmqrte, provides many parameters that determine characteristics of the trace-route message itself, and how the trace-route message should be treated as it is routed through a queue manager network. This section gives an overview of the parameters available with the WebSphere MQ display route application that are related to the generation, configuration, and use of trace-route messages.
Connecting to a queue manager
The queue manager that the WebSphere MQ display route application connects to is specified using the following parameters:
- -c
- Specifies that the WebSphere MQ display route application connects as a client application. For more information on how to set up client machines, see the WebSphere MQ Clients book.
If you do not specify this parameter, the WebSphere MQ display route application does not connect as a client application.
- -m QMgrName
- The name of the queue manager to which the WebSphere 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.
The target queue
The target destination of a trace-route message is specified using the following parameters:
- -q TargetQName
- If the WebSphere 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.
- -qm TargetQMgr
- Qualifies the target queue name; normal queue manager name resolution will then apply. The target queue is specified with
-q TargetQName.
If you do not specify this parameter, the queue manager to which the WebSphere MQ display route application is connected is used as the target queue manager.
- -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.
Mimicking a message
One use of trace-route messaging is to help determine the last known location of a message that did not reach its intended destination. The WebSphere MQ display route application provides parameters that can help configure a trace-route message to mimic the original message. For information on the importance of mimicking the original message, see Mimicking a message. When mimicking a message, we can use the following parameters:
- -l Persistence
- Specifies the persistence of the generated trace-route message. Possible values for Persistence are:
A trace-route reply message, or any report messages, returned will share the same persistence value as the original trace-route message.
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). If Persistence is specified as yes, 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.
- -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.
- -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.
- -ro
none | ReportOption
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 neither
-ro ReportOption nor
-ro none are specified, then the MQRO_ACTIVITY and MQRO_DISCARD_MSG report options are specified.
The WebSphere MQ display route application does not allow you to add user data to the trace-route message. If you require user data to be added to the trace-route message then manually generate a trace-route message, see Configuring and generating a trace-route message.
Accumulating activity information
The route a trace-route message has taken is determined using recorded activity information. Recorded activity information can be returned using the following:
- Activity reports.
- A trace-route reply message.
- The trace-route message itself (having been put on the target queue).
For more information, see How recorded activity information is acquired.
When using dspmqrte, the method used to return recorded activity information is determined using the following parameters:
- The
activity report option, specified using -ro
- Specifies that activity information is returned using activity reports. By default activity recording is enabled.
- -ac -ar
- Specifies that activity information is accumulated in the trace-route message, and that a trace-route reply message is to be generated.
- -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 a WebSphere MQ V6.0 queue manager.
- The trace-route message is put to a local queue (target queue or dead-letter queue) by a WebSphere MQ V6.0 queue manager.
- The number of activities performed on the trace-route message exceeds the value of specified in -s Activities.
- -ac -d yes
- Specifies that activity information is accumulated in the trace-route message, and that on arrival, the trace-route message will be put on the target queue.
- -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.
- -d yes
- On arrival, the trace-route message is put to the target queue, even if the queue manager does not support trace-route messaging.
If you do not specify this parameter, the trace-route message is not put to the target queue.
The trace-route message can then be retrieved from the target queue, and the recorded activity information acquired.
We can combine these methods as required.
Additionally, the detail level of the recorded activity information can be specified using the following parameter:
- -t Detail
- Specifies the activities that are recorded. The possible values for Detail are:
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 could be included with this level of detail. If you do not specify this parameter, medium level activities are recorded.
By default the WebSphere MQ display route application uses a temporary dynamic queue to store the returned messages. When the WebSphere MQ display route application ends, the temporary dynamic queue is closed, and any messages are purged. If the returned messages are required beyond the current execution of the WebSphere MQ display route application ends, then a permanent queue must be specified using the following parameters:
- -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 then a dynamic reply-to queue is created using the system default model queue, SYSTEM.DEFAULT.MODEL.QUEUE.
- -rqm ReplyToQMgr
- Specifies the name of the queue manager where the reply-to queue resides. The name can contain up to 48 characters.
If you do not specify this parameter, the queue manager to which the WebSphere MQ display route application is connected is used as the reply-to queue manager.
How the trace-route message is handled
There are various parameters that are used to control how a trace-route message is handled as it is routed through a queue manager network. The following parameters can restrict where the trace-route message can be routed in the queue manager network:
- -d Deliver
- Specifies whether the trace-route message is to be delivered to the target queue on arrival. Possible values for Deliver are:
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 TraceRoute PCF group. The possible values for Forward are:
If you do not specify this parameter, the trace-route message will only be forwarded to a queue manager that will honor the Deliver parameter.
The following parameters can prevent a trace-route message from remaining in a queue manager network indefinitely:
- -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 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.
- -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.
- -xp PassExpiry
- Specifies whether the expiry time from the trace-route message is passed on to a trace-route reply message. Possible values for PassExpiry are:
If you do not specify this parameter, MQRO_PASS_DISCARD_AND_EXPIRY is not specified.
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 report option (if specified), and the remaining expiry time are passed on.
This 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 expiry time from the trace-route message are not passed on.
- The
discard report option, specified using -ro
- Specifies the MQRO_DISCARD_MSG report option. This can prevent the trace-route message remaining in the queue manager network indefinitely.