Queues

Queue managers manage queues and provide programming interface access to the queues. The queues are not directly visible to an application and all interactions with the queues take place through queue managers. Each queue manager can have queues that it manages and owns. These queues are known as local queues. WebSphere MQ Everyplace also allows applications to access messages on queues that belong to another queue manager. These queues are known as remote queues. The same sets of operations are available on both local and remote queues, with the exception of defining message listeners (see Message listeners).

The messages on the queues are held in the queue's persistent store (see Storing messages). The backing store used by a queue can be changed using an WebSphere MQ Everyplace administration message. Changing the backing store is not allowed while the queue is active or contains messages. If the backing store used by the queue allows the messages to be recovered in the event of a system failure, then this allows WebSphere MQ Everyplace to assure the delivery of messages.

Queue names

WebSphere MQ Everyplace queue names can contain the following characters:

Queue names cannot have a leading or trailing '.' character.

There are no inherent name length limitations in WebSphere MQ Everyplace.

For additional naming recommendations when interacting with WebSphere MQ networks, see Naming recommendations for inter-operability with a WebSphere MQ network.

Queue types

The WebSphere MQ Everyplace queue types are described briefly in WebSphere MQ Everyplace queues, and information on setting up and administering the various types is provided in Queues.

Queue ordering

The order of messages on a queue is primarily determined by their priority. Message priority ranges from 9 (highest) to 0 (lowest). Messages with the same priority value are ordered by the time at which they arrive on the queue, with messages that have been on the queue for the longest, being at the head of the priority group.

Reading all the messages on a queue

When a queue is empty, the queue returns Return Code 121 - MQERETURN_J_Q_NO_MATCHING_MSG if a get message command is issued. This allows you to create an application that reads all the available messages on a queue.

Browse and Lock

Browsing a group of messages and locking them allows an application to assure that no other application is able to process the messages while they are locked. The messages remain locked until they are unlocked by the application. No other application can unlock the messages. The example program Example 5 contains an example of browsing messages with lock.

This command locks all the messages on the local queue SYSTEM.DEFAULT.QUEUE.NAME. These messages can now only be accessed by the application that locked them. (Any messages arriving on the queue after the Browse and Lock operation will not be locked).

The MQeMessageEnumeration object contains all the messages that match the filter supplied to the browse. .

An application can perform either a get or a delete operation on the messages to remove them from the queue. To do this, the application must supply the lock ID that is returned with the enumeration of messages. Specifying the lock ID allows applications to work with locked messages without having to unlock them first.

Instead of removing the messages from the queue, it is also possible just to unlock them, this makes them visible once again to all WebSphere MQ Everyplace applications. You can achieve this by using the unlockMessage() function.

Note:
See Getting and browsing messages from the WebSphere MQ-bridge queue for special considerations with WebSphere MQ-bridge queues.

Message listeners

WebSphere MQ Everyplace allows an application to listen for events occurring on queues. The application is able to specify message filters to identify the messages in which it is interested. A message arriving on queue triggers an event.

The Application example Ex 4 contains an example of using message listeners.

To enable this, an MQeMessageListener object must be created. The new() function for this takes an extra parameter, which is a function pointer. This function pointer indicates the function that should be called when a message arrives on the queue. This function should have the prototype:

- MQEVOID messageArrived(MQeMessageEventHndl hE);

Where MQeMessageEventHndl is a handle to an object that contains information about the message that has arrived. The queue needs to be aware of this handle , so the mqeQueueManager_addMessageListener function must be called with the MQeMessageListener object handle.

The MQeMessageEvent contains information about the message including:

Message filters only work on local queues. A separate technique known as message polling allows messages to be obtained as soon as they arrive on remote queues. (This is discussed in the next section.)

Message polling

Message polling uses the mqeQueueManager_waitForMessage() function. This command issues a mqeQueueManager_getMessage() command to the remote queue at regular intervals. As soon as a message that matches the supplied filter becomes available, it is returned to the calling application.

A wait for message call typically looks like this:

rc = mqeQueueManager_waitForMessage(hQueueManger, pExceptBlock, &hMQeMessage, 
                                    hQMgrName, hQueueName, hFilter, 
                                    hAttribute, confirmID, 6000);

The mqeQueueManager_waitForMessage() function polls the remote queue for the length of time specified in its final parameter. The time is specified in milliseconds, so in the example above, the polling lasts for 6 seconds. The thread on which the command is executing is blocked for this length of time, unless a message is returned earlier.

Message polling works on both local and remote queues.

Note:
Use of this technique results in multiple requests being sent over the network.

Messaging operations

Table 1 shows the operations that can be performed on messages on the various queue types.

Table 1. Messaging operations

Operation Local queues Remote queues


Synchronous Asynchronous
browse(&lock) yes yes
delete yes yes
get yes yes
listen yes

put yes yes yes
wait yes yes

Using queue aliases

Aliases can be assigned for WebSphere MQ Everyplace queues to provide a level of indirection between the application and the real queues. Hence the attributes of a queue that an alias relates to can be changed without the application needing to change. For instance, a queue can be given a number of aliases and messages sent to any of these names will be accepted by the queue.

The following examples illustrate some of the ways that aliasing can be used with queues.

Examples of queue aliasing

Merging applications

Suppose you have the following configuration:

Some time later the two server applications are merged into one application supporting requests from both the client applications. It may now be appropriate for the two queues to be changed to one queue. For example, you may delete Q2, and add an alias of the Q1 queue, calling it Q2. Messages from the client application that previously used Q2 are automatically sent to Q1.

Upgrading applications
Suppose you have the following configuration:

You then develop a new version of the application that gets the messages. You can make the new application work with a queue called Q2. You can define a queue called Q2 and use it to exercise the new application. When you want it to go live, you let the old version clear all traffic off the Q1 queue, and then create an alias of Q2 called Q1. The application that puts to Q1 will still work, but the messages will end up on Q2.

Using different transfer modes to a single queue

Suppose you have a queue MY_Q_ASYNC on queue manager MQE1. Messages are passed to MY_Q_ASYNC by a different queue manager MQE2, using a remote queue definition that is defined as an asynchronous queue. Now suppose your application periodically wants to get messages in a synchronous manner from the MY_Q_ASYNC queue.

The recommended way to achieve this is to add an alias to the MY_Q_ASYNC queue, perhaps called MY_Q_SYNC. Then define a remote queue definition on your MQE2 queue manager, that references the MY_Q_SYNC queue. This provides you with two remote queue definitions. If you use the MY_Q_ASYNC definition, the messages are transported asynchronously. If you use the MY_Q_SYNC definition, synchronous message transfer is used.

Figure 8. Two modes of transfer to a single queue

Diagrammatic representation of description above.



© IBM Corporation 2002. All Rights Reserved