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 Version 6 queue manager.
- The trace-route message is put to a local queue (target queue or dead-letter
queue) by a WebSphere MQ Version 6 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:
-
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
-
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.
-
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.
-
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.
-
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.