dead-letter queue handler utility (CSQUDLQH), CSQUDLQH (dead-letter queue handler utility), actions, APPLIDAT keyword, DLQ handler, APPLNAME keyword, APPLTYPE keyword, DESTQ keyword, DESTQM keyword, FEEDBACK keyword, FORMAT keyword, MSGTYPE keyword, PERSIST keyword, REASON keyword, REPLYQ keyword, REPLYQM keyword, USERID keyword, ACTION keyword, FWDQ keyword, FWDQM keyword, HEADER keyword, PUTAUT keyword, RETRY keyword" /> Rules (patterns and actions)

 

Rules (patterns and actions)

Figure 81 shows an example rule from a DLQ handler rules table.

Figure 81. An example rule from a DLQ handler rules table. 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. 

 PERSIST(MQPER_PERSISTENT) REASON (MQRC_PUT_INHIBITED) +
  ACTION (RETRY) RETRY (3)

This section describes the keywords that we can include in a rules table. It begins with a description of the pattern-matching keywords (those against which messages on the DLQ are matched). It then describes the action keywords (those that determine how the DLQ handler is to process a matching message).

 

The pattern-matching keywords

The pattern-matching keywords, are described below. You use these to specify values against which messages on the DLQ are matched. All pattern-matching keywords are optional.

APPLIDAT (ApplIdentityData|*)

The ApplIdentityData value of the message on the DLQ, specified in the message descriptor, MQMD.

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 queue manager name for the message queue for which the message is destined.

FEEDBACK (Feedback|*)

Describes the nature of the report when the MsgType value is MQMT_REPORT.

We can use symbolic names. For example, we can use the symbolic name MQFB_COA to identify those messages on the DLQ that require confirmation of their arrival on their destination queues. A few symbolic names are not accepted by the utility and lead to a syntax error. In these cases, we can use the corresponding numeric value.

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 require 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 those 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. A few symbolic names are not accepted by the utility and lead to a syntax error. In these cases, we can use the corresponding numeric value.

REPLYQ (QueueName|*)

The reply-to queue name specified in the message descriptor, MQMD, of the message on the DLQ.

REPLYQM (QueueManagerName|*)

The queue manager name of the reply-to queue specified in the REPLYQ keyword.

USERID (UserIdentifier|*)

The user ID of the user who originated the message on the DLQ, as specified in the message descriptor, MQMD.

 

The action keywords

The action keywords are described below. You use these to describe how a matching message is processed.

ACTION

(DISCARD|IGNORE|RETRY|FWD)

The action taken for any message on the DLQ that matches the pattern defined in this rule.

DISCARD

Causes the message to be deleted from the DLQ.

IGNORE

Causes the message to be left on the DLQ.

RETRY

Causes the DLQ handler to try again to put the message on its destination queue.

FWD

Causes the DLQ handler to forward the message to the queue named on the FWDQ keyword.

You must specify the ACTION keyword. The number of attempts made to implement an action is governed by the RETRY keyword. The RETRYINT keyword of the control data controls the interval between attempts.

FWDQ (QueueName|&DESTQ|&REPLYQ)

The name of the message queue to which the message is forwarded when you select the ACTION keyword.

QueueName

This parameter is the name of a message queue. FWDQ(' ') is not valid.

&DESTQ

Takes the queue name from the DestQName field in the MQDLH structure.

&REPLYQ

Takes the name from the ReplyToQ field in the message descriptor, MQMD. We can specify REPLYQ (?*) in the message pattern to avoid error messages, when a rule specifying FWDQ (&REPLYQ), matches a message with a blank ReplyToQ field.

FWDQM (QueueManagerName|&DESTQM|&REPLYQM|' ')

The queue manager of the queue to which a message is forwarded.

QueueManagerName

This parameter defines the queue manager name for the queue to which the message is forwarded when you select the ACTION (FWD) keyword.

&DESTQM

Takes the queue manager name from the DestQMgrName field in the MQDLH structure.

&REPLYQM

Takes the name from the ReplyToQMgr field in the message descriptor, MQMD.

' '

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

Puts messages with the authority of the DLQ handler itself.

CTX

Causes the messages to be put with the authority of the user ID in the message context. You must be authorized to assume the identity of other users, if you specify PUTAUT (CTX).

RETRY (RetryCount|1)

The number of times that an action should be attempted (at the interval specified on the RETRYINT keyword of the control data). Specify a value in the range 1 through 999 999 999.
Note:
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 you restart the DLQ handler, the count of attempts made to apply a rule is reset to zero.