The TraceRoute PCF group

Attributes in the TraceRoute PCF group control the behavior of a trace-route message. The TraceRoute PCF group is in the message data of every trace-route message.

Detail

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

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.
• 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 with applications that were not enabled for trace-route messaging. This value is incremented by the queue manager. If this value is greater than 0, 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, 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 any of the following values:

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 an IBM MQ Version 6 (or later) queue manager.
• The trace-route message is put to a local queue (target queue or dead-letter queue) by an IBM MQ Version 6 (or later) 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, the algorithm continues to step 4.
   • If the remote queue manager is not capable of supporting trace-route messaging, 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, the trace-route message is rejected with feedback MQFB_UNSUPPORTED_DELIVERY.
   • If no unrecognized delivery options are found, 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, the trace-route message is forwarded to the remote queue manager.
   • If Deliver is specified as MQROUTE_DELIVER_NO, 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, the trace-route message is rejected with feedback MQFB_UNSUPPORTED_FORWARDING.
   • If no unrecognized forwarding options are found, 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, the trace-route message is rejected with feedback MQFB_NOT_FORWARDED.
   • If Forward is specified as MQROUTE_FORWARD_ALL, 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 any of the following values:

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.

Parent topic: Generating and configuring a trace-route message