Working with local queues on IBM i

This section contains examples of some of the commands that you can use to manage local queues. All the commands shown are also available using options from the WRKMQMQ command panel.

Defining a local queue

For an application, the local queue manager is the queue manager to which the application is connected. Queues that are managed by the local queue manager are said to be local to that queue manager.

Use the command CRTMQMQ QTYPE *LCL to create a definition of a local queue and also to create the data structure that is called a queue. You can also modify the queue characteristics from those of the default local queue.

In this example, the queue we define, orange.local.queue, is specified to have these characteristics:

It is enabled for gets, disabled for puts, and operates on a first-in-first-out (FIFO) basis.
It is an ordinary queue, that is, it is not an initiation queue or a transmission queue, and it does not generate trigger messages.
The maximum queue depth is 1000 messages; the maximum message length is 2000 bytes.

The following command does this on the default queue manager:

CRTMQMQ QNAME('orange.local.queue') QTYPE(*LCL)
TEXT('Queue for messages from other systems')
PUTENBL(*NO)
GETENBL(*YES)
TRGENBL(*NO)
MSGDLYSEQ(*FIFO)
MAXDEPTH(1000)
MAXMSGLEN(2000)
USAGE(*NORMAL)

Note:

USAGE *NORMAL indicates that this queue is not a transmission queue.
If you already have a local queue with the name orange.local.queue on the same queue manager, then this command fails. Use the REPLACE *YES attribute if you want to overwrite the existing definition of a queue, but see also Changing local queue attributes.

Defining a dead-letter queue

Each queue manager must have a local queue to be used as a dead-letter queue so that messages that cannot be delivered to their correct destination can be stored for later retrieval. You must explicitly tell the queue manager about the dead-letter queue. You can do this by specifying a dead-letter queue on the CRTMQM command, or you can use the CHGMQM command to specify one later. You must also define the dead-letter queue before it can be used.

A sample dead-letter queue called SYSTEM.DEAD.LETTER.QUEUE is supplied with the product. This queue is automatically created when you create the queue manager. You can modify this definition if required. There is no need to rename it, although you can if you like.

A dead-letter queue has no special requirements except that:

It must be a local queue.
Its MAXMSGL (maximum message length) attribute must enable the queue to accommodate the largest messages that the queue manager has to handle plus the size of the dead-letter header (MQDLH).

IBM® MQ provides a dead-letter queue handler that allows you to specify how messages found on a dead-letter queue are to be processed or removed. For further information, see The dead-letter queue handler on IBM i.

Displaying default object attributes

When you define an IBM MQ object, it takes any attributes that you do not specify from the default object. For example, when you define a local queue, the queue inherits any attributes that you omit in the definition from the default local queue, which is called SYSTEM.DEFAULT.LOCAL.QUEUE. To see exactly what these attributes are, use the following command:

DSPMQMQ QNAME(SYSTEM.DEFAULT.LOCAL.QUEUE) MQMNAME(MYQUEUEMANAGER)

Copying a local queue definition

You can copy a queue definition using the CPYMQMQ command. For example:

CPYMQMQ FROMQ('orange.local.queue') TOQ('magenta.queue') MQMNAME(MYQUEUEMANAGER)

This command creates a queue with the same attributes as our original queue orange.local.queue, rather than those of the system default local queue.

You can also use the CPYMQMQ command to copy a queue definition, but substituting one or more changes to the attributes of the original. For example:

CPYMQMQ FROMQ('orange.local.queue') TOQ('third.queue') MQMNAME(MYQUEUEMANAGER)
MAXMSGLEN(1024)

This command copies the attributes of the queue orange.local.queue to the queue third.queue, but specifies that the maximum message length on the new queue is to be 1024 bytes, rather than 2000.

Note: When you use the CPYMQMQ command, you copy the queue attributes only, not the messages on the queue.

Changing local queue attributes

You can change queue attributes in two ways, using either the CHGMQMQ command or the CPYMQMQ command with the REPLACE *YES attribute. In Defining a local queue, you defined the queue orange.local.queue. If, for example, you need to increase the maximum message length on this queue to 10,000 bytes.

Using the CHGMQMQ command:
```
CHGMQMQ QNAME('orange.local.queue') MQMNAME(MYQUEUEMANAGER) MAXMSGLEN(10000)
```
This command changes a single attribute, that of the maximum message length; all the other attributes remain the same.
Using the CRTMQMQ command with the REPLACE *YES option, for example:
```
CRTMQMQ QNAME('orange.local.queue') QTYPE(*LCL) MQMNAME(MYQUEUEMANAGER)
MAXMSGLEN(10000) REPLACE(*YES)
```
This command changes not only the maximum message length, but all the other attributes, which are given their default values. The queue is now put enabled whereas previously it was put inhibited. Put enabled is the default, as specified by the queue SYSTEM.DEFAULT.LOCAL.QUEUE, unless you have changed it.

If you decrease the maximum message length on an existing queue, existing messages are not affected. Any new messages, however, must meet the new criteria.

Clearing a local queue

To delete all the messages from a local queue called magenta.queue, use the following command:

CLRMQMQ QNAME('magenta.queue') MQMNAME(MYQUEUEMANAGER)

You cannot clear a queue if:

There are uncommitted messages that have been put on the queue under syncpoint.
An application currently has the queue open.

Deleting a local queue

Use the command DLTMQMQ to delete a local queue.

A queue cannot be deleted if it has uncommitted messages on it, or if it is in use.

Enabling large queues

IBM MQ supports queues larger than 2 GB. See your operating system documentation for information on how to enable IBM i to support large files.

The IBM i product information can be found in IBM Documentation.

Some utilities might not be able to cope with files greater than 2 GB. Before enabling large file support, check your operating system documentation for information on restrictions on such support.