Messaging operations

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:

  1. The synchronous remote wait operation is implemented through a poll of the remote queue, so the actual wait time is a multiple of the poll time

  2. The WebSphere MQ bridge supplied with WebSphere MQ Everyplace only supports an assured or unassured put, unassured get, and unassured browse (without lock).

The following list describes each message operation in detail:

Put
This operation places specified messages on a specified queue. The queue can belong to a local or remote queue manager. Puts to remote queues can occur immediately, or at a later time, depending on how the remote queue is defined on the local queue manager.

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.

Note:
In Java, if the local queue manager does not hold a definition of the remote queue then it attempts to contact the queue sychronously. This does not apply to the C codebase.
Assured delivery depends on the value of the confirmID parameter. Passing a non-zero value transmits the message as normal, but the message is locked on the target queue until a subsequent confirm is received. Passing a value of zero transmits the message without the need for a subsequent confirm. However, message delivery is not assured. Refer to Message Delivery, for more information on assured and non-assured message delivery.

You can protect a message using message-level security. Refer to Security for detailed information on message-level security.

Get

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.

Delete

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);
 
 

Browse

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.

confirmPut
This method performs the confirmation of a previously successful putMessage() operation.

confirmGet
This method confirms the successful receipt of a message retrieved from a queue manager by a previous getMessage() operation. The message remains locked on the target queue until it receives a confirm flow.

Listen
Applications can listen for WebSphere MQ Everyplace message events, again with an optional filter. However, in order to do this, you must add a listener to a queue manager. Listeners are notified when messages arrive on a queue.

Wait

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:

Java
Message polling uses the waitForMessage() method. This command issues a 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:
	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.

Note:
Using this technique sends multiple requests over the network.


© IBM Corporation 2002. All Rights Reserved