Options for report messages.
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 MDREP 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:
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).
The application that receives the report message can determine the reason the report was generated by examining the MDFB field in the MQMD; see the MDFB field for more details.
Exception options: You can specify one of the options listed below to request an exception report message.
Activity reports required
This report option enables an activity report to be generated, whenever a message with this report option set is processed by supporting applications.
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 back level queue managers. To achieve this, the report option is placed in the MQRO_ACCEPT_UNSUP_MASK subfield.
If a process (either a queue manager or a user process) performs an Activity on a message with MQRO_ACTIVITY set, it can choose to generate and put an activity report.
The activity report option 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 and instantly they can begin to calculate the route of the message through the network. If the application generating the message cannot switch on activity reports, it can be turned on by using an API crossing exit supplied by queue manager administrators.
Several conditions are applicable to activity reports:
This type of report can be generated by a message channel agent 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:
Refer to the WebSphere MQ Intercommunication book for more information about normal and fast message channels.
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 that it has received 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 ROEXC, ROEXCD, and ROEXCF.
This is the same as ROEXC, 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 ROEXC, ROEXCD, and ROEXCF.
This is the same as ROEXC, except that all of the application message data from the original message is included in the report message.
Do not specify more than one of ROEXC, ROEXCD, and ROEXCF.
Expiration options: You can specify one of the options listed below to request an expiration report message.
This type of report is generated by the queue manager if the message is discarded prior to delivery to an application because its expiry time has passed (see the MDEXP field). If this option is not set, no report message is generated if a message is discarded for this reason (even if one of the ROEXC* options is specified).
Message data from the original message is not included with the report message.
Do not specify more than one of ROEXP, ROEXPD, and ROEXPF.
This is the same as ROEXP, 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 ROEXP, ROEXPD, and ROEXPF.
This is the same as ROEXP, except that all of the application message data from the original message is included in the report message.
Do not specify more than one of ROEXP, ROEXPD, and ROEXPF.
Confirm-on-arrival options: You can specify one of the options listed below to request a confirm-on-arrival report message.
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 becomes available for retrieval only if and when the unit of work is committed.
A COA report is not generated if the MDFMT field in the message descriptor is FMXQH or FMDLH. 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 ROCOA, ROCOAD, and ROCOAF.
This is the same as ROCOA, 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 ROCOA, ROCOAD, and ROCOAF.
This is the same as ROCOA, except that all of the application message data from the original message is included in the report message.
Do not specify more than one of ROCOA, ROCOAD, and ROCOAF.
Discard and expiry options: You can specify the option below to set the expiry time and discard flag for report messages.
This option ensures that report messages and reply messages inherit the expiry time and discard flag (whether to discard or not), from their original messages. With this option set, report and reply messages:
With this option set, the following applies:
Confirm-on-delivery options: You can specify one of the options listed below to request a confirm-on-delivery report message.
This type of report is generated by the queue manager when an application retrieves the message from the destination queue in a way that causes the message to be deleted 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 generated if the MDFMT field in the message descriptor is FMDLH. This prevents a COD report being generated if the message is undeliverable and put on a dead-letter queue.
ROCOD is not valid if the destination queue is an XCF queue.
Do not specify more than one of ROCOD, ROCODD, and ROCODF.
This is the same as ROCOD, 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 GMATM 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 is the minimum of:
ROCODD is not valid if the destination queue is an XCF queue.
Do not specify more than one of ROCOD, ROCODD, and ROCODF.
This is the same as ROCOD, except that all of the application message data from the original message is included in the report message.
ROCODF is not valid if the destination queue is an XCF queue.
Do not specify more than one of ROCOD, ROCODD, and ROCODF.
Action-notification options: You can specify one or both of the options listed below to request that the receiving application send a positive-action or negative-action report message.
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 or not 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 upon this option. It is the responsibility of the retrieving application to generate the report if appropriate.
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 or not any data is to be included with the report. For example, it may be desirable 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 upon this option. It is the responsibility of the retrieving application to generate the report if appropriate.
Determination of which conditions correspond to a positive action and which correspond to a negative action is the responsibility of the application. However, it is recommended that if the request has been only partially performed, a NAN report rather than a PAN report should be generated if requested. It is also recommended that every possible condition should correspond to either a positive action, or a negative action, but not both.
Message-identifier options: You can specify one of the options listed below to control how the MDMID of the report message (or of the reply message) is to be set.
This is the default action, and indicates that if a report or reply is generated as a result of this message, a new MDMID is to be generated for the report or reply message.
If a report or reply is generated as a result of this message, the MDMID of this message is to be copied to the MDMID of the report or reply message.
If this option is not specified, RONMI is assumed.
Correlation-identifier options: You can specify one of the options listed below to control how the MDCID of the report message (or of the reply message) is to be set.
This is the default action, and indicates that if a report or reply is generated as a result of this message, the MDMID of this message is to be copied to the MDCID of the report or reply message.
If a report or reply is generated as a result of this message, the MDCID of this message is to be copied to the MDCID of the report or reply message.
If this option is not specified, ROCMTC is assumed.
Servers replying to requests or generating report messages are recommended to check whether the ROPMI or ROPCI options were set in the original message. If they were, the servers should take the action described for those options. If neither is set, the servers should take the corresponding default action.
Disposition options: You can 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.
This is the default action, and indicates that the message should be placed on the dead-letter queue, if the message cannot be delivered to the destination queue. An exception report message will be generated, if one was requested by the sender.
This indicates that the message should be discarded if it cannot be delivered to the destination queue. An exception report message will be generated, if one was requested by the sender.
If it is desired to return the original message to the sender, without the original message being placed on the dead-letter queue, the sender should specify RODISC with ROEXCF.
Default option: You can specify the following if no report options are required:
This value can be used to indicate that no other options have been specified. RONONE 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:
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 D. Report options and message flags for more details.
If a report message is requested, the name of the queue to which the report should be sent must be specified in the MDRQ field. When a report message is received, the nature of the report can be determined by examining the MDFB field in the message descriptor.
If the report has to travel to a remote destination, senders and receivers can decide whether or not to accept it, in the same way as they do for other messages.
Exception report messages may be held up in the same way for reasons 1, 2, and 3 above. However, when an MCA is unable to 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.
Report messages for message segments:
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 |
---|---|
MDSID | MDSIDV |
MDVER | MDVER2 |
MDREP | RONONE |
MDMT | MTRPRT |
MDEXP | EIULIM |
MDFB | As appropriate for the nature of the report (FBCOA, FBCOD, FBEXP, or an RC* value) |
MDENC | Copied from the original message descriptor |
MDCSI | Copied from the original message descriptor |
MDFMT | Copied from the original message descriptor |
MDPRI | Copied from the original message descriptor |
MDPER | Copied from the original message descriptor |
MDMID | As specified by the report options in the original message descriptor |
MDCID | As specified by the report options in the original message descriptor |
MDBOC | 0 |
MDRQ | Blanks |
MDRM | Name of queue manager |
MDUID | As set by the PMPASI option |
MDACC | As set by the PMPASI option |
MDAID | As set by the PMPASI option |
MDPAT | ATQM, or as appropriate for the message channel agent |
MDPAN | First 28 bytes of the queue manager name or message channel agent name. For report messages generated by the IMS bridge, this field contains the XCF group name and XCF member name of the IMS system to which the message relates. |
MDPD | Date when report message is sent |
MDPT | Time when report message is sent |
MDAOD | Blanks |
MDGID | Copied from the original message descriptor |
MDSEQ | Copied from the original message descriptor |
MDOFF | Copied from the original message descriptor |
MDMFL | Copied from the original message descriptor |
MDOLN | Copied from the original message descriptor if not OLUNDF, 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:
Analyzing the report field: The MDREP field contains subfields; because of this, applications that need to check whether the sender of the message requested a particular report should 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 RONONE.
Notices |
Downloads |
Library |
Support |
Feedback
![]() ![]() |
js51190 |