DSPMQMRTE (Display MQ Route Information)

Where allowed to run: All environments (*ALL)
Threadsafe: Yes

The DSPMQMRTE command generates a trace route message based on user specified parameters and puts it to a specified queue. One or more reports about the route the message takes to its final destination might be generated, as well as a reply. These will be got from a specified reply queue and the information contained within them will be written to the job's spooled output when it is received.

Parameters

Table 1. Command parameters
Keyword	Description	Choices	Notes
QNAME	Target object	Character value	Required, Positional 1
MQMNAME	Message Queue Manager name	`Character value`, *DFT	Optional, Positional 2
CRRLID	Correlation Identifier	`Character value`, *NONE	Optional, Positional 3
MSGPST	Message Persistence	YES, NO, *QUEUE	Optional, Positional 4
MSGPRTY	Message Priority	0-9, *QUEUE	Optional, Positional 5
OPTION	Report Option	Single values: DFT, NONE Other values (up to 6 repetitions): ACTIVITY, COA, COD, DISCARD, EXCEPTION, EXPIRATION	Optional, Positional 6
RPLYQ	Reply Queue	`Character value`, *DFT	Optional, Positional 7
RPLYMQM	Reply Queue Manager	`Character value`, *DFT	Optional, Positional 8
EXPIRY	Message Expiry	0-999999999, *DFT	Optional, Positional 9
EXPRPT	Pass Expiry	YES, NO	Optional, Positional 10
RTEINF	Route Accumulation	YES, NO	Optional, Positional 11
RPLYMSG	Reply Message	YES, NO	Optional, Positional 12
DLVRMSG	Deliver Message	YES, NO	Optional, Positional 13
FWDMSG	Forward Message	SUPPORT, ALL	Optional, Positional 14
MAXACTS	Maximum Activities	1-999999999, *NOMAX	Optional, Positional 15
DETAIL	Route Detail	LOW, MEDIUM, *HIGH	Optional, Positional 16
BROWSE	Browse Only	YES, NO	Optional, Positional 17
DSPMSG	Display Message	YES, NO	Optional, Positional 18
TGTMQM	Target Queue Manager	`Character value`, *DFT	Optional, Positional 19
DSPINF	Display Information	Single values: ALL, SUMMARY, NONE Other values (up to 6 repetitions): ACTGRP, ID, MSGGRP, MSGDELTA, OPGRP, *TRGRP	Optional, Positional 20
WAIT	Wait Time	0-999999999, *DFT	Optional, Positional 21
BIND	Bind Option	OPEN, NOTFIXED	Optional, Positional 22

Target object (QNAME)

Specifies the name of the target queue of the trace route message or, if displaying previously gathered information, the name of the queue storing the information.

Message Queue Manager name (MQMNAME)

Specifies the name of the message queue manager.

The possible values are:

*DFT: Use the default queue manager.
message-queue-manager-name: Specify the name of the queue manager.

Correlation Identifier (CRRLID)

Specifies the CorrelId to use when retrieving previously gathered information. The format of the 24 byte CorrelId is a 48 character hexadecimal string. You must supply a CorrelId if you are retrieving previously gathered information, rather than generating a trace route message.

The possible values are:

*NONE: No CorrelId is supplied.
correlation-identifier: The 48 character hexadecimal string representing the 24 byte CorrelId.

Message Persistence (MSGPST)

Specifies the persistence of the trace route message.

The possible values are:

*NO: The message will be put with MQPER_NOT_PERSISTENT.
*YES: The message will be put with MQPER_PERSISTENT.
*QUEUE: The message will be put with MQPER_PERSISTENCE_AS_Q_DEF.

Message Priority (MSGPRTY)

Specifies the priority of the trace route message.

The possible values are:

*QUEUE: The message will be put with MQPRI_PRIORITY_AS_Q_DEF.
message-priority: The priority of the message ranging 0 through 9.

Report Option (OPTION)

Specifies the report options of the trace route message. Reports generated on a non trace route enabled queue manager can potentially remain in the network undelivered, which is why most report options are disabled by default. By requesting full data to be returned, it allows the trace route information contained in the message to be returned in the result of a problem.

The possible values are:

*DFT: Turns on MQRO_ACTIVITY and MQRO_DISCARD_MSG.
*NONE: No report options are set.
*ACTIVITY: Turns on MQRO_ACTIVITY.
*COA: Turns on MQRO_COA_WITH_FULL_DATA.
*COD: Turns on MQRO_COD_WITH_FULL_DATA.
*DISCARD: Turns on MQRO_DISCARD_MSG.
*EXCEPTION: Turns on MQRO_EXCEPTION_WITH_FULL_DATA.
*EXPIRATION: Turns on MQRO_EXPIRATION_WITH_FULL_DATA.

Reply Queue (RPLYQ)

Specifies the name of the reply queue to which the reply and all report messages should be sent. This must exist on the local queue manager unless the RPLYMQM parameter is also specified. The reply queue should not be a temporary queue if the trace route message is to be persistent.

The possible values are:

*DFT: The SYSTEM.DEFAULT.MODEL.QUEUE is used and the reply queue is by default a temporary dynamic queue.
reply-queue: The name of the reply queue to use.

Reply Queue Manager (RPLYMQM)

Specifies the queue manager to which replies are sent.

The possible values are:

*DFT: Replies are sent to the local queue manager.
reply-queue-manager: The name of the reply to queue manager.

Message Expiry (EXPIRY)

Specifies the Expiry time, in seconds, of the trace route message.

The possible values are:

*DFT: The default expiry time of 60 seconds is used.
expiry-time: The expiry time of the message ranging from 0 through 999999999.

Pass Expiry (EXPRPT)

Specifies whether the expiry of the trace route message is passed to reports or the reply message. This effectively turns MQRO_PASS_DISCARD_AND_EXPIRY on and off. This allows users to keep the reports indefinitely if required.

The possible values are:

*YES: Expiry is passed to reports or the reply message.
*NO: Expiry is not passed to reports or the reply message.

Route Accumulation (RTEINF)

Specifies that the route information is accumulated within the trace route message as it flows through the queue manager network.

The possible values are:

*NO: No information is accumulated within the trace route message.
*YES: Information is accumulated within the trace route message.

Reply Message (RPLYMSG)

Requests that a reply message containing all accumulated information is returned to the reply to queue when the trace route message reaches its final destination (if this is permitted by the queue manager hosting the final destination queue).

The possible values are:

*NO: No reply message is returned.
*YES: A reply message is returned to the the reply to queue.

Deliver Message (DLVRMSG)

Specifies whether the trace route message is delivered to getting applications if the message successfully arrives at the destination queue.

The possible values are:

*NO: If the trace route message successfullly arrives at the target queue it is not delivered to getting applications.
*YES: The trace route message is delivered to a getting application if the message successfully arrives at the target queue. Specifying this option effectively gives permission for the message to arrive on a queue manager, whether it supports trace route or not.

Forward Message (FWDMSG)

Specifies whether the trace route message is forwarded to the next queue manager in the route.

The possible values are:

*SUPPORT: The trace route message is forwarded only to queue managers that can ensure that the delivery option is honoured.
*ALL: The trace route message is forwarded on without any regard given to the next queue manager in the route. This option can be used to force a non-trace route enabled queue manager to accept trace route messages, even when they cannot process them in line with the delivery option.

Maximum Activities (MAXACTS)

Specifies the maximum number of activities that can take place on the trace route message before it is discarded.

The possible values are:

*NOMAX: No maximum number of activities are specified.
maximum-activities: The maximum numer of activities ranging from 1 through 999999999.

Route Detail (DETAIL)

Specifies how much detail about the route is requested.

The possible values are:

*LOW: At this level of detail no information about queue manager activities is requested. This gives a very high level view of what user activity has taken place on the message.
*MEDIUM: Low detail information, as well as information on the movements of the message within the queue manager is requested. This includes the work of the MCA.
*HIGH: Low and medium detail, as well as more detailed information about the route the message took is requested. For example, in clustering this might include detail about why the route was chosen.

Browse Only (BROWSE)

Specifies whether messages returned are browsed only. This means that the information remains on the queue for future display operations.

The possible values are:

*NO: Messages returned are not browse only.
*YES: Messages returned are browse only.

Display Message (DSPMSG)

Specifies whether when a trace route message is generated the information returned is displayed.

The possible values are:

*YES: The returned information is displayed.
*NO: The returned information is not displayed. This allows DSPMQMRTE to exit as soon as the trace route message has been put to the target queue. On exit, a 48 character hexadecimal string is output, which is the MsgId on the trace route message that was generated and can be used as the CRRLID supplied to a subsequent DSPMQMRTE call.

Target Queue Manager (TGTMQM)

Specifies the target queue manager for the trace route message.

The possible values are:

*DFT: No target queue manager is specified. Either the destination queue is a local queue, or there is a local definition of the queue.
target-queue-manager: The target queue manager for the trace route message.

Display Information (DSPINF)

Specifies how much of the information gathered should be displayed.

The possible values are:

*ALL: All available information is displayed.
*SUMMARY: Displays only the queues which the message was routed through.
*NONE: None of the available information will be displayed.
*ACTGRP: All non-group parameters in the Activity groups will be displayed.
*ID: Values with parameters identifiers MQBACF_MSG_ID or MQBACF_CORREL_ID are always displayed. This overrides *MSGDELTA which normally prevents certain values in the Message groups from being displayed.
*MSGGRP: All non-group parameters in the Message groups are displayed.
*MSGDELTA: Like *MSGGRP, except that information in the Message groups is only displayed where it has changed since the last operation took place.
*OPGRP: All non-group parameters in the Operation groups are displayed.
*TRGRP: All parameters in the TraceRoute groups are displayed.

Wait Time (WAIT)

Specifies how long, in seconds, that DSPMQMRTE should wait before assuming that all a reply message or all the reports (depending on the options specified) that were generated en route that can be delivered to the reply queue have now done so.

The possible values are:

*DFT: DSPMQMRTE waits for 60 seconds longer than the Expiry time of the trace route message.
wait-time: The time that DSPMQMRTE should wait.

Bind Option (BIND)

Specifies whether the target queue is bound to a specific destination.

The possible values are:

*OPEN: The target queue is bound to a specific destination. The queue is opened with option MQOO_BIND_ON_OPEN.
*NOTFIXED: 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 queue is opened with option MQOO_BIND_NOT_FIXED.