Queues

 

A WebSphere MQ queue is a named object on which applications can put messages, and from which applications can get messages. Messages are stored on a queue, so if the putting application is expecting a reply to its message, it is free to do other work while waiting for that reply. Applications access a queue by using the Message Queue Interface (MQI), described in Chapter 6, Introducing the Message Queue Interface.

Before a message can be put on a queue, the queue must have already been created. A queue is owned by a queue manager, and that queue manager can own many queues. However, each queue must have a name that is unique within that queue manager.

A queue is maintained through a queue manager. In most cases, each queue is physically managed by its queue manager but this is transparent to an application program. WebSphere MQ for z/OS shared queues can be managed by any queue manager in the queue-sharing group.

To create a queue you can use WebSphere MQ commands (MQSC), PCF commands, or platform-specific interfaces such as the WebSphere MQ for z/OS operations and control panels.

On all platforms except MQSeries for VSE/ESA, you can create local queues for temporary jobs "dynamically" from your application. For example, you can create reply-to queues (which are not needed after an application ends). For more information, see Dynamic queues.

Before using a queue, open the queue, specifying what you want to do with it. For example, you can open a queue:

  • For browsing messages only (not retrieving them)

  • For retrieving messages (and either sharing the access with other programs, or with exclusive access)

  • For putting messages on the queue

  • For inquiring about the attributes of the queue

  • For setting the attributes of the queue

For a complete list of the options you can specify when you open a queue, see the description of the MQOPEN call in WebSphere MQ Application Programming Reference.

 

Types of queue

The types of queue that WebSphere MQ supports for applications to use are:

Local and remote queues
A queue is known to a program as local if it is owned by the queue manager to which the program is connected; the queue is known as remote if it is owned by a different queue manager. The important difference between these two types of queue is that you can get messages only from local queues. (You can put messages on both types of queue.)

The queue definition object, created when you define a local queue, will hold the definition information of the queue as well as the physical messages put on the queue. The queue definition object, created when you 'define' a remote queue, will only hold the information necessary for the local queue manager to be able to locate the queue to which you want your message to go. This object is known as the local definition of a remote queue. All the attributes of the remote queue are held by the queue manager that owns it, because it is a local queue to that queue manager.

Shared queues
Shared queues are only available on WebSphere MQ for z/OS.

A shared queue is a type of local queue whose messages can be accessed by one or more queue managers that are in a queue-sharing group. (This is not the same as a queue being "shared" by more than one application, via the same queue manager.) Shared queues are held by a coupling facility (CF), and are accessible by any queue manager in the queue-sharing group. Each shared queue in a queue-sharing group must have a name that is unique within that group. See WebSphere MQ for z/OS Concepts and Planning Guide for a full discussion of shared queues and queue-sharing groups.

Alias queues
To your program, an alias queue appears to be a queue, but it is really a WebSphere MQ object that you can use to access another queue. This means that more than one program can work with the same queue, accessing it using different names.

Model and dynamic queues
A model queue is a template of a queue definition used only when you want to create a dynamic local queue.

You can create a local queue dynamically from a WebSphere MQ program, naming the model queue you wish to use as the template for the queue attributes. You may now, if you wish, change some attributes of the new queue. However, you cannot change the DefinitionType. If, for example, you require a permanent queue, select a model queue with the definition type set to permanent. Some conversational applications could make use of dynamic queues to hold replies to their queries because they probably would not need to maintain these queues after they have processed the replies.

Cluster queues
A cluster queue is a queue that is hosted by a cluster queue manager and made available to other queue managers in the cluster.

The cluster queue manager makes a local queue definition for the queue specifying the name of the cluster that the queue is to be available in. This definition has the effect of advertising the queue to the other queue managers in the cluster. The other queue managers in the cluster can put messages to a cluster queue without needing a corresponding remote-queue definition. A cluster queue can be advertised in more than one cluster. See What is a cluster? and WebSphere MQ Queue Manager Clusters for further information.

 

Types of local queue

Each queue manager can have some local queues that it uses for special purposes:

Transmission queues
A transmission queue is a local queue which holds messages destined for a remote queue. The messages are forwarded to their destination queue by WebSphere MQ when a communication program and link are available.

Initiation queues
An initiation queue is a local queue on which the queue manager puts a message for the purpose of automatically starting an application when certain conditions (such as more than 10 messages arriving, for example) are met on a local queue.

Dead-letter (undelivered message) queue
The dead-letter queue is a local queue on which the queue manager and applications put messages they cannot deliver. You should plan to process any messages that arrive on this queue.

System command queue
The system command queue is a queue to which suitably authorized applications can send WebSphere MQ commands.

System default queues
When you create a queue (other than a dynamic queue), WebSphere MQ uses the queue definitions stored in the system default queues.

Channel queues
Channel queues are used for distributed queue management.

Event queues
Event queues hold event messages. These messages are reported by the queue manager or a channel.

These special queues are described in greater detail in the following sections.

 

Attributes of queues

Some of the attributes of a queue are specified when the queue is defined, and may not be changed afterwards (for example, the type of the queue). Other attributes of queues can be grouped into those that can be changed:

  • By the queue manager during the processing of the queue (for example, the current depth of a queue)

  • Only by commands (for example, the text description of the queue)

  • By applications, using the MQSET call (for example, whether or not put operations are allowed on the queue)

You can find the values of all the attributes using the MQINQ call.

The attributes that are common to more than one type of queue are:

QName
Name of the queue

QType
Type of the queue

QDesc
Text description of the queue

InhibitGet
Whether or not programs are allowed to get messages from the queue (although you can never get messages from remote queues)

InhibitPut
Whether or not programs are allowed to put messages on the queue

DefPriority
Default priority for messages put on the queue

DefPersistence
Default persistence for messages put on the queue

Scope (not supported on z/OS or VSE/ESA)
Controls whether an entry for this queue also exists in a name service

For a full description of these attributes, see WebSphere MQ Application Programming Reference.

 

Remote queues

To a program, a queue is remote if it is owned by a different queue manager to the one to which the program is connected. Where a communication link has been established, it is possible for a program to send a message to a remote queue. A program can never get a message from a remote queue.

When opening a remote queue, to identify the queue specify either:

  • The name of the local definition that defines the remote queue.

    To create a local definition of a remote queue use the DEFINE QREMOTE command; in WebSphere MQ for iSeries, alternatively use the CRTMQMQ command; in MQSeries for Compaq NonStop Kernel, you can use the MQM screen-based interface; in MQSeries for VSE/ESA, you can use the MQMT transaction.

    From the viewpoint of an application, this is the same as opening a local queue. An application does not need to know if a queue is local or remote.

  • The name of the remote queue manager and the name of the queue as it is known to that remote queue manager.

Local definitions of remote queues have three attributes in addition to the common attributes described in Attributes of queues. These are RemoteQName (the name that the queue's owning queue manager knows it by), RemoteQMgrName (the name of the owning queue manager), and XmitQName (the name of the local transmission queue that is used when forwarding messages to other queue managers). For a fuller description of these attributes, see WebSphere MQ Application Programming Reference.

If you use the MQINQ call against the local definition of a remote queue, the queue manager returns the attributes of the local definition only, that is the remote queue name, the remote queue manager name and the transmission queue name, not the attributes of the matching local queue in the remote system.

See also Transmission queues.

 

Alias queues

An alias queue is a WebSphere MQ object that you can use to access another queue. The queue resulting from the resolution of an alias name (known as the base queue) can be a local queue, the local definition of a remote queue, or a shared queue (a type of local queue only available on WebSphere MQ for z/OS). It can also be either a predefined queue or a dynamic queue, as supported by the platform.

An alias cannot resolve to another alias.

An example of the use of alias queues is for a system administrator to give different access authorities to the base queue name (that is, the queue to which the alias resolves) and to the alias queue name. This would mean that a program or user could be authorized to use the alias queue, but not the base queue.

Alternatively, authorization can be set to inhibit put operations for the alias name, but allow them for the base queue.

In some applications, the use of alias queues means that system administrators can easily change the definition of an alias queue object without having to get the application changed.

WebSphere MQ makes authorization checks against the alias name when programs try to use that name. It does not check that the program is authorized to access the name to which the alias resolves. A program can therefore be authorized to access an alias queue name, but not the resolved queue name.

In addition to the general queue attributes described in Attributes of queues, alias queues have a BaseQName attribute. Name of the base queue to which the alias name resolves. For a fuller description of this attribute, see WebSphere MQ Application Programming Reference.

The InhibitGet and InhibitPut attributes (see Attributes of queues) of alias queues belong to the alias name. For example, if the alias-queue name ALIAS1 resolves to the base-queue name BASE, inhibitions on ALIAS1 affect ALIAS1 only and BASE is not inhibited. However, inhibitions on BASE also affect ALIAS1.

The DefPriority and DefPersistence attributes also belong to the alias name. So, for example, you can assign different default priorities to different aliases of the same base queue. Also, you can change these priorities without having to change the applications that use the aliases.

 

Model queues

A model queue is a template of a queue definition that you use when creating a dynamic queue. You specify the name of a model queue in the object descriptor (MQOD) of your MQOPEN call. Using the attributes of the model queue, the queue manager dynamically creates a local queue for you.

You can specify a name (in full) for the dynamic queue, or the stem of a name (for example, ABC) and let the queue manager add a unique part to this, or you can let the queue manager assign a complete unique name for you. If the queue manager assigns the name, it puts it in the MQOD structure.

You can not issue an MQPUT1 call directly to a model queue, but you can issue an MQPUT1 to the dynamic queue that has been created by opening a model queue.

The attributes of a model queue are a subset of those of a local queue. For a fuller description, see WebSphere MQ Application Programming Reference.

 

Dynamic queues

On all platforms except for MQSeries for VSE/ESA, when an application program issues an MQOPEN call to open a model queue, the queue manager dynamically creates an instance of a local queue with the same attributes as the model queue. Depending on the value of the DefinitionType field of the model queue, the queue manager creates either a temporary or permanent dynamic queue (See Creating dynamic queues).

 

Properties of temporary dynamic queues

Temporary dynamic queues have the following properties:

  • They cannot be shared queues, accessible from queue managers in a queue-sharing group (only available on WebSphere MQ for z/OS).

  • They hold nonpersistent messages only.

  • They are non-recoverable.

  • They are deleted when the queue manager is started.

  • They are deleted when the application that issued the MQOPEN call which resulted in the creation of the queue closes the queue or terminates.

    • If there are any committed messages on the queue, they will be deleted.

    • If there are any uncommitted MQGET, MQPUT, or MQPUT1 calls outstanding against the queue at this time, the queue is marked as being logically deleted, and is only physically deleted (after these calls have been committed) as part of close processing, or when the application terminates.

    • If the queue happens to be in use at this time (by the creating, or another application), the queue is marked as being logically deleted, and is only physically deleted when closed by the last application using the queue.

    • Attempts to access a logically deleted queue (other than to close it) fail with reason code MQRC_Q_DELETED.

    • MQCO_NONE, MQCO_DELETE and MQCO_DELETE_PURGE are all treated as MQCO_NONE when specified on an MQCLOSE call for the corresponding MQOPEN call that created the queue.

 

Properties of permanent dynamic queues

Permanent dynamic queues have the following properties:

  • They hold persistent or nonpersistent messages.

  • They are recoverable in the event of system failures.

  • They are deleted when an application (not necessarily the one that issued the MQOPEN call which resulted in the creation of the queue) successfully closes the queue using the MQCO_DELETE, or the MQCO_DELETE_PURGE option.

    • A close request with the MQCO_DELETE option fails if there are any messages (committed or uncommitted) still on the queue. A close request with the MQCO_DELETE_PURGE option succeeds even if there are committed messages on the queue (the messages being deleted as part of the close), but fails if there are any uncommitted MQGET, MQPUT, or MQPUT1 calls outstanding against the queue.

    • If the delete request is successful, but the queue happens to be in use (by the creating, or another application), the queue is marked as being logically deleted and is only physically deleted when closed by the last application using the queue.

  • They are not deleted if closed by an application which is not authorized to delete the queue, unless the closing application issued the MQOPEN call which caused the creation of the queue. Authorization checks are performed against the user identifier (or alternate user identifier if MQOO_ALTERNATE_USER_AUTHORITY was specified) which was used to validate the corresponding MQOPEN call.

  • They can be deleted in the same way as a normal queue.

 

Uses of dynamic queues

You can use dynamic queues for:

  • Applications that do not require queues to be retained after the application has terminated.

  • Applications that require replies to messages to be processed by another application can dynamically create a reply-to queue by opening a model queue. For example, a client application could:

    1. Create a dynamic queue.

    2. Supply its name in the ReplyToQ field of the message descriptor structure of the request message.

    3. Place the request on a queue being processed by a server.

The server could then place the reply message on the reply-to queue. Finally, the client could process the reply, and close the reply-to queue with the delete option.

 

Recommendations for uses of dynamic queues

You should consider the following points when using dynamic queues:

  • In a client-server model, each client should create and use its own dynamic reply-to queue. If a dynamic reply-to queue is shared between more than one client, the deletion of the reply-to queue may be delayed because there is uncommitted activity outstanding against the queue, or because the queue is in use by another client. Additionally, the queue might be marked as being logically deleted, and hence inaccessible for subsequent API requests (other than MQCLOSE).

  • If your application environment requires that dynamic queues must be shared between applications, ensure that the queue is only closed (with the delete option) when all activity against the queue has been committed. This should be by the last user preferably. This ensures that deletion of the queue is not delayed, and should minimize the period that the queue is inaccessible because it has been marked as being logically deleted.

 

Transmission queues

When an application sends a message to a remote queue, the local queue manager stores the message in a special local queue, called a transmission queue.

A message channel agent (channel program), or intra-group queuing agent when using intra-group queuing on WebSphere MQ for z/OS, will be associated with the transmission queue and the remote queue manager, and this delivers the message. When the message has been delivered, it is deleted from the transmission queue.

The message may have to pass through many queue managers (or nodes) on its journey to its final destination. There must be a transmission queue defined at each queue manager along the route, each holding messages waiting to be transmitted to the next node. (A shared transmission queue is used when using intra-group queuing on WebSphere MQ for z/OS.) There can be several transmission queues defined at a particular queue manager. A given transmission queue holds messages whose next destination is the same queue manager, although the messages may have different eventual destinations. There may also be several transmission queues for the same remote queue manager, with each one being used for a different type of service, for example.

Transmission queues can be used to trigger a message channel agent to send messages onward. For information about this, see Chapter 14, Starting WebSphere MQ applications using triggers. These attributes are defined in the transmission queue definition (for triggered channels) or the process definition object (see Process definitions).

 

Initiation queues

An initiation queue is a local queue on which the queue manager puts a trigger message when a trigger event occurs on an application queue. A trigger event is an event (for example, more than 10 messages arriving) that an application designer intends the queue manager to use as a cue, or trigger, to start a program that will process the queue. For more information on how triggering works, see Chapter 14, Starting WebSphere MQ applications using triggers.

 

Dead-letter (undelivered message) queues

A dead-letter (undelivered message) queue is a local queue on which the queue manager puts messages it cannot deliver.

When the queue manager puts a message on the dead-letter queue, it adds a header to the message. This includes such information as the intended destination of the original message, the reason the queue manager put the message on the dead-letter queue, and the date and time it did this.

Applications can also use the queue for messages they cannot deliver. For more information, see Using the dead-letter (undelivered message) queue.

 

System command queues

Not supported in MQSeries for VSE/ESA.

These queues receive the PCF, MQSC, and CL commands, as supported on your platform, in readiness for the queue manager to action them. In WebSphere MQ for z/OS the queue is known as the SYSTEM.COMMAND.INPUT.QUEUE and accepts MQSC commands. On other platforms it is known as the SYSTEM.ADMIN.COMMAND.QUEUE and the commands accepted vary by platform.

 

System default queues

The system default queues contain the initial definitions of the queues for your system. When you create a new queue, the queue manager copies the definition from the appropriate system default queue.

 

WebSphere is a trademark of the IBM Corporation in the United States, other countries, or both.

 

IBM is a trademark of the IBM Corporation in the United States, other countries, or both.