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 you 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).
- All keywords except ACTION are optional.
- 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. You can specify only
one of these.
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.
You can use symbolic names. For example, you 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, you 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.
You can use symbolic
names. For example, you 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.)
You can
use symbolic names. For example, you 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.
You can use symbolic names. For example, you 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, you 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. You 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.