The DLQ handler rules table

 

Overview

The DLQ handler rules table defines how the DLQ handler is to process messages that arrive on the DLQ. There are two types of entry in a rules table:

  • The first entry in the table, which is optional, contains control data.

  • All other entries in the table are rules for the DLQ handler to follow. Each rule consists of a pattern (a set of message characteristics) that a message is matched against, and an action to be taken when a message on the DLQ matches the specified pattern. There must be at least one rule in a rules table.

Each entry in the rules table comprises one or more keywords.

 

Control data

INPUTQ (QueueName|' ')
The name of the DLQ you want to process:

  1. Any INPUTQ value you supply as a parameter to the runmqdlq command overrides any INPUTQ value in the rules table.

  2. If you do not specify an INPUTQ value as a parameter to the runmqdlq command, but you do specify a value in the rules table, the INPUTQ value in the rules table is used.

  3. If no DLQ is specified or you specify INPUTQ(' ') in the rules table, the name of the DLQ belonging to the queue manager whose name is supplied as a parameter to the runmqdlq command is used.

  4. If you do not specify an INPUTQ value as a parameter to the runmqdlq command or as a value in the rules table, the DLQ belonging to the queue manager named on the INPUTQM keyword in the rules table is used.

INPUTQM (QueueManagerName|' ')
The name of the queue manager that owns the DLQ named on the INPUTQ keyword:

  1. Any INPUTQM value you supply as a parameter to the runmqdlq command overrides any INPUTQM value in the rules table.

  2. If you do not specify an INPUTQM value as a parameter to the runmqdlq command, the INPUTQM value in the rules table is used.

  3. If no queue manager is specified or you specify INPUTQM(' ') in the rules table, the default queue manager for the installation is used.

RETRYINT (Interval|60)
The interval, in seconds, at which the DLQ handler should reprocess messages on the DLQ that could not be processed at the first attempt, and for which repeated attempts have been requested. By default, the retry interval is 60 seconds.

WAIT (YES|NO|nnn)
Whether the DLQ handler should wait for further messages to arrive on the DLQ when it detects that there are no further messages that it can process.

YES
The DLQ handler waits indefinitely.

NO
The DLQ handler ends when it detects that the DLQ is either empty or contains no messages that it can process.

nnn
The DLQ handler waits for nnn seconds for new work to arrive before ending, after it detects that the queue is either empty or contains no messages that it can process.

Specify WAIT (YES) for busy DLQs, and WAIT (NO) or WAIT (nnn) for DLQs that have a low level of activity. If the DLQ handler is allowed to terminate, invoke it again using triggering.

An alternative to including control data in the rules table is to supply the names of the DLQ and its queue manager as input parameters to the runmqdlq command. If you specify a value both in the rules table and as input to the runmqdlq command, the value specified on the runmqdlq command takes precedence.

If you include a control-data entry in the rules table, it must be the first entry in the table.

 

Rules (patterns and actions)

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 you 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.

This section begins with a description of the pattern-matching keywords (those against which messages on the DLQ are matched), and 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, which you use to specify values against which messages on the DLQ are matched, are described below. 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.

You can use symbolic names. For example, you 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.

You can use symbolic names. For example, you 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.)

You can use symbolic names. For example, you 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.

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.

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.

 

The action keywords

The action keywords, used to describe how a matching message is to be processed, are described below.

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.

You 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 Destqueue_manager 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), 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.

 

Rules table conventions

The rules table must adhere to the following conventions regarding its syntax, structure, and contents:

  • A rules table must contain at least one rule.

  • Keywords can occur in any order.

  • A keyword can be included only once in any rule.

  • Keywords are not case-sensitive.

  • A keyword and its parameter value must be separated from other keywords by at least one blank or comma.

  • There can be any number of blanks at the beginning or end of a rule, and between keywords, punctuation, and values.

  • Each rule must begin on a new line.

  • For reasons of portability, the significant length of a line must not be greater than 72 characters.

  • Use the plus sign (+) as the last nonblank character on a line to indicate that the rule continues from the first nonblank character in the next line. Use the minus sign (-) as the last nonblank character on a line to indicate that the rule continues from the start of the next line. Continuation characters can occur within keywords and parameters.

    For example: 

    APPLNAME('ABC+
  D')

    results in 'ABCD', and 

    APPLNAME('ABC-
  D')

    results in 'ABC D'.

  • Comment lines, which begin with an asterisk (*), can occur anywhere in the rules table.

  • Blank lines are ignored.

  • Each entry in the DLQ handler rules table comprises one or more keywords and their associated parameters. The parameters must follow these syntax rules:

    • Each parameter value must include at least one significant character. The delimiting quotation marks in quoted values are not considered significant. For example, these parameters are valid:

      FORMAT('ABC') 3 significant characters
      FORMAT(ABC) 3 significant characters
      FORMAT('A') 1 significant character
      FORMAT(A) 1 significant character
      FORMAT(' ') 1 significant character

      These parameters are invalid because they contain no significant characters:

      FORMAT('')
      FORMAT( )
      FORMAT()
      FORMAT

    • Wildcard characters are supported. You can use the question mark (?) instead of any single character, except a trailing blank; you can use the asterisk (*) instead of zero or more adjacent characters. The asterisk (*) and the question mark (?) are always interpreted as wildcard characters in parameter values.

    • Wildcard characters cannot be included in the parameters of these keywords: ACTION, HEADER, RETRY, FWDQ, FWDQM, and PUTAUT.

    • Trailing blanks in parameter values, and in the corresponding fields in the message on the DLQ, are not significant when performing wildcard matches. However, leading and embedded blanks within strings in quotation marks are significant to wildcard matches.

    • Numeric parameters cannot include the question mark (?) wildcard character. You can use the asterisk (*) instead of an entire numeric parameter, but not as part of a numeric parameter. For example, these are valid numeric parameters:

      MSGTYPE(2) Only reply messages are eligible
      MSGTYPE(*) Any message type is eligible
      MSGTYPE('*') Any message type is eligible

      However, MSGTYPE('2*') is not valid, because it includes an asterisk (*) as part of a numeric parameter.

    • Numeric parameters must be in the range 0-999 999 999. If the parameter value is in this range, it is accepted, even if it is not currently valid in the field to which the keyword relates. You can use symbolic names for numeric parameters.

    • If a string value is shorter than the field in the MQDLH or MQMD to which the keyword relates, the value is padded with blanks to the length of the field. If the value, excluding asterisks, is longer than the field, an error is diagnosed. For example, these are all valid string values for an 8 character field:

      'ABCDEFGH' 8 characters
      'A*C*E*G*I' 5 characters excluding asterisks
      '*A*C*E*G*I*K*M*O*' 8 characters excluding asterisks

    • Enclose strings that contain blanks, lowercase characters, or special characters other than period (.), forward slash (/), underscore (_), and percent sign (%) in single quotation marks. Lowercase characters not enclosed in quotation marks are folded to uppercase. If the string includes a quotation, use two single quotation marks to denote both the beginning and the end of the quotation. When the length of the string is calculated, each occurrence of double quotation marks is counted as a single character.