What happens when a message cannot be delivered?

When a message cannot be delivered, the MCA can process it in several ways. It can try again, it can return-to-sender, or it can put it on the dead-letter queue.

Figure 1 shows the processing that occurs when an MCA is unable to put a message to the destination queue. (The options shown do not apply on all platforms.)

As shown in the figure, the MCA can do several things with a message that it cannot deliver. The action taken is determined by options specified when the channel is defined and on the MQPUT report options for the message.

1. Message-retry

   If the MCA is unable to put a message to the target queue for a reason that could be transitory (for example, because the queue is full), the MCA can wait and try the operation again later. We can determine if the MCA waits, for how long, and how many times it tries.
   • We can specify a message-retry time and interval for MQPUT errors when you define your channel. If the message cannot be put to the destination queue because the queue is full, or is inhibited for puts, the MCA tries the operation the number of times specified, at the time interval specified.
   • We can write your own message-retry exit. The exit enables you to specify under what conditions we want the MCA to try the MQPUT or MQOPEN operation again. Specify the name of the exit when you define the channel.

2. Return-to-sender

   If message-retry was unsuccessful, or a different type of error was encountered, the MCA can send the message back to the originator. To enable return-to-sender, we need to specify the following options in the message descriptor when you put the message to the original queue:
   • The MQRO_EXCEPTION_WITH_FULL_DATA report option
   • The MQRO_DISCARD_MSG report option
   • The name of the reply-to queue and reply-to queue manager

   If the MCA is unable to put the message to the destination queue, it generates an exception report containing the original message, and puts it on a transmission queue to be sent to the reply-to queue specified in the original message. (If the reply-to queue is on the same queue manager as the MCA, the message is put directly to that queue, not to a transmission queue.)

3. Dead-letter queue

   If a message cannot be delivered or returned, it is put on to the dead-letter queue (DLQ). We can use the DLQ handler to process the message. This processing is described in Processing messages on a dead-letter queue for IBM MQ for UNIX, Linux and Windows systems, and in The dead-letter queue handler utility (CSQUDLQH) for z/OS systems. If the dead-letter queue is not available, the sending MCA leaves the message on the transmission queue, and the channel stops. On a fast channel, nonpersistent messages that cannot be written to a dead-letter queue are lost.

   On IBM WebSphere MQ Version 7.0, if no local dead-letter queue is defined, the remote queue is not available or defined, and there is no remote dead-letter queue, then the sender channel goes into RETRY and messages are automatically rolled back to the transmission queue.

Parent topic: Introduction to distributed queue management

Related information

• Use Dead-Letter Queue (USEDLQ)