Home

 

dspmqrte (WebSphere MQ display route application)

 

 

Purpose

The WebSphere MQ display route application (dspmqrte) can be executed on all WebSphere MQ V6.0 queue managers, with the exception of WebSphere MQ for z/OS queue managers. We can execute the WebSphere MQ display route application as a client to a WebSphere MQ for z/OS Version 6.0 queue manager by specifying the -c parameter when issuing the dspmqrte command.

To run a client application against a WebSphere MQ for z/OS queue manager, the client attachment feature must be installed.

Use dspmqrte to help determine the route a message has taken through a queue manager network. The WebSphere 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 it's target queue the activity information is collected by the WebSphere MQ display route application and displayed. For more information, and examples of using the WebSphere MQ display route application, see the WebSphere MQ Monitoring book.

 

Syntax







>>-dspmqrte--+------+------------------------------------------->
             '- -c -'   

   .-| Generation options |--------------.                      
>--+-------------------------------------+-- -q --TargetQName--->
   '- -i --CorrelId--| Display options |-'                      

>--+----------------+------------------------------------------><
   '- -m --QMgrName-'   

Generation options

|--+------------------+--+---------------+--+---------------+--->
   '- -ac --+-------+-'  '- -d --Deliver-'  '- -f --Forward-'   
            '- -ar -'                                           

>--+-----------------------+--+------+--+----------------+------>
   |                   (1) |  '- -o -'  '- -p --Priority-'   
   '- -l --Persistence-----'                                 

>--+-----------------------+--+-----------------------------+--->
   '- -qm --TargetQMgrName-'  '- -ro --+- none -----------+-'   
                                       | .-,------------. |     
                                       | V              | |     
                                       '---ReportOption-+-'     

>--+------------------------------------------+----------------->
   '- -rq --ReplyToQ--+---------------------+-'   
                      '- -rqm --ReplyToQMgr-'     

>--+------------------+--+--------------+----------------------->
   '- -s --Activities-'  '- -t --Detail-'   

>--+-------------------+--+---------------+--------------------->
   '- -xp --PassExpiry-'  '- -xs --Expiry-'   

   .-| Display options |-.   
>--+---------------------+--------------------------------------|
   |        (2)          |   
   '--- -n --------------'   

Display options

             .- -v  summary --------------------------------.   
|--+------+--+----------------------------------------------+--->
   '- -b -'  '- -v --+- all ------------------------------+-'   
                     +- none -----------------------------+     
                     '- outline --+---------------------+-'     
                                  | .-,---------------. |       
                                  | V                 | |       
                                  '--- 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 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.

If the WebSphere 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 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.

-i CorrelId

This parameter is used when the WebSphere 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 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.

Generation Options

The following parameters are used when the WebSphere 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 a WebSphere MQ V6 queue manager.

  • The trace-route message is put to a local queue (target queue or dead-letter queue) by a WebSphere MQ V6 queue manager.

  • The number of activities performed on the trace-route message exceeds the value of specified in -s Activities.

For more information on trace-route reply messages, see the WebSphere MQ Monitoring book.

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

-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 WebSphere MQ Monitoring. 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.

-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 it's 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.

-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 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 reply-to queue manager.

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

-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 WebSphere MQ display route application, to be created.

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

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

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

-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:

  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 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 WebSphere MQ display route application to display the activity information for the trace-route message at a later time, 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 WebSphere MQ display route application is used to display collected activity information.

-b

Specifies that the WebSphere MQ display route application will only browse activity reports or a trace-route reply message related to a message. This allows activity information to be displayed again at a later time.

If you do not specify this parameter, the WebSphere MQ display route application will destructively get activity reports or a trace-route reply message related to a message.

-v summary | all | none | outline DisplayOption

  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 following 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 you do not specify this parameter, a summary of the message route is displayed.

-w WaitTime

Specifies the time, in seconds, that the WebSphere MQ display route application will wait 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.

 

Return codes

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 WebSphere 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 is delivered to the reply-to queue TRR.REPLY.TO.Q, the WebSphere MQ display route application orders and displays the activity information that was accumulated in the trace-route message.

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

 

Parent topic:

The control commands


fa15730_


 

Home