Report message options

 

We 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.

A benefit of this is that we 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.

We 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:

• We can request that either the MsgId or the CorrelId of the original message is to be copied into the CorrelId field of the report message. The default action is to copy the message identifier. Use MQRO_COPY_MSG_ID_TO_CORRELID because it enables the sender of a message to correlate the reply or report message with the original message. The correlation identifier of the reply or report message will be identical to the message identifier of the original message.

• We can request that either a new MsgId is generated for the report message, or that the MsgId of the original message is to be copied into the MsgId field of the report message. The default action is to generate a new message identifier. Use MQRO_NEW_MSG_ID because it ensures that each message in the system has a different message identifier, and can be distinguished unambiguously from all other messages in the system.

• Specialized applications might need to use MQRO_PASS_MSG_ID or MQRO_PASS_CORREL_ID. However, we need to design the application that reads the messages from the queue to ensure that it works correctly when, for example, the queue contains multiple messages with the same message identifier.

  Server applications must check the settings of these flags in the request message, and set the MsgId and CorrelId fields in the reply or report message appropriately.

  Applications that act as intermediaries between a requester application and a server application should not need to check the settings of these flags. This is because these applications usually need to forward the message to the server application with the MsgId, CorrelId, and Report fields unchanged. This allows the server application to copy the MsgId from the original message in the CorrelId field of the reply 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 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 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.)

 

Parent topic:

Report messages

fg10640_