JMS report messages

Using JMS report messages

JMS applications can use report messages as a form of managed request/response processing, to give remote feedback to producers on the outcome of their send operations and the fate of their messages.

JMS applications can request the following types of report message by setting appropriate JMS_IBM_Report_Xxxx message properties and options. The options have the same general syntax and meaning:

MQRO_report-type: A report message of the indicated type is generated that contains the MQMD of the original message. It does not contain any message body data.
MQRO_report-type_WITH_DATA: A report message of the indicated type is generated that contains the MQMD, any MQ headers, and 100 bytes of body data.
MQRO_report-type_WITH_FULL_DATA: A report message of the indicated type is generated that contains all data from the original message.

For example, to request a COD report message with full data, the JMS application must set JMS_IBM_Report_COD to the value MQRO_COD_WITH_FULL_DATA.

Type of report message Description JMS_IBM_Report_Xxxx message property and options
Exception Send a report message if the request message cannot be put to the target queue. The exception report messages are generated when a message has been rerouted to an exception destination. JMS_IBM_Report_Exception

MQRO_EXCEPTION
MQRO_EXCEPTION_WITH_DATA
MQRO_EXCEPTION_WITH_FULL_DATA

Expiration Send a report message if the request message passes its expiry time. JMS_IBM_Report_Expiration

MQRO_EXPIRATION
MQRO_EXPIRATION_WITH_DATA
MQRO_EXPIRATION_WITH_FULL_DATA

Confirm on arrival (COA) Send a report message when the request message has been put to the target queue.
For publish/subscribe messaging, the COA report message is generated only on the producers messaging engine. Therefore, such reports are relevant only to local subscriptions.
For point-to-point messaging, COA messages are generated when the message arrives at the final destination. For partitioned queues, the report message is generated only when the put operation has committed and a final destination has therefore been selected. Any With_Data or With_Full_Data report options specified are ignored; the COA report message deals only with message headers.
If a forward-routing path is used, the COA message are generated when the message arrives at the final destination in the path.
JMS_IBM_Report_COA

MQRO_COA
MQRO_COA_WITH_DATA
MQRO_COA_WITH_FULL_DATA

Confirm on delivery (COD) Send a report message when the request message has been removed from the queue or topic space by a message consumer.
For publish/subscribe messaging, the COD message is generated when all subscribers have received the request message. Therefore, there is one COD message generated for every COA. When a message is consumed by a subscriber, the reference count of the message on the topic space is reduced. When the reference count reaches zero, the message is removed from the topic space then a COD report message is generated.
For point-to-point messaging, the COD message is generated after the message has been successfully received by a consuming application. Any With_Data or With_Full_Data report options specified are ignored; the COD report message deals only with message headers.
JMS_IBM_Report_COD

MQRO_COD
MQRO_COD_WITH_DATA
MQRO_COD_WITH_FULL_DATA

Positive action notification (PAN) Ask the consumer application to send a report message when it has successfully processed the request message. JMS_IBM_Report_PAN

MQRO_PAN

Negative action notification (NAN) Ask the consumer application to send a report message if it has not successfully processed the request message. JMS_IBM_Report_NAN

MQRO_NAN

The requesting application can control other aspects of the report message as follows:

Type of report message	Description	JMS_IBM_Report_Xxxx message property and options
Exception	Send a report message if the request message cannot be put to the target queue. The exception report messages are generated when a message has been rerouted to an exception destination.	JMS_IBM_Report_Exception MQRO_EXCEPTION MQRO_EXCEPTION_WITH_DATA MQRO_EXCEPTION_WITH_FULL_DATA
Expiration	Send a report message if the request message passes its expiry time.	JMS_IBM_Report_Expiration MQRO_EXPIRATION MQRO_EXPIRATION_WITH_DATA MQRO_EXPIRATION_WITH_FULL_DATA
Confirm on arrival (COA)	Send a report message when the request message has been put to the target queue. For publish/subscribe messaging, the COA report message is generated only on the producers messaging engine. Therefore, such reports are relevant only to local subscriptions. For point-to-point messaging, COA messages are generated when the message arrives at the final destination. For partitioned queues, the report message is generated only when the put operation has committed and a final destination has therefore been selected. Any With_Data or With_Full_Data report options specified are ignored; the COA report message deals only with message headers. If a forward-routing path is used, the COA message are generated when the message arrives at the final destination in the path.	JMS_IBM_Report_COA MQRO_COA MQRO_COA_WITH_DATA MQRO_COA_WITH_FULL_DATA
Confirm on delivery (COD)	Send a report message when the request message has been removed from the queue or topic space by a message consumer. For publish/subscribe messaging, the COD message is generated when all subscribers have received the request message. Therefore, there is one COD message generated for every COA. When a message is consumed by a subscriber, the reference count of the message on the topic space is reduced. When the reference count reaches zero, the message is removed from the topic space then a COD report message is generated. For point-to-point messaging, the COD message is generated after the message has been successfully received by a consuming application. Any With_Data or With_Full_Data report options specified are ignored; the COD report message deals only with message headers.	JMS_IBM_Report_COD MQRO_COD MQRO_COD_WITH_DATA MQRO_COD_WITH_FULL_DATA
Positive action notification (PAN)	Ask the consumer application to send a report message when it has successfully processed the request message.	JMS_IBM_Report_PAN MQRO_PAN
Negative action notification (NAN)	Ask the consumer application to send a report message if it has not successfully processed the request message.	JMS_IBM_Report_NAN MQRO_NAN

How the message Id is generated for the report message and any reply message:

MQRO_New_Msg_Id

This the default. A new message Id is generated for the report message.

MQRO_Pass_Msg_Id

The message Id of the report message is set to the message Id of the request message.
How the correlation Id of the report or reply message is to be set.

MQRO_Copy_Msg_Id_To_Correl_Id

This the default. the correlation Id of the report message is set to the message Id of the request message.

MQRO_Pass_Correl_Id

The correlation Id of the report message is set to the correlation Id of the request message.

For more information about report messages and the associated properties and options, see the WebSphere MQ: Using Java book, SC34-6066.

Related tasks
Designing an enterprise application to use JMS

Related reference
The effect of transaction context on non-durable subscribers