What happens when a message cannot be delivered?

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

Figure 31. What happens when a message cannot be delivered

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 has the option to wait and retry the operation later. You can determine if the MCA waits, for how long, and how many times it retries.

• You 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 retries the operation the number of times specified, at the time interval specified.
• You can write your own message-retry exit. The exit enables you to specify under what conditions you want the MCA to retry the MQPUT or MQOPEN operation. Specify the name of the exit when you define the channel.

Message-retry is not available on WebSphere MQ for z/OS, or MQSeries for VSE/ESA.

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 this, you 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.)

Return-to-sender is not available on MQSeries for VSE/ESA.

3. Dead-letter queue

If a message cannot be delivered or returned, it is put on to the dead-letter queue (DLQ). You can use the DLQ handler to process the message. This is described in the WebSphere MQ System Administration Guide book for WebSphere MQ for AIX, HP-UX, Linux, Solaris, and Windows systems, and MQSeries V5.1 for OS/2 Warp, and in the WebSphere MQ for z/OS System Administration Guide for z/OS.

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 WebSphere MQ Version 5 products, if no local dead-letter queue is defined, the remote queue is not available or defined, and there is no remote dead-letter queue, the channel stops abnormally, and messages are not rolled back to the sending transmission queue. You must resolve the channel using the COMMIT or BACKOUT functions.