Display MQ Route Information (DSPMQMRTE)

    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

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.


Examples

None


Error messages

Unknown