DLQ rules (patterns and actions)

A description of the pattern-matching keywords (those against which messages on the dead-letter queue are matched), and the action keywords (those that determine how the DLQ handler is to process a matching message). An example rule is also provided.


The pattern-matching keywords

The pattern-matching keywords, which we use to specify values against which messages on the DLQ are matched, are as follows. (All pattern-matching keywords are optional):

    APPLIDAT ( ApplIdentityData|* )
    The ApplIdentityData value specified in the message descriptor, MQMD, of the message on the DLQ.

    APPLNAME ( PutApplName|* )
    The name of the application that issued the MQPUT or MQPUT1 call, as specified in the PutApplName field of the message descriptor, MQMD, of the message on the DLQ.

    APPLTYPE ( PutApplType|* )
    The PutApplType value, specified in the message descriptor, MQMD, of the message on the DLQ.

    DESTQ ( QueueName|* )
    The name of the message queue for which the message is destined.

    DESTQM ( QueueManagerName|* )
    The name of the queue manager of the message queue for which the message is destined.

    FEEDBACK ( Feedback|* )
    When the MsgType value is MQFB_REPORT, Feedback describes the nature of the report.

    We can use symbolic names. For example, we can use the symbolic name MQFB_COA to identify those messages on the DLQ that need confirmation of their arrival on their destination queues.

    FORMAT ( Format|* )
    The name that the sender of the message uses to describe the format of the message data.

    MSGTYPE ( MsgType|* )
    The message type of the message on the DLQ.

    We can use symbolic names. For example, we can use the symbolic name MQMT_REQUEST to identify those messages on the DLQ that need replies.

    PERSIST ( Persistence|* )
    The persistence value of the message. (The persistence of a message determines whether it survives restarts of the queue manager.)

    We can use symbolic names. For example, we can use the symbolic name MQPER_PERSISTENT to identify messages on the DLQ that are persistent.

    REASON ( ReasonCode|* )
    The reason code that describes why the message was put to the DLQ.

    We can use symbolic names. For example, we can use the symbolic name MQRC_Q_FULL to identify those messages placed on the DLQ because their destination queues were full.

    REPLYQ ( QueueName|* )
    The name of the reply-to queue specified in the message descriptor, MQMD, of the message on the DLQ.

    REPLYQM ( QueueManagerName|* )
    The name of the queue manager of the reply-to queue, as specified in the message descriptor, MQMD, of the message on the DLQ.

    USERID ( UserIdentifier|* )
    The user ID of the user who originated the message on the DLQ, as specified in the message descriptor, MQMD, of the message on the DLQ.


The action keywords

The action keywords, used to describe how a matching message is to be processed, are as follows:

    ACTION (DISCARD|IGNORE|RETRY|FWD)
    The action to be taken for any message on the DLQ that matches the pattern defined in this rule.

      DISCARD
      Delete the message from the DLQ.

      IGNORE
      Leave the message on the DLQ.

      RETRY
      If the first attempt to put the message on its destination queue fails, try again. The RETRY keyword sets the number of tries made to implement an action. The RETRYINT keyword of the control data controls the interval between attempts.

      FWD
      Forward the message to the queue named on the FWDQ keyword.

    We must specify the ACTION keyword.

    FWDQ ( QueueName|&DESTQ|&REPLYQ)
    The name of the message queue to which to forward the message when ACTION (FWD) is requested.

      QueueName
      The name of a message queue. FWDQ(' ') is not valid.

      &DESTQ
      Take the queue name from the DestQName field in the MQDLH structure.

      &REPLYQ
      Take the queue name from the ReplyToQ field in the message descriptor, MQMD.

      To avoid error messages when a rule specifying FWDQ (&REPLYQ) matches a message with a blank ReplyToQ field, specify REPLYQ (?*) in the message pattern.

    FWDQM ( QueueManagerName|&DESTQM|&REPLYQM|' ')
    The queue manager of the queue to which to forward a message.

      QueueManagerName
      The name of the queue manager of the queue to which to forward a message when ACTION (FWD) is requested.

      &DESTQM
      Take the queue manager name from the DestQMgrName field in the MQDLH structure.

      &REPLYQM
      Take the queue manager name from the ReplyToQMgr field in the message descriptor, MQMD.

      ' '
      FWDQM(' '), which is the default value, identifies the local queue manager.

    HEADER ( YES|NO)
    Whether the MQDLH should remain on a message for which ACTION (FWD) is requested. By default, the MQDLH remains on the message. The HEADER keyword is not valid for actions other than FWD.

    PUTAUT ( DEF|CTX)
    The authority with which messages should be put by the DLQ handler:

      DEF
      Put messages with the authority of the DLQ handler itself.

      CTX
      Put the messages with the authority of the user ID in the message context. If you specify PUTAUT (CTX), we must be authorized to assume the identity of other users.

    RETRY ( RetryCount|1 )
    The number of times, in the range 1 - 999,999,999, to try an action (at the interval specified on the RETRYINT keyword of the control data). The count of attempts made by the DLQ handler to implement any particular rule is specific to the current instance of the DLQ handler; the count does not persist across restarts. If the DLQ handler is restarted, the count of attempts made to apply a rule is reset to zero.


Example rule

Here is an example rule from a DLQ handler rules table: 
PERSIST(MQPER_PERSISTENT) REASON (MQRC_PUT_INHIBITED) +
ACTION (RETRY) RETRY (3)

This rule instructs the DLQ handler to make three attempts to deliver to its destination queue any persistent message that was put on the DLQ because MQPUT and MQPUT1 were inhibited.

All keywords that we can use on a rule are described in the rest of this section. Note the following:

  • The default value for a keyword, if any, is underlined. For most keywords, the default value is * (asterisk), which matches any value.
  • The vertical line (|) separates alternatives, only one of which can be specified.
  • All keywords except ACTION are optional.

Parent topic: The DLQ handler rules table