Report messages

Report messages inform applications about events such as the occurrence of an error when processing a message. They can be generated by:

Report messages can be generated at any time, and might arrive on a queue when your application is not expecting them.

Types of report message

When you put a message on a queue, you can select to receive:

Note:
Each type of report message contains one of the following:

You can request more than one type of report message when you put a message on a queue. If you select the delivery confirmation report message and the exception report message options, in the event that the message fails to be delivered, you receive an exception report message. However, if you select only the delivery confirmation report message option and the message fails to be delivered, you do not get an exception report message.

The report messages that you request, when the criteria for generating a particular message are met, are the only ones that you receive.

Report message options

You can discard a message after an exception has arisen. If you select the discard option, and have requested an exception report message, the report message goes to the ReplyToQ and ReplyToQMgr, and the original message is discarded.

Note:
A benefit of this is that you can reduce the number of messages going to the dead-letter queue. However, it does mean that your application, unless it sends only datagram messages, has to deal with returned messages. When an exception report message is generated, it inherits the persistence of the original message.

If a report message cannot be delivered (if the queue is full, for instance), the report message is placed on the dead-letter queue.

If you want to receive a report message, specify the name of your reply-to queue in the ReplyToQ field; otherwise the MQPUT or MQPUT1 of your original message fails with MQRC_MISSING_REPLY_TO_Q.

You can use other report options in the message descriptor (MQMD) of a message to specify the content of the MsgId and CorrelId fields of any report messages that are created for the message:

When generating a report about a message, server applications must test to see if any of these options have been set.

For more information on how to use report messages, see the description of the Report field in the WebSphere MQ Application Programming Reference.

To indicate the nature of the report, queue managers use a range of feedback codes. They put these codes in the Feedback field of the message descriptor of a report message. Queue managers can also return MQI reason codes in the Feedback field. WebSphere MQ defines a range of feedback codes for applications to use.

For more information on feedback and reason codes, see the description of the Feedback field in the WebSphere MQ Application Programming Reference.

An example of a program that could use a feedback code is one that monitors the workloads of other programs serving a queue. If there is more than one instance of a program serving a queue, and the number of messages arriving on the queue no longer justifies this, such a program can send a report message (with the feedback code MQFB_QUIT) to one of the serving programs to indicate that the program should terminate its activity. (A monitoring program could use the MQINQ call to find out how many programs are serving a queue.)