runmqdlq (run dead-letter queue handler)

Use the runmqdlq command to start the dead-letter queue (DLQ) handler, which monitors and handles messages on a DLQ.

Before IBM® MQ 9.3.0, this command is used on servers. If you want client mode you should compile amqsdlq in client mode. See The sample DLQ handler amqsdlq for more information.

From IBM MQ 9.3.0, you can use runmqdlq with the -c parameter to specify that it should connect to a queue manager by using a client connection.

Syntax

Description

Use the dead-letter queue handler to perform various actions on selected messages by specifying a set of rules that can both select a message and define the action to be performed on that message.

The runmqdlq command takes its input from stdin. When the command is processed, the results and a summary are put into a report that is sent to stdout.

By taking stdin from the keyboard, you can enter runmqdlq rules interactively.

By redirecting the input from a file, you can apply a rules table to the specified queue. The rules table must contain at least one rule.

If you use the DLQ handler without redirecting stdin from a file (the rules table), the DLQ handler reads its input from the keyboard:

On AIX® and Linux®, the DLQ handler does not start to process the named queue until it receives an end_of_file (Ctrl+D) character.
On Windows, the DLQ handler does not start to process the named queue until you press the following sequence of keys: Ctrl+Z, Enter, Ctrl+Z, Enter.

For more information about rules tables and how to construct them, see The DLQ handler rules table.

Optional parameters

The MQSC command rules for comment lines and for joining lines also apply to the DLQ handler input parameters.

QName

The name of the queue to be processed.

If you omit the name, the dead-letter queue defined for the local queue manager is used. If you enter one or more blanks (' '), the dead-letter queue of the local queue manager is explicitly assigned.

QMgrName

The name of the queue manager that owns the queue to be processed.

If you omit the name, the default queue manager for the installation is used. If you enter one or more blanks (' '), the default queue manager for this installation is explicitly assigned.

-u UserID

If you use the -u parameter to supply a user ID, you are prompted for a matching password.

If you have configured the CONNAUTH AUTHINFO record with CHCKLOCL(REQUIRED) or CHCKLOCL(REQDADM), you must use the -u parameter otherwise you will not be able to start a dead-letter queue handler for your queue manager with runmqdlq.

If you specify this parameter and redirect stdin, a prompt will not be displayed and the first line of redirected input should contain the password.

-c

Modifies the runmqdlq command to connect to a queue manager by using a client connection. The client channel definitions used to connect to the queue manager are located using the following environment variables in this order of precedence: MQSERVER, MQCHLLIB , and MQCHLTAB .

This option requires the client to be installed. If it is not installed an error message reporting the missing client libraries is issued.

Attention: From IBM MQ 9.4.0, the default permissions of runmqdlq have been changed to remove the setuid bit. When running runmqdlq, the tool runs under the context of the user that invokes the command.

Before IBM MQ 9.4.0, runmqdlq is a setuid application that runs as the 'mqm' user regardless of which user started the application. If you use a CCDT file, the 'mqm' group must have permission to read the CCDT file as well as 'execute' permission on the directory structure. Failure to grant the correct permissions results in runmqdlq failing with an AMQ9516 error.

Return codes

Table 1. Return code identifiers and descriptions
Return code	Description
0	Successful operation
16	Usage / Invalid arguments provided
32	Warning
64	Expected error
95	Unexpected error
151	Unable to load Libraries