Network Deployment (Distributed operating systems), v8.0 > Reference > Developer best practices
Map MQMD Report fields to JMS provider-specific properties
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. A JMS application can request different types of report message by setting JMS_IBM_Report_Xxxx message properties and options.
JMS applications can request the following types of report message by setting the 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 WebSphere MQ message descriptor (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. Use the following prefix with each option: com.ibm.websphere.sib.api.jms.
For example, to request a Confirm on delivery (COD) report message with full data, the JMS application must set JMS_IBM_Report_COD to the value com.ibm.websphere.sib.api.jms.MQRO_COD_WITH_FULL_DATA.
For each type of report message, the following table shows the JMS_IBM_Report_Xxxx message property that a JMS application can set, and the MQMD Report field options that map to the property.
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
Discard Discard the original request message rather than sending it to an exception destination. Use with the JMS_IBM_Report_Exception property set to MQRO_EXCEPTION_WITH_FULL_DATA to return an undeliverable request message to its sender. JMS_IBM_Report_Discard_Msg
- TRUE
- FALSE
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
- TRUE
- FALSE
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
- TRUE
- FALSE
The requesting application can control other aspects of the report message as follows:
- 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 refer to the Use Java section of the WebSphere MQ information center, available from the WebSphere MQ library.