Types of message

There are four types of messages defined by IBM MQ .

These four messages are:

• Datagram
• Request messages
• Reply messages
• Report messages
  • Types of report message
  • Report message options

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. We can also define your own types of message. For the range of values we can use, see MsgType.

Datagrams

Use a datagram when we 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 might use datagrams is one that displays flight information in an airport lounge. A message might contain the data for a whole screen of flight information. Such an application is unlikely to request an acknowledgment for a message because it probably does not matter if a message is not delivered. The application sends an update message after a short time.

Request messages

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:

• Make the application that handles the request message responsible for ensuring that it puts information into the reply message that relates to the request message.
• 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:
  • We 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).
  • We 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

Use a reply message when you reply to another message.

When you create a reply message, 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).

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

Types of report message

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

• An exception report message. This is sent in response to a message with 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

We 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, if 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, we 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

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.

Note: A benefit of this is that we can reduce the number of messages going to the dead-letter queue. However, it does mean that our 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 is 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, you 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 do not need to check the settings of these flags. This is because these applications typically 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 about how to use report messages, see Report.

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. IBM MQ defines a range of feedback codes for applications to use.

For more information about feedback and reason codes, see Feedback.

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