Manual generation

A trace-route message consists of the following:

The message descriptor

An MQMD structure, with the Format field set to MQFMT_ADMIN or MQFMT_EMBEDDED_PCF.

Message data

Consists of either:

  • A PCF header (MQCFH) and trace-route message data, if Format is set to MQFMT_ADMIN, or

  • An embedded PCF header (MQEPH), trace-route message data, and additional user-specified message data, if Format is set to MQFMT_EMBEDDED_PCF.

The trace-route message data consists of the TraceRoute PCF group and one or more Activity PCF groups. When generating a trace-route message manually, an Activity PCF group is not required. Activity PCF groups are written to the message data of the trace-route message when an MCA or user-written application performs an activity on its behalf. The TraceRoute group is detailed in The TraceRoute PCF group.

For information on the parameters contained in the message descriptor and message data of a trace-route message, see Trace-route message reference.

 

The TraceRoute PCF group

The behavior of a trace-route message is controlled by attributes in the TraceRoute PCF group. The TraceRoute group is a PCF group that resides in the message data of every trace-route message. The following table details the parameters in the TraceRoute group, that an MCA will recognize. Further parameters can be added if user-written applications are written to recognize them, see Recording additional information.

Table 16. TraceRoute PCF group
parameter
Type
TraceRoute
   Detail
   RecordedActivities
   UnrecordedActivities
   DiscontinuityCount
   MaxActivities
   Accumulate
   Forward
   Deliver
MQCFGR
MQCFIN
MQCFIN
MQCFIN
MQCFIN
MQCFIN
MQCFIN
MQCFIN
MQCFIN

Descriptions of each parameter in the TraceRoute PCF group follows:

Detail

Specifies the detail level of activity information that is to be recorded. The value can be:

MQROUTE_DETAIL_LOW

Only activities performed by user application are recorded.

MQROUTE_DETAIL_MEDIUM

Activities specified in MQROUTE_DETAIL_LOW should be recorded. Additionally, activities performed by MCAs are recorded.

MQROUTE_DETAIL_HIGH

Activities specified in MQROUTE_DETAIL_LOW, and MQROUTE_DETAIL_MEDIUM should be recorded. MCAs do not record any further activity information at this level of detail. This option is only available to user applications that are to record further activity information. For example, if a user application determines the route a message takes by considering certain message characteristics, the information about the routing logic could be included with this level of detail.

RecordedActivities

Specifies the number of recorded activities performed on behalf of the trace-route message. An activity is considered to be recorded if information about it has been written to the trace-route message, or if an activity report has been generated. For every recorded activity, RecordedActivities increments by one.

UnrecordedActivities

Specifies the number of unrecorded activities performed on behalf of the trace-route message. An activity is considered to be unrecorded if an application that is enabled for trace-route messaging neither accumulates, nor writes the related activity information to an activity report.

An activity performed on behalf of a trace-route message is unrecorded in the following circumstances:

  • The detail level of the performed activity is less than the level of detail specified by the parameter Detail. For more information, see Detail.

  • The trace-route message requests an activity report but not accumulation, and the queue manager is not enabled for activity recording.

  • The trace-route message requests accumulation but not an activity report, and the queue manager is not enabled for trace-route messaging.

  • The trace-route message requests both accumulation and an activity report, and the queue manager is not enabled for activity recording and trace route messaging.

  • The trace-route message requests neither accumulation nor an activity report.

For every unrecorded activity the parameter, UnrecordedActivities, increments by one.

DiscontinuityCount

Specifies the number of times the trace-route message has been routed through a queue manager whose applications were not enabled for trace-route messaging. This value is incremented by the queue manager. If this value is greater than 0, then only a partial message route can be determined.

MaxActivities

Specifies the maximum number of activities that can be performed on behalf of the trace-route message.

The total number of activities is the sum of RecordedActivities, UnrecordedActivities, and DiscontinuityCount. The total number of activities must not exceed the value of MaxActivities.

The value of MaxActivities can be:

A positive integer

The maximum number of activities.

If the maximum number of activities is exceeded, then the trace-route message is rejected with feedback MQFB_MAX_ACTIVITIES. This can prevent the trace-route message from being forwarded indefinitely if caught in an infinite loop.

MQROUTE_UNLIMITED_ACTIVITIES

An unlimited number of activities can be performed on behalf of the trace-route message.

Accumulate

Specifies the method used to accumulate activity information. The value can be:

MQROUTE_ACCUMULATE_IN_MSG

If the queue manager is enabled for trace-route messaging, activity information is accumulated in the message data of the trace-route message.

If this value is specified, the trace-route message data consists of the following:

  • The TraceRoute PCF group.

  • Zero or more Activity PCF groups.

MQROUTE_ACCUMULATE_AND_REPLY

If the queue manager is enabled for trace-route messaging, activity information is accumulated in the message data of the trace-route message, and a trace-route reply message is generated if any of the following occur:

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

If this value is specified, the trace-route message data consists of the following:

  • The TraceRoute PCF group.

  • Zero or more Activity PCF groups.

MQROUTE_ACCUMULATE_NONE

Activity information is not accumulated in the message data of the trace-route message.

If this value is specified, the trace-route message data consists of the following:

  • The TraceRoute PCF group.

Forward

Specifies where a trace-route message can be forwarded to. The value can be:

MQROUTE_FORWARD_IF_SUPPORTED

The trace-route message is only forwarded to queue managers that will honor the value of the Deliver parameter from the TraceRoute group.

MQROUTE_FORWARD_ALL

The trace-route message is forwarded to any queue manager, regardless of whether the value of the Deliver parameter will be honored.
Queue managers use the following algorithm when determining whether to forward a trace-route message to a remote queue manager:

  1. Determine whether the remote queue manager is capable of supporting trace-route messaging.

    • If the remote queue manager is capable of supporting trace-route messaging, then the algorithm continues to step 4.

    • If the remote queue manager is not capable of supporting trace-route messaging, then the algorithm continues to step 2

  2. Determine whether the Deliver parameter from the TraceRoute group contains any unrecognized delivery options in the MQROUTE_DELIVER_REJ_UNSUP_MASK bit mask.

    • If any unrecognized delivery options are found, then the trace-route message is rejected with feedback MQFB_UNSUPPORTED_DELIVERY.

    • If no unrecognized delivery options are found, then the algorithm continues to step 3.

  3. Determine the value of the parameter Deliver from the TraceRoute PCF group in the trace-route message.

    • If Deliver is specified as MQROUTE_DELIVER_YES, then the trace-route message is forwarded to the remote queue manager.

    • If Deliver is specified as MQROUTE_DELIVER_NO, then the algorithm continues to step 4.

  4. Determine whether the Forward parameter from the TraceRoute group contains any unrecognized forwarding options in the MQROUTE_FORWARDING_REJ_UNSUP_MASK bit mask.

    • If any unrecognized forwarding options are found, then the trace-route message is rejected with feedback MQFB_UNSUPPORTED_FORWARDING.

    • If no unrecognized forwarding options are found, then the algorithm continues to step 5.

  5. Determine the value of the parameter Forward from the TraceRoute PCF group in the trace-route message.

    • If Forward is specified as MQROUTE_FORWARD_IF_SUPPORTED, then the trace-route message is rejected with feedback MQFB_NOT_FORWARDED.

    • If Forward is specified as MQROUTE_FORWARD_ALL, then trace-route message can be forwarded to the remote queue manager.

Deliver

Specifies the action to be taken if the trace-route message reaches its intended destination. User-written applications must check this attribute before placing a trace-route message on its target queue. The value can be:

MQROUTE_DELIVER_YES

On arrival, the trace-route message is put on the target queue. Any application performing a get operation on the target queue can retrieve the trace-route message.

MQROUTE_DELIVER_NO

On arrival, the trace-route message is not delivered to the target queue. The message is processed according to its report options.