Generating trace-route messages

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:

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 will share the same persistence value as the original trace-route message.
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:

all The trace-route message is forwarded to any queue manager.
Warning:
If forwarded to a WebSphere MQ queue manager prior to V6.0, the trace-route message will not be 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 will honor the Deliver parameter from the TraceRoute PCF group.

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:

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.

If you do not specify this parameter, MQRO_PASS_DISCARD_AND_EXPIRY is not specified.

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.

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

	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.

	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.

	all	The trace-route message is forwarded to any queue manager. Warning: If forwarded to a WebSphere MQ queue manager prior to V6.0, the trace-route message will not be 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 will honor the Deliver parameter from the TraceRoute PCF group.