The following table shows which types of messaging operations are valid on
local queues, synchronous remote queues, and asynchronous remote
queues. Note that the Listen and Wait operations
are supported in Java only.
Table 4. Messaging operations on WebSphere MQ Everyplace queues
Operation | Local queue | Synchronous remote queue | Asynchronous remote queue |
---|---|---|---|
Put | Yes | Yes | Yes |
Get | Yes | Yes | No |
Browse | Yes | Yes | No |
Delete | Yes | Yes | No |
Listen | Yes | No | No |
Wait | Yes | Yes | No |
Notes:
The following list describes each message operation in detail:
If a remote queue is defined as synchronous, message transmission occurs immediately. If a remote queue is defined as asynchronous, the message is stored within the local queue manager. The message remains there until it is transmitted. The put message call may finish before the message is put. Refer to Message Delivery for more information.
You can protect a message using message-level security. Refer to Security for detailed information on message-level security.
This operation returns an available message from a specified queue and removes the message from the queue. The queue can belong to a local or remote WebSphere MQ Everyplace queue manager, but cannot be an asynchronous remote queue.
If you do not specify a filter, the first available message is returned. If you do specify a filter, the first available message that matches the filter is returned. Including a valid lockID in the message filter allows you to get messages that have been locked by a previous browse operation. If no message is available, the get operation returns an error.
Using assured message delivery depends on the value of the confirmID parameter. Passing a non-zero value returns the message as normal. However, the message is locked and is not removed from the target queue until it receives a subsequent confirm. You can issue a confirm using the confirmGetMessage() method. However, message delivery is not assured. Refer to Message Delivery, for more information on assured and non-assured message delivery.
This method deletes a message from a queue. It does not return the message to the application that called it. You must specify the UniqueID and you can delete only one message per operation. The queue can belong to a local or synchronous remote WebSphere MQ Everyplace queue manager. Including a valid lockID in the message filter allows you to delete messages that have been locked by a previous operation, for example browse. If a message is not available, the application returns an error.
/* Example for deleting a message */ MQeFieldsHndl hMsg,hFilter; /* create the new message */ rc = mqeFields_new(&exceptBlock, &hMsg); if (MQERETURN_OK == rc) { /* add application fields here */ /* ... */ /* put message to a queue */ rc = mqeQueueManager_putMessage(hQueueManager, &exceptBlock, hQMName, hQueueName, hMsg, NULL,0); if (MQERETURN_OK == rc) { /* Delete requires a filter - this can most easily be*/ /* found from the UID fields of the message*/ rc = mqeFieldsHelper_getMsgUidFields(hMsg, &exceptBlock, &hFilter); } } /* some time later want to delete the message - use the esatblished filter */ rc = mqeQueueManager_deleteMessage(hQueueManager, &exceptBlock, hQMName, hQueueName, hFilter);
You can browse queues for messages using a filter, for example message ID or priority . Browsing retrieves all the messages that match the filter, but leaves them on the queue. The queue can belong to a local or remote queue manager. However, the implementation of the browse command is codebase specific.
WebSphere MQ Everyplace also supports Browsing under lock. This allows you to lock the matching messages on the queue. You can lock messages individually, or in groups identified through a filter, and the locking operation returns a lockID. Use the lockID to get or delete messages. An option on browse allows you to return either the full messages, or only the UniqueIDs.
MQeVectorHndl hListMsgs; rc = mqeQueueManager_browseMessages(hQueueManager, &exceptBlock, &hListMsgs, hQMName, hQueueName, hFilter, NULL,MQE_FALSE); if (MQERETURN_OK == rc) { /* process list using mqeVector_* apis */ /* free off the vector */ rc = mqeVector_free(hListMsgs,&exceptBlock); }
Returning an entire collection of messsages can be expensive in terms of system resources. Setting the justUID parameter to true and returns the uniqueID of each message that matches the filter only.
The messages returned in the collection are still visible to other WebSphere MQ Everyplace APIs. Therefore, when performing subsequent operations on the messages contained in the enumeration, the application must be aware that another application can process these messages once the collection is returned. To prevent other applications from processing messages, use the browseMessagesAndLock method to lock messages contained in the enumeration.
This method implements message polling. It allows you to specify a time for messages to arrive on a queue. Java implements a helper function for this. The C codebase, as it is non-threaded, must implement a function in application layer code. The following example demonstrates the Wait method:
qmgr.waitForMessage("RemoteQMgr", "RemoteQueue", filter, null, 0, 60000);
The waitForMessage() method polls the remote queue for the length of time specified in its final parameter. The time is specified in milliseconds. Therefore, in the example, polling lasts for 6 seconds. This blocks the thread on which the command is running for 6 seconds, unless a message is returned earlier. Message polling works on both local and remote queues.