Remotely determined errors

When you send messages to a remote queue, even when the local queue manager has processed your MQI call without finding an error, other factors can influence how your message is handled by a remote queue manager. For example, the queue you are targeting may be full, or may not even exist. If your message has to be handled by other intermediate queue managers on the route to the target queue, any of these could find an error.

Problems delivering a message

When an MQPUT call fails, you have the choice of attempting to put the message on the queue again, returning it to the sender, or putting it on the dead-letter queue.

Each option has its own merits, but you may not want to retry putting a message if the reason that the MQPUT failed was because the destination queue was full. In this instance, putting it on the dead-letter queue allows you to deliver it to the correct destination queue later on.

Retry message delivery

Before the message is put on a dead-letter queue, a remote queue manager attempts to put the message on the queue again if the attributes MsgRetryCount and MsgRetryInterval have been set for the channel, or if there is a retry exit program for it to use (the name of which is held in the channel attribute MsgRetryExitId field).

If the MsgRetryExitId field is blank, the values in the attributes MsgRetryCount and MsgRetryInterval are used.

If the MsgRetryExitId field is not blank, the exit program of this name runs. For more information on using your own exit programs, see WebSphere MQ Intercommunication.

Return message to sender

You return a message to the sender by requesting a report message to be generated to include all of the original message. See Report messages for details on report message options.

Using the dead-letter (undelivered message) queue

When a queue manager cannot deliver a message, it attempts to put the message on its dead-letter queue. This queue should be defined when the queue manager is installed.

Your programs can use the dead-letter queue in the same way that the queue manager uses it. You can find the name of the dead-letter queue by opening the queue manager object (using the MQOPEN call) and inquiring about the DeadLetterQName attribute (using the MQINQ call).

When the queue manager puts a message on this queue, it adds a header to the message, the format of which is described by the dead-letter header (MQDLH) structure, in WebSphere MQ Application Programming Reference. This header includes the name of the target queue and the reason the message was put on the dead-letter queue. It must be removed and the problem must be resolved before the message is put on the intended queue. Also, the queue manager changes the Format field of the message descriptor (MQMD) to indicate that the message contains an MQDLH structure.

The addition of the header to a message may make the message too long for the dead-letter queue, so you should always make sure that your messages are shorter than the maximum size allowed for the dead-letter queue, by at least the value of the MQ_MSG_HEADER_LENGTH constant. The maximum size of messages allowed on a queue is determined by the value of the MaxMsgLength attribute of the queue. For the dead-letter queue, you should make sure that this attribute is set to the maximum allowed by the queue manager. If your application cannot deliver a message, and the message is too long to be put on the dead-letter queue, follow the advice given in the description of the MQDLH structure.

You need to ensure that the dead-letter queue is monitored, and that any messages arriving on it get processed. A dead-letter queue handler is provided by WebSphere MQ on all platforms except VSE/ESA. It runs as a batch utility and can be used to perform various actions on selected messages on the dead-letter queue. If you have a queue manager on one of the platforms that does not provide a dead-letter queue handler, you will need to provide your own. The program could be triggered, or run at regular intervals. For further details, see WebSphere MQ System Administration Guide for WebSphere MQ for AIX, HP-UX, Linux, OS/2, Solaris, and Windows systems; for WebSphere MQ for z/OS see WebSphere MQ for z/OS System Administration Guide; for other platforms, see the appropriate System Management Guide.

If data conversion is necessary, the queue manager converts the header information when you use the MQGMO_CONVERT option on the MQGET call. If the process putting the message is an MCA, the header is followed by all the text of the original message.

You should be aware that messages put on the dead-letter queue may be truncated if they are too long for this queue. A possible indication of this situation is the messages on the dead-letter queue being the same length as the value of the MaxMsgLength attribute of the queue.

Dead-letter queue processing

The rest of this chapter contains general-use programming interface information.

Dead-letter queue processing is dependent on local system requirements, but you should consider the following when you draw up the specification:

• The message can be identified as having a dead-letter queue header because the value of the format field in the MQMD, is MQFMT_DEAD_LETTER_HEADER.
• In WebSphere MQ for z/OS using CICS, if an MCA puts this message to the dead-letter queue, the PutApplType field is MQAT_CICS, and the PutApplName field is the ApplId of the CICS system followed by the transaction name of the MCA.
• The reason for the message to be routed to the dead-letter queue is contained in the Reason field of the dead-letter queue header.
• The dead-letter queue header contains details of the destination queue name and queue manager name.
• The dead-letter queue header contains fields that have to be reinstated in the message descriptor before the message is put to the destination queue. These are:
  1. Encoding
  2. CodedCharSetId
  3. Format
• The message descriptor is the same as PUT by the original application, except for the three fields shown above.

Your dead-letter queue application should do one or more of the following:

• Examine the Reason field. A message may have been put by an MCA for the following reasons:
  • The message was longer than the maximum message size for the channel

    The reason will be MQRC_MSG_TOO_BIG_FOR_CHANNEL (or MQRC_MSG_TOO_BIG_FOR_Q_MGR if you are using CICS for distributed queuing on WebSphere MQ for z/OS)

  • The message could not be put to its destination queue

    The reason will be any MQRC_* reason code that can be returned by an MQPUT operation

  • A user exit has requested this action

    The reason code will be that supplied by the user exit, or the default MQRC_SUPPRESSED_BY_EXIT

• Try to forward the message to its intended destination, where this is possible.
• Retain the message for a certain length of time before discarding when the reason for the diversion is determined, but not immediately correctable.
• Give instructions to administrators for the correction of problems where these have been determined.
• Discard messages that are corrupted or otherwise not processible.

There are two ways that you deal with the messages you have recovered from the dead-letter queue:

1. If the message is for a local queue, you should:
   • Carry out any code translations required to extract the application data
   • Carry out code conversions on that data if this is a local function
   • Put the resulting message on the local queue with all the detail of the message descriptor restored
2. If the message is for a remote queue, put the message on the queue.

For information on how undelivered messages are handled in a distributed queuing environment, see WebSphere MQ Intercommunication.