System Administration Guide

Working with local queues

This section contains examples of some MQSC commands that you can use to manage local, model, and alias queues. See the WebSphere MQ Script (MQSC) Command Reference for detailed information about these commands.

Defining a local queue

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

Use the MQSC command DEFINE QLOCAL to create a local queue. You can also use the default defined in the default local queue definition, or you can modify the queue characteristics from those of the default local queue.

Note:

The default local queue is named SYSTEM.LOCAL.DEFAULT.QUEUE and it was created on system installation.

Using the MQSC command shown below, we define a queue called ORANGE.LOCAL.QUEUE, with the following characteristics:

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

DEFINE QLOCAL (ORANGE.LOCAL.QUEUE) +
       DESCR('Queue for messages from other systems') +
       PUT (DISABLED) +
       GET (ENABLED) +
       NOTRIGGER +
       MSGDLVSQ (FIFO) +
       MAXDEPTH (1000) +
       MAXMSGL (2000) +
       USAGE (NORMAL);

Notes:

Most of these attributes are the defaults as supplied with the product. We have shown them here for purposes of illustration. You can omit them if you are sure that the defaults are what you want or have not been changed. See also Displaying default object attributes.
USAGE (NORMAL) indicates that this queue is not a transmission queue.
If you already have a local queue on the same queue manager with the name ORANGE.LOCAL.QUEUE, this command fails. Use the REPLACE attribute if you want to overwrite the existing definition of a queue, but see also Changing local queue attributes.

Defining a dead-letter queue

We recommend that each queue manager has 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 tell the queue manager about the dead-letter queue. You do this by specifying a dead-letter queue name on the crtmqm command (crtmqm -u DEAD.LETTER.QUEUE, for example), or by using the DEADQ attribute on the ALTER QMGR command to specify one later. You must define the dead-letter queue before using it.

We supply a sample dead-letter queue called SYSTEM.DEAD.LETTER.QUEUE with the product. This queue is automatically created when you create the queue manager. You can modify this definition if required, and rename it.

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)

WebSphere 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 Chapter 12, The WebSphere MQ dead-letter queue handler.

Displaying default object attributes

When you define a WebSphere 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:

DISPLAY QUEUE (SYSTEM.DEFAULT.LOCAL.QUEUE)

The syntax of this command is different from that of the corresponding DEFINE command. On the DISPLAY command you can give just the queue name, whereas on the DEFINE command you have to specify the type of the queue, that is, QLOCAL, QALIAS, QMODEL, or QREMOTE.

You can selectively display attributes by specifying them individually. For example:

DISPLAY QUEUE (ORANGE.LOCAL.QUEUE) +
        MAXDEPTH +
        MAXMSGL +
        CURDEPTH;

This command displays the three specified attributes as follows:

AMQ8409: Display Queue details.
   QUEUE(ORANGE.LOCAL.QUEUE)               MAXDEPTH(5000)
   MAXMSGL(4194304)                        CURDEPTH(0)
     5 : end

CURDEPTH is the current queue depth, that is, the number of messages on the queue. This is a useful attribute to display, because by monitoring the queue depth you can ensure that the queue does not become full.

Copying a local queue definition

You can copy a queue definition using the LIKE attribute on the DEFINE command. For example:

DEFINE QLOCAL (MAGENTA.QUEUE) +
       LIKE (ORANGE.LOCAL.QUEUE)

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. Enter the name of the queue to be copied exactly as it was entered when you created the queue. If the name contains lower case characters, enclose the name in single quotation marks.

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

DEFINE QLOCAL (THIRD.QUEUE) +
       LIKE (ORANGE.LOCAL.QUEUE) +
       MAXMSGL(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.

Notes:

When you use the LIKE attribute on a DEFINE command, you are copying the queue attributes only. You are not copying the messages on the queue.
If you a define a local queue, without specifying LIKE, it is the same as DEFINE LIKE(SYSTEM.DEFAULT.LOCAL.QUEUE).

Changing local queue attributes

You can change queue attributes in two ways, using either the ALTER QLOCAL command or the DEFINE QLOCAL command with the REPLACE attribute. In Defining a local queue, we defined the queue called ORANGE.LOCAL.QUEUE. Suppose, for example, you want to increase the maximum message length on this queue to 10 000 bytes.

Using the ALTER command:
```
ALTER QLOCAL (ORANGE.LOCAL.QUEUE) MAXMSGL(10000)
```
This command changes a single attribute, that of the maximum message length; all the other attributes remain the same.
Using the DEFINE command with the REPLACE option, for example:
```
DEFINE QLOCAL (ORANGE.LOCAL.QUEUE) MAXMSGL(10000) REPLACE
```
This command changes not only the maximum message length, but also 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.
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:

CLEAR QLOCAL (MAGENTA.QUEUE)

Note:

There is no prompt that enables you to change your mind; once you press the Enter key the messages are lost.

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 MQSC command DELETE QLOCAL to delete a local queue. A queue cannot be deleted if it has uncommitted messages on it. However, if the queue has one or more committed messages and no uncommitted messages, it can be deleted only if you specify the PURGE option. For example:

DELETE QLOCAL (PINK.QUEUE) PURGE

Specifying NOPURGE instead of PURGE ensures that the queue is not deleted if it contains any committed messages.

Browsing queues

WebSphere MQ provides a sample queue browser that you can use to look at the contents of the messages on a queue. The browser is supplied in both source and executable formats.

In WebSphere MQ for Windows, the default file names and paths are:

Source: c:\Program Files\IBM\WebSphere MQ\tools\c\samples\
Executable: c:\Program files\IBM\WebSphere MQ\tools\c\samples\bin\amqsbcg.exe

In MQSeries for UNIX systems, the default file names and paths are:

Source: /opt/mqm/samp/amqsbcg0.c (/usr/mqm/samp/amqsbcg0.c on AIX)
Executable: /opt/mqm/samp/bin/amqsbcg (/usr/mqm/samp/bin/amqsbcg on AIX)

The sample requires two input parameters, the queue name and the queue manager name. For example:

amqsbcg SYSTEM.ADMIN.QMGREVENT.tpp01 saturn.queue.manager

Typical results from this command are shown in Figure 6.

Figure 6. Typical results from queue browser

AMQSBCG0 - starts here
**********************
 
 MQOPEN - 'SYSTEM.ADMIN.QMGR.EVENT'
 
 
 MQGET of message number 1
****Message descriptor****
 
  StrucId  : 'MD  '  Version : 2
  Report   : 0  MsgType : 8
  Expiry   : -1  Feedback : 0
  Encoding : 546  CodedCharSetId : 850
  Format : 'MQEVENT '
  Priority : 0  Persistence : 0
  MsgId : X'414D512073617475726E2E71756575650005D30033563DB8'
  CorrelId : X'000000000000000000000000000000000000000000000000'
  BackoutCount : 0
  ReplyToQ       : '                                                '
  ReplyToQMgr    : 'saturn.queue.manager                            '
  ** Identity Context
  UserIdentifier : '            '
  AccountingToken :
   X'0000000000000000000000000000000000000000000000000000000000000000'
  ApplIdentityData : '                                '
  ** Origin Context
  PutApplType    : '7'
  PutApplName    : 'saturn.queue.manager        '
  PutDate  : '19970417'    PutTime  : '15115208'
  ApplOriginData : '    '
 
  GroupId : X'000000000000000000000000000000000000000000000000'
  MsgSeqNumber   : '1'
  Offset         : '0'
  MsgFlags       : '0'
  OriginalLength : '104'
 
****   Message      ****
 
 length - 104 bytes
 
00000000:  0700 0000 2400 0000 0100 0000 2C00 0000 '....>.......,...'
00000010:  0100 0000 0100 0000 0100 0000 AE08 0000 '................'
00000020:  0100 0000 0400 0000 4400 0000 DF07 0000 '........D.......'
00000030:  0000 0000 3000 0000 7361 7475 726E 2E71 '....0...saturn.q'
00000040:  7565 7565 2E6D 616E 6167 6572 2020 2020 'ueue.manager    '
00000050:  2020 2020 2020 2020 2020 2020 2020 2020 '                '
00000060:  2020 2020 2020 2020                     '                '
  
 No more messages
 MQCLOSE
 MQDISC

Monitoring local queues with the Windows Performance Monitor

Administrators of WebSphere MQ for Windows can monitor the performance of local queues using the Windows Performance Monitor.

The Performance Monitor displays a new object type called WebSphere MQ Queues in which performance data for local queues is stored.

Active local queues defined in running queue managers are displayed as QueueName:QMName in the Performance Monitor Instance list when you select the WebSphere MQ Queues object type. QMName denotes the name of the queue manager owning the queue, and QueueName denotes the name of the local queue.

For each queue, you can view information relating to the following:

The current queue depth
The queue depth as a percentage of the maximum queue depth
The number of messages being placed on the queue each second
The number of messages being removed from the queue each second

For messages sent to a distribution list, the Performance Monitor counts the number of messages being put onto each queue.

In the case of segmented messages, the Performance Monitor counts the appropriate number of small messages.

Performance data is obtained from statistical data maintained by the WebSphere MQqueue managers for each local queue. However, performance data is available only for queues that are accessed after the Performance Monitor has started.

You can monitor the performance of queues on computers other than that on which the Performance Monitor is running, by selecting your target computer from the Performance Monitor, which works using the Windows^(R) Network Neighborhood hierarchy.

Enabling large queues

WebSphere MQ Version 5.3 supports queues larger than 2 GB. On Windows systems, support for large files is available without any additional enablement. On AIX, HP-UX, and Solaris systems, you need to explicitly enable large file support before you can create queue files larger than 2 GB. See your operating system documentation for information on how to do this.

Some utilities, such as tar, cannot cope with files greater than 2 GB. Before enabling large file support, check your operating system documentation for information on restrictions on such support.