Report (MQLONG)
A report message is a message about another message, used to inform
an application about expected or unexpected events that relate to the original
message. The Report field enables the application sending
the original message to specify which report messages are required, whether
the application message data is to be included in them, and also (for both
reports and replies) how the message and correlation identifiers in the report
or reply message are to be set. Any or all (or none) of the following types
of report message can be requested:
- Exception
- Expiration
- Confirm on arrival (COA)
- Confirm on delivery (COD)
- Positive action notification (PAN)
- Negative action notification (NAN)
If more than one type of report message is required, or other report
options are needed, the values can be:
- Added together (do not add the same constant more than once), or
- Combined using the bitwise OR operation (if the programming language supports
bit operations).
The application that receives the report message can determine the reason
that the report was generated by examining the Feedback field
in the MQMD; see the Feedback field for more details.
Exception options: Specify one of the options listed
below to request an exception report message.
- MQRO_EXCEPTION
- A message channel agent generates this type of report when a message
is sent to another queue manager and the message cannot be delivered to the
specified destination queue. For example, the destination queue or an intermediate
transmission queue might be full, or the message might be too big for the
queue.
Generation of the exception report message depends on the persistence
of the original message, and the speed of the message channel (normal or fast)
through which the original message travels:
An exception report is not generated if the application that
put the original message can be notified synchronously of the problem by means
of the reason code returned by the MQPUT or MQPUT1 call.
Applications can also send exception reports, to
indicate that a message cannot be processed (for example, because it is a
debit transaction that would cause the account to exceed its credit limit).
Message data from the original message is not included with the report
message.
Do not specify more than one of MQRO_EXCEPTION, MQRO_EXCEPTION_WITH_DATA,
and MQRO_EXCEPTION_WITH_FULL_DATA.
- MQRO_EXCEPTION_WITH_DATA
- This is the same as MQRO_EXCEPTION, except that the first 100 bytes
of the application message data from the original message are included in
the report message. If the original message contains one or more MQ header
structures, they are included in the report message, in addition to the 100
bytes of application data.
Do not specify more than one of MQRO_EXCEPTION,
MQRO_EXCEPTION_WITH_DATA, and MQRO_EXCEPTION_WITH_FULL_DATA.
- MQRO_EXCEPTION_WITH_FULL_DATA
- Exception reports with full data required.
This is the same as MQRO_EXCEPTION,
except that all the application message data from the original message is
included in the report message.
Do not specify more than one of MQRO_EXCEPTION,
MQRO_EXCEPTION_WITH_DATA, and MQRO_EXCEPTION_WITH_FULL_DATA.
Expiration options: Specify one of the options listed
below to request an expiration report message.
- MQRO_EXPIRATION
- This type of report is generated by the queue manager if the message
is discarded before delivery to an application because its expiry time has
passed (see the Expiry field). If this option is not set,
no report message is generated if a message is discarded for this reason (even
if you specify one of the MQRO_EXCEPTION_* options).
Message data
from the original message is not included with the report message.
Do not specify more than one of MQRO_EXPIRATION, MQRO_EXPIRATION_WITH_DATA,
and MQRO_EXPIRATION_WITH_FULL_DATA.
- MQRO_EXPIRATION_WITH_DATA
- This is the same as MQRO_EXPIRATION, except that the first 100 bytes
of the application message data from the original message are included in
the report message. If the original message contains one or more MQ header
structures, they are included in the report message, in addition to the 100
bytes of application data.
Do not specify more than one of MQRO_EXPIRATION,
MQRO_EXPIRATION_WITH_DATA, and MQRO_EXPIRATION_WITH_FULL_DATA.
- MQRO_EXPIRATION_WITH_FULL_DATA
- This is the same as MQRO_EXPIRATION, except that all the application
message data from the original message is included in the report message.
Do not specify more than one of MQRO_EXPIRATION, MQRO_EXPIRATION_WITH_DATA,
and MQRO_EXPIRATION_WITH_FULL_DATA.
Confirm-on-arrival options: Specify one of the options
listed below to request a confirm-on-arrival report message.
- MQRO_COA
- This type of report is generated by the queue manager that owns the
destination queue when the message is placed on the destination queue. Message
data from the original message is not included with the report message.
If the message is put as part of a unit of work, and the destination queue
is a local queue, the COA report message generated by the queue manager can
be retrieved only if the unit of work is committed.
A COA report is
not generated if the Format field in the message descriptor
is MQFMT_XMIT_Q_HEADER or MQFMT_DEAD_LETTER_HEADER. This prevents a COA report
being generated if the message is put on a transmission queue, or is undeliverable
and put on a dead-letter queue.
Do not specify more than one of MQRO_COA,
MQRO_COA_WITH_DATA, and MQRO_COA_WITH_FULL_DATA.
- MQRO_COA_WITH_DATA
- This is the same as MQRO_COA, except that the first 100 bytes of the
application message data from the original message are included in the report
message. If the original message contains one or more MQ header structures,
they are included in the report message, in addition to the 100 bytes of application
data.
Do not specify more than one of MQRO_COA, MQRO_COA_WITH_DATA, and
MQRO_COA_WITH_FULL_DATA.
- MQRO_COA_WITH_FULL_DATA
- This is the same as MQRO_COA, except that all the application message
data from the original message is included in the report message.
Do not
specify more than one of MQRO_COA, MQRO_COA_WITH_DATA, and MQRO_COA_WITH_FULL_DATA.
Confirm-on-delivery options: Specify one of the options
listed below to request a confirm-on-delivery report message.
- MQRO_COD
- This type of report is generated by the queue manager when an application
retrieves the message from the destination queue in a way that deletes the
message from the queue. Message data from the original message is not included
with the report message.
If the message is retrieved as part of a unit
of work, the report message is generated within the same unit of work, so
that the report is not available until the unit of work is committed. If the
unit of work is backed out, the report is not sent.
A COD report is
not always generated if a message is retrieved with the MQGMO_MARK_SKIP_BACKOUT
option. If the primary unit of work is backed out but the secondary unit of
work is committed, the message is removed from the queue, but a COD report
is not generated.
A COD report is not generated if the Format field in the message descriptor is MQFMT_DEAD_LETTER_HEADER. This
prevents a COD report being generated if the message is undeliverable and
put on a dead-letter queue.
MQRO_COD is not valid if the destination
queue is an XCF queue.
Do not specify more than one of MQRO_COD, MQRO_COD_WITH_DATA,
and MQRO_COD_WITH_FULL_DATA.
- MQRO_COD_WITH_DATA
- This is the same as MQRO_COD, except that the first 100 bytes of the
application message data from the original message are included in the report
message. If the original message contains one or more MQ header structures,
they are included in the report message, in addition to the 100 bytes of application
data.
If MQGMO_ACCEPT_TRUNCATED_MSG is specified on the MQGET call for the original message, and the message retrieved is truncated,
the amount of application message data placed in the report message depends
on the environment:
- On z/OS, it is the minimum of:
- The length of the original message
- The length of the buffer used to retrieve the message
- 100 bytes.
- In other environments, it is the minimum of:
- The length of the original message
- 100 bytes.
MQRO_COD_WITH_DATA is not valid if the destination queue is an
XCF queue.
Do not specify more than one of MQRO_COD, MQRO_COD_WITH_DATA,
and MQRO_COD_WITH_FULL_DATA.
- MQRO_COD_WITH_FULL_DATA
- This is the same as MQRO_COD, except that all the application message
data from the original message is included in the report message.
MQRO_COD_WITH_FULL_DATA
is not valid if the destination queue is an XCF queue.
Do not specify
more than one of MQRO_COD, MQRO_COD_WITH_DATA, and MQRO_COD_WITH_FULL_DATA.
Action-notification options: Specify one or both
of the options listed below to request that the receiving application send
a positive-action or negative-action report message.
- MQRO_PAN
- This type of report is generated by the application that retrieves the
message and acts upon it. It indicates that the action requested in the message
has been performed successfully. The application generating the report determines
whether any data is to be included with the report.
Other than conveying
this request to the application retrieving the message, the queue manager
takes no action based on this option. The retrieving application must generate
the report if appropriate.
- MQRO_NAN
- This type of report is generated by the application that retrieves the
message and acts upon it. It indicates that the action requested in the message
has not been performed successfully. The application
generating the report determines whether any data is to be included with the
report. For example, you might want to include some data indicating why the
request could not be performed.
Other than conveying this request to the
application retrieving the message, the queue manager takes no action based
on this option. The retrieving application must generate the report if appropriate.
The application must determine which conditions correspond to a positive
action and which correspond to a negative action. However, if the request
has been only partially performed, generate a NAN report rather than a PAN
report if requested. Every possible condition must correspond to either a
positive action, or a negative action, but not both.
Message-identifier options: Specify one of the options
listed below to control how the MsgId of the report message
(or of the reply message) is to be set.
- MQRO_NEW_MSG_ID
- This is the default action, and indicates that if a report or reply
is generated as a result of this message, a new MsgId is
generated for the report or reply message.
- MQRO_PASS_MSG_ID
- If a report or reply is generated as a result of this message, the MsgId of this message is copied to the MsgId of
the report or reply message.
If this option is not specified, MQRO_NEW_MSG_ID
is assumed.
Correlation-identifier options: Specify one of the
options listed below to control how the CorrelId of the
report message (or of the reply message) is to be set.
- MQRO_COPY_MSG_ID_TO_CORREL_ID
- This is the default action, and indicates that if a report or reply
is generated as a result of this message, the MsgId of
this message is copied to the CorrelId of the report or
reply message.
- MQRO_PASS_CORREL_ID
- If a report or reply is generated as a result of this message, the CorrelId of this message is copied to the CorrelId of
the report or reply message.
If this option is not specified, MQRO_COPY_MSG_ID_TO_CORREL_ID
is assumed.
Servers replying to requests or generating report messages must check whether
the MQRO_PASS_MSG_ID or MQRO_PASS_CORREL_ID options were set in the original
message. If they were, the servers must take the action described for those
options. If neither is set, the servers must take the corresponding default
action.
Disposition options: Specify one of the options listed
below to control the disposition of the original message when it cannot be
delivered to the destination queue. These options apply only to those situations
that would result in an exception report message being generated if one had
been requested by the sending application. The application can set the disposition
options independently of requesting exception reports.
- MQRO_DEAD_LETTER_Q
- This is the default action, and places the message on the dead-letter
queue if the message cannot be delivered to the destination queue. An exception
report message is generated, if one was requested by the sender.
- MQRO_DISCARD_MSG
- This discards the message if it cannot be delivered to the destination
queue. An exception report message is generated, if one was requested by the
sender.
If you want to return the original message to the sender, without
the original message being placed on the dead-letter queue, the sender must
specify MQRO_DISCARD_MSG with MQRO_EXCEPTION_WITH_FULL_DATA.
- MQRO_PASS_DISCARD_AND_EXPIRY
- If this option is set on a message, and a report or reply is generated
because of it, the message descriptor of the report inherits:
- MQRO_DISCARD_MSG if it was set.
- The remaining expiry time of the message (if this is not an expiry report).
If this is an expiry report the expiry time is set to 60 seconds.
Activity option
- MQRO_ACTIVITY
- Using this value allows the route of any message
to be traced throughout a queue manager network. The report option can be
specified on any current user message, instantly allowing you to begin calculating
the route of the message through the network.
If the application generating
the message cannot switch on activity reports, reports can be turned on using
an API crossing exit supplied by queue manager administrators.
Notes:
- The fewer the queue managers in the network that are able to generate
activity reports, the less detailed the route.
- The activity reports might be difficult to place in the correct order
to determine the route taken.
- The activity reports might not be able to find a route to their requested
destination.
- Messages with this report option set must be accepted by any queue manager,
even if they do not understand the option. This allows the report option to
be set on any user message, even if they are processed by a non Version 6.0
queue manager.
- If a process, either a queue manager or a user process, performs an activity
on a message with this option set it can choose to generate and put an activity
report.
Default option: Specify the following if no report
options are required:
- MQRO_NONE
- Use this value to indicate that no other options have been specified.
MQRO_NONE is defined to aid program documentation. It is not intended that
this option be used with any other, but as its value is zero, such use cannot
be detected.
General information:
- All report types required must be specifically requested by the application
sending the original message. For example, if a COA report is requested but
an exception report is not, a COA report is generated when the message is
placed on the destination queue, but no exception report is generated if the
destination queue is full when the message arrives there. If no Report options are set, no report messages are generated by the
queue manager or message channel agent (MCA).
Some report options can be
specified even though the local queue manager does not recognize them; this
is useful when the option is to be processed by the destination queue manager. See Appendix E. Report options and message flags for more details.
If
a report message is requested, the name of the queue to which to send the
report must be specified in the ReplyToQ field. When a
report message is received, the nature of the report can be determined by
examining the Feedback field in the message descriptor.
- If the queue manager or MCA that generates a report message cannot put
the report message on the reply queue (for example, because the reply queue
or transmission queue is full), the report message is placed instead on the
dead-letter queue. If that also fails, or there is
no dead-letter queue, the action taken depends on the type of the report message:
- If the report message is an exception report, the message that generated
the exception report is left on its transmission queue; this ensures that
the message is not lost.
- For all other report types, the report message is discarded and processing
continues normally. This is done because either the original message has already
been delivered safely (for COA or COD report messages), or is no longer of
any interest (for an expiration report message).
Once a report message has been placed successfully on a queue (either
the destination queue or an intermediate transmission queue), the message
is no longer subject to special processing; it is treated just like any other
message.
- When the report is generated, the ReplyToQ queue is
opened and the report message put using the authority of the UserIdentifier in the MQMD of the message causing the report, except in the following
cases:
- Exception reports generated by a receiving MCA are put with whatever authority
the MCA used when it tried to put the message causing the report. The PutAuthority channel attribute determines the user identifier used.
- COA reports generated by the queue manager are put with whatever authority
was used when the message causing the report was put on the queue manager
generating the report. For example, if the message was put by a receiving
MCA using the MCA's user identifier, the queue manager puts the COA report
using the MCA's user identifier.
Applications generating reports must use the same authority as they
use to generate a reply; this is usually the authority of the user identifier
in the original message.
If the report has to travel to a remote destination,
senders and receivers can decide whether to accept it, in the same way as
they do for other messages.
- If a report message with data is requested:
- The report message is always generated with the amount of data requested
by the sender of the original message. If the report message is too big for
the reply queue, the processing described above occurs; the report message
is never truncated to fit on the reply queue.
- If the Format of the original message is MQFMT_XMIT_Q_HEADER,
the data included in the report does not include the MQXQH. The report data
starts with the first byte of the data beyond the MQXQH in the original message.
This occurs whether or not the queue is a transmission queue.
- If a COA, COD, or expiration report message is received at the reply queue,
it is guaranteed that the original message arrived, was delivered, or expired,
as appropriate. However, if one or more of these report messages is requested
and is not received, the reverse cannot be assumed,
because one of the following might have occurred:
- The report message is held up because a link is down.
- The report message is held up because a blocking condition exists at an
intermediate transmission queue or at the reply queue (for example, the queue
is full or inhibited for puts).
- The report message is on a dead-letter queue.
- When the queue manager was attempting to generate the report message,
it could neither put it on the appropriate queue, nor on the dead-letter queue,
so the report message could not be generated.
- A failure of the queue manager occurred between the action being reported
(arrival, delivery, or expiry), and generation of the corresponding report
message. (This does not happen for COD report messages if the application
retrieves the original message within a unit of work, as the COD report message
is generated within the same unit of work.)
Exception report messages can be held up in the same way for reasons
1, 2, and 3 above. However, when an MCA cannot generate an exception report
message (the report message cannot be put either on the reply queue or the
dead-letter queue), the original message remains on the transmission queue
at the sender, and the channel is closed. This occurs irrespective of whether
the report message was to be generated at the sending or the receiving end
of the channel.
- If the original message is temporarily blocked (resulting in an exception
report message being generated and the original message being put on a dead-letter
queue), but the blockage clears and an application then reads the original
message from the dead-letter queue and puts it again to its destination, the
following might occur:
- Even though an exception report message has been generated, the original
message eventually arrives successfully at its destination.
- More than one exception report message is generated in respect of a single
original message, because the original message might encounter another blockage
later.
Report messages for message segments:
- Report messages can be requested for messages that have segmentation allowed
(see the description of the MQMF_SEGMENTATION_ALLOWED flag). If the queue
manager finds it necessary to segment the message, a report message can be
generated for each of the segments that subsequently encounters the relevant
condition. Applications must be prepared to receive multiple report messages
for each type of report message requested. Use the GroupId field
in the report message to correlate the multiple reports with the group identifier
of the original message, and the Feedback field identify
the type of each report message.
- If MQGMO_LOGICAL_ORDER is used to retrieve report messages for segments,
be aware that reports of different types might be
returned by the successive MQGET calls. For example,
if both COA and COD reports are requested for a message that is segmented
by the queue manager, the MQGET calls for the report
messages might return the COA and COD report messages interleaved in an unpredictable
fashion. Avoid this by using the MQGMO_COMPLETE_MSG option (optionally with
MQGMO_ACCEPT_TRUNCATED_MSG). MQGMO_COMPLETE_MSG causes the queue manager to
reassemble report messages that have the same report type. For example, the
first MQGET call might reassemble all the COA messages
relating to the original message, and the second MQGET call
might reassemble all the COD messages. Which is reassembled first depends
on which type of report message occurs first on the queue.
- Applications that themselves put segments can specify different report
options for each segment. However, note the following points:
- If the segments are retrieved using the MQGMO_COMPLETE_MSG option, only
the report options in the first segment are honored
by the queue manager.
- If the segments are retrieved one by one, and most of them have one of
the MQRO_COD_* options, but at least one segment does not, you cannot
use the MQGMO_COMPLETE_MSG option to retrieve the report messages with a single MQGET call, or use the MQGMO_ALL_SEGMENTS_AVAILABLE option
to detect when all the report messages have arrived.
- In an MQ network, the queue managers can have different capabilities.
If a report message for a segment is generated by a queue manager or MCA that
does not support segmentation, the queue manager or MCA does not by default
include the necessary segment information in the report message, and this
might make it difficult to identify the original message that caused the report
to be generated. Avoid this difficulty by requesting data with the report
message, that is, by specifying the appropriate MQRO_*_WITH_DATA
or MQRO_*_WITH_FULL_DATA options. However, be aware that if MQRO_*_WITH_DATA
is specified, less than 100 bytes of application message
data might be returned to the application that retrieves the report message,
if the report message is generated by a queue manager or MCA that does not
support segmentation.
Contents of the message descriptor for a report message: When the queue manager or message channel agent (MCA) generates a report
message, it sets the fields in the message descriptor to the following values,
and then puts the message in the normal way.
Field in MQMD |
Value used |
StrucId |
MQMD_STRUC_ID |
Version |
MQMD_VERSION_2 |
Report |
MQRO_NONE |
MsgType |
MQMT_REPORT |
Expiry |
MQEI_UNLIMITED |
Feedback |
As appropriate for the nature of the report (MQFB_COA,
MQFB_COD, MQFB_EXPIRATION, or an MQRC_* value) |
Encoding |
Copied from the original message descriptor |
CodedCharSetId |
Copied from the original message descriptor |
Format |
Copied from the original message descriptor |
Priority |
Copied from the original message descriptor |
Persistence |
Copied from the original message descriptor |
MsgId |
As specified by the report options in the original message
descriptor |
CorrelId |
As specified by the report options in the original message
descriptor |
BackoutCount |
0 |
ReplyToQ |
Blanks |
ReplyToQMgr |
Name of queue manager |
UserIdentifier |
As set by the MQPMO_PASS_IDENTITY_CONTEXT option |
AccountingToken |
As set by the MQPMO_PASS_IDENTITY_CONTEXT option |
ApplIdentityData |
As set by the MQPMO_PASS_IDENTITY_CONTEXT option |
PutApplType |
MQAT_QMGR, or as appropriate for the message channel agent |
PutApplName |
First 28 bytes of the queue-manager name or message channel
agent name. For report messages generated by the IMS(TM) bridge, this field contains the XCF group
name and XCF member name of the IMS system to which the message relates. |
PutDate |
Date when report message is sent |
PutTime |
Time when report message is sent |
ApplOriginData |
Blanks |
GroupId |
Copied from the original message descriptor |
MsgSeqNumber |
Copied from the original message descriptor |
Offset |
Copied from the original message descriptor |
MsgFlags |
Copied from the original message descriptor |
OriginalLength |
Copied from the original message descriptor if not MQOL_UNDEFINED,
and set to the length of the original message data otherwise |
An application generating a report is recommended to set similar values,
except for the following:
- The ReplyToQMgr field can be set to blanks (the queue
manager changes this to the name of the local queue manager when the message
is put).
- Set the context fields using the option that would have been used for
a reply, normally MQPMO_PASS_IDENTITY_CONTEXT.
Analyzing the report field: The Report field
contains subfields; because of this, applications that need to check whether
the sender of the message requested a particular report must use one of the
techniques described in Analyzing the report field.
This is an output field for the MQGET call, and an
input field for the MQPUT and MQPUT1 calls. The initial value of this field is MQRO_NONE.