Sun Java System Message Queue 4.3 Developer's Guide for C Clients

MQReceiveMessageNoWait

The MQReceiveMessageNoWait function passes a handle back to a message delivered to the specified consumer if a message is available.


MQReceiveMessageNoWait(const MQConsumerHandle consumerHandle,
  													MQMessageHandle * messageHandle);

Return Value

MQStatus. See the MQStatusIsError() function for more information.

Parameters

consumerHandle

The handle to the message consumer. This handle is passed back to you when you create a synchronous message consumer.

messageHandle

Output parameter for the handle to the message to be received. You are responsible for freeing the message handle when you are done by calling the MQFreeMessage() function.

This function can only be called if the session is created with receive mode MQ_SESSION_SYNC_RECEIVE. The MQReceiveMessageNoWait function passes a handle back to you in the messageHandle parameter if there is a message arrived for the consumer specified by the consumerHandle parameter. If there is no message for the consumer, the function returns immediately with an error.

When you create a session, you specify one of several acknowledge modes for that session; these are described in Acknowledge Modes. If you specify MQ_CLIENT_ACKNOWLEDGE as the acknowledge mode for the session, you must explicitly call the MQAcknowledgeMessages function to acknowledge messages that you have received. For more information, see the description of the function MQAcknowledgeMessage()s.

Because distributed applications involve greater processing time, such an application might not behave as expected if it were run locally. For example, calling the MQReceiveMessageNoWait function might return MQ_NO_MESSAGE even when there is a message available to be retrieved.

If a client connects to the broker and immediately calls the MQReceiveMessageNoWait , it is possible that the message queued for the consuming client is in the process of being transmitted from the broker to the client. The client runtime has no knowledge of what is on the broker, so when it sees that there is no message available on the client’s internal queue, it returns with MQ_NO_MESSAGE .

You can avoid this problem by having your client use one of the synchronous receive methods that specifies a timeout interval.

You can use the MQReceiveMessageWait() function if you want the receive function to block while waiting for a message to arrive. You can use the MQReceiveMessageWithTimeout() function to wait for a specified time for a message to arrive.

Common Errors

MQ_NOT_SYNC_RECEIVE_MODE
MQ_CONCURRENT_ACCESS
MQ_NO_MESSAGE
MQ_CONSUMER_CLOSED
MQ_SESSION_CLOSED
MQ_BROKER_CONNECTION_CLOSED
MQ_THREAD_OUTSIDE_XA_TRANSACTION
MQ_XA_SESSION_NO_TRANSATION