Types of message

There are four types of message defined by WebSphere MQ:

• Datagram
• Request
• Reply
• Report

Applications can use the first three types of messages to pass information between themselves. The fourth type, report, is for applications and queue managers to use to report information about events such as the occurrence of an error.

Each type of message is identified by an MQMT_* value. You can also define your own types of message. For the range of values you can use, see the description of the MsgType field in WebSphere MQ Application Programming Reference.

Datagrams

You should use a datagram when you do not require a reply from the application that receives the message (that is, gets the message from the queue).

An example of an application that could use datagrams is one that displays flight information in an airport lounge. A message could contain the data for a whole screen of flight information. Such an application is unlikely to request an acknowledgement for a message because it probably does not matter if a message is not delivered. The application will send an update message after a short period of time.

Request messages

You should use a request message when you want a reply from the application that receives the message.

An example of an application that could use request messages is one that displays the balance of a checking account. The request message could contain the number of the account, and the reply message would contain the account balance.

If you want to link your reply message with your request message, there are two options:

• You can give the application that handles the request message the responsibility of ensuring that it puts information into the reply message that relates to the request message.
• You can use the report field in the message descriptor of your request message to specify the content of the MsgId and CorrelId fields of the reply message:
  • You can request that either the MsgId or the CorrelId of the original message is to be copied into the CorrelId field of the reply message (the default action is to copy MsgId).
  • You can request that either a new MsgId is generated for the reply message, or that the MsgId of the original message is to be copied into the MsgId field of the reply message (the default action is to generate a new message identifier).

Reply messages

You should use a reply message when you reply to another message.

When you create a reply message, you should respect any options that were set in the message descriptor of the message to which you are replying. Report options specify the content of the message identifier (MsgId) and correlation identifier (CorrelId) fields. These fields allow the application that receives the reply to correlate the reply with its original request.

Report messages

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

• A queue manager,
• A message channel agent (for example, if they cannot deliver the message),

  or

• An application (for example, if it cannot use the data in the message).

Note that report messages can be generated at any time, and they may 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:

• An exception report message. This is sent in response to a message that had the exceptions flag set. It is generated by the message channel agent (MCA) or the application.
• An expiry report message. This indicates that an application attempted to retrieve a message that had reached its expiry threshold; the message is marked to be discarded. This type of report is generated by the queue manager.
• A confirmation of arrival (COA) report message. This indicates that the message has reached its target queue. It is generated by the queue manager.
• A confirmation of delivery (COD) report message. This indicates that the message has been retrieved by a receiving application. It is generated by the queue manager.
• A positive action notification (PAN) report message. This indicates that a request has been successfully serviced (that is, the action requested in the message has been performed successfully). This type of report is generated by the application.
• A negative action notification (NAN) report message. This indicates that a request has not been successfully serviced (that is, the action requested in the message has not been performed successfully). This type of report is generated by the application.

Note:

Each type of report message contains one of the following:

• The entire original message
• The first 100 bytes of data in the original message
• No data from the original message

You may 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 will receive an exception report message. However, if you select only the delivery confirmation report message option and the message fails to be delivered, you will not get an exception report message.

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

Report message options

You have the option to 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 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 will be placed on the dead-letter queue.

If you wish to receive a report message, you must specify the name of your reply-to queue in the ReplyToQ field; otherwise the MQPUT or MQPUT1 of your original message will fail 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:

• You 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. MQRO_COPY_MSG_ID_TO_CORRELID should be used 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.
• You 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. MQRO_NEW_MSG_ID should be used because it ensures that each message in the system has a different message identifier, and therefore can be distinguished unambiguously from all other messages in the system.
• Specialized applications may need to use MQRO_PASS_MSG_ID and, or MQRO_PASS_CORREL_ID. However, the application that reads the messages from the queue may need careful design in order to ensure that it will work correctly. In particular when the queue contains multiple messages with the same message identifier.

  Server applications should 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 which 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 should 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 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 WebSphere MQ Application Programming Reference.

An example of a program that could use a feedback code is one that monitors the work loads 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 could 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.)

Reports and segmented messages

Not supported in WebSphere MQ for z/OS.

If a message is segmented (see Message segmentation for a description of this) and you ask for reports to be generated, you may receive more reports than you would have done had the message not been segmented.

For reports generated by WebSphere MQ

If you segment your messages or allow the queue manager to do so, there is only one case in which you can expect to receive a single report for the entire message. This is when you have requested only COD reports, and you have specified MQGMO_COMPLETE_MSG on the getting application.

In other cases your application must be prepared to deal with several reports; usually one for each segment.

Note:

If you segment your messages, and you need only the first 100 bytes of the original message data to be returned, you must change the setting of the report options to ask for reports with no data for segments that have an offset of 100 or more. If you do not do this, and you leave the setting so that each segment requests 100 bytes of data, and you retrieve the report messages with a single MQGET specifying MQGMO_COMPLETE_MSG, the reports assemble into a large message containing 100 bytes of read data at each appropriate offset. If this happens, you need a large buffer or you need to specify MQGMO_ACCEPT_TRUNCATED_MSG.

If your application generates reports, you should always copy the WebSphere MQ headers that are present at the start of the original message data to the report message data. Then add none, 100 bytes, or all of the original message data (or whatever other amount you would normally include) to the report message data.

You can recognize the WebSphere MQ headers that must be copied by looking at the successive Format names, starting with the MQMD and continuing through any headers present. The following Format names indicate these WebSphere MQ headers:

• MQMDE
• MQDLH
• MQXQH
• MQIIH
• MQH*

MQH* means any name starting with the characters MQH.

The Format name occurs at specific positions for MQDLH and MQXQH, but for the other WebSphere MQ headers it occurs at the same position. The length of the header is contained in a field that also occurs at the same position for MQMDE, MQIMS and all MQH* headers.

If you are using a Version 1 of the MQMD, and you are reporting on a segment, or a message in a group, or a message for which segmentation is allowed, the report data must start with an MQMDE. You should set the OriginalLength field to the length of the original message data excluding the lengths of any WebSphere MQ headers that you find.

Retrieval of reports

If you ask for COA or COD reports, you can ask for them to be reassembled for you with MQGMO_COMPLETE_MSG. An MQGET with MQGMO_COMPLETE_MSG is satisfied when enough report messages (of a single type, for example COA, and with the same GroupId) are present on the queue to represent one complete original message. This is true even if the report messages themselves do not contain the complete original data; the OriginalLength field in each report message gives the length of original data represented by that report message, even if the data itself is not present.

This technique can be used even if there are several different report types present on the queue (for example, both COA and COD), because an MQGET with MQGMO_COMPLETE_MSG reassembles report messages only if they have the same Feedback code. Note, however, that you cannot normally use the technique for exception reports, since in general these have different Feedback codes.

You can use this technique to get a positive indication that the entire message has arrived. However, in most circumstances you need to cater for the possibility that some segments arrive while others may generate an exception (or expiry, if you have allowed this). You cannot use MQGMO_COMPLETE_MSG in this case because in general you may get different Feedback codes for different segments and, as noted above, you may get more than one report for a given segment. You can, however, use MQGMO_ALL_SEGMENTS_AVAILABLE.

To allow for this you may need to retrieve reports as they arrive, and build up a picture in your application of what happened to the original message. You can use the GroupId field in the report message to correlate reports with the GroupId of the original message, and the Feedback field to identify the type of each report message. The way in which you do this depends on your application requirements.

One approach is as follows:

• Ask for COD reports and exception reports.
• After a specific time, check whether a complete set of COD reports has been received using MQGMO_COMPLETE_MSG. If so, your application knows that the entire message has been processed.
• If not, and exception reports relating to this message are present, the problem should be handled just as for unsegmented messages, though provision must also be made for "orphan" segments to be cleaned up at some point.
• If there are segments for which there are no reports of any kind, the original segments (or the reports) may be waiting for a channel to be reconnected, or the network might be overloaded at some point. If no exception reports at all have been received (or if you think that the ones you have may be temporary only), you may decide to let your application wait a little longer.

  As before, this is similar to the considerations you have when dealing with unsegmented messages, except that you must also consider the possibility of "orphan" segments which have to be cleaned up.

If the original message is not critical (for example, if it is a query, or a message that can be repeated later), set an expiry time to ensure that orphan segments are removed.

Back-level queue managers

When a report is generated by a queue manager that supports segmentation, but is received on a queue manager that does not support segmentation, the MQMDE structure (which identifies the Offset and OriginalLength represented by the report) is always included in the report data, in addition to zero, 100 bytes, or all of the original data in the message.

However, if a segment of a message passes through a queue manager that does not support segmentation, you should be aware that if a report is generated there, the MQMDE structure in the original message will be treated purely as data. It will not therefore be included in the report data if zero bytes of the original data have been requested. Without the MQMDE, the report message may not be useful.

You should therefore request at least 100 bytes of data in reports if there is a possibility that the message might travel through a back-level queue manager.