Receiving Messages

Messages are received by a message consumer in the context of a connection and a session. In order to receive messages, you must explicitly start the connection by calling the MQStartConnection function.

Table 2–10 lists the functions you use to create message consumers and to receive messages.

Table 2–10 Functions Used to Receive Messages

Function	Description
MQCreateMessageConsumer	Creates the specified synchronous consumer and passes back a handle to it.
MQCreateDurableMessageConsumer	Creates a durable synchronous message consumer for the specified destination.
MQCreateAsyncMessageConsumer	Creates an asynchronous message consumer for the specified destination.
MQCreateAsyncDurableMessageConsumer	Creates a durable asynchronous message consumer for the specified destination.
MQUnsubscribeDurableMessageConsumer	Unsubscribes the specified durable message consumer.
MQReceiveMessageNoWait	Passes a handle back to a message delivered to the specified consumer if a message is available; otherwise it returns an error.
MQReceiveMessageWait	Passes a handle back to a message delivered to the specified consumer if a message is available; otherwise it blocks until a message becomes available.
MQReceiveMessageWithTimeout	Passes a handle back to a message delivered to the specified consumer if a message is available within the specified amount of time.
MQAcknowledgeMessages	Acknowledges the specified message and all messages received before it on the same session
MQCloseMessageConsumer	Closes the specified consumer.

Working With Consumers

When you create a consumer, you need to make several decisions:

• Do you want to receive messages synchronously or asynchronously?

  If you create a synchronous consumer, you can call one of three kinds of receive functions to receive your messages. If you create an asynchronous consumer, you must specify the name of a callback function that the client runtime can call when a message is delivered to the destination for that consumer. For information about the callback function signature, see Callback Type for Asynchronous Message Consumption .

• If you are consuming messages from a topic, do you want to use a durable or a nondurable consumer?

  A durable consumer receives all the messages published to a topic, including the ones published while the subscriber is inactive. A nondurable consumer only receives messages while the subscriber is active.

  The broker retains a record of this durable subscription and makes sure that all messages from the publishers to this topic are retained until they are either acknowledged by this durable subscriber or until they have expired. Sessions with durable subscribers must always provide the same client identifier. In addition, each consumer must specify a durable name using the durableName parameter, which uniquely identifies (for each client identifier) each durable subscription it creates.

A session’s consumers are automatically closed when you close the session or connection to which they belong. However, messages will be routed to the durable subscriber while it is inactive and delivered when a new durable consumer is recreated. To close a consumer without closing the session or connection to which it belongs, use the MQCloseMessageConsumer() function. If you want to close a durable consumer permanently, you should call the function MQUnsubscribeDurableMessageConsumer after closing it, to delete state information maintained by the broker on behalf of the durable consumer.

Receiving a Message Synchronously

If you have created a synchronous consumer, you can use one of three receive functions: MQReceiveMessageNoWait, MQReceiveMessageWait , or MQReceiveMessagewithTimeOut. In order to use any of these functions, you must have specified MQ_SESSION_SYNC_RECEIVE for the receive mode when you created the session.

When you create a session you must specify one of several acknowledge modes for that session. 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. If the session is transacted, the acknowledge mode parameter is ignored.

When the receiving function returns, it gives you a handle to the delivered message. You can pass that handle to the functions described in Processing a Message, in order to read message properties and information stored in the header and body of the message.

It is possible that a message can be lost for synchronous consumers in a session using AUTO_ACKNOWLEDGE mode if the provider fails. To prevent this possibility, you should either use a transacted session or a session in CLIENT_ACKNOWLEDGE mode.

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 on the broker. See the usage notes provided in the section MQReceiveMessageNoWait for more information.

Receiving a Message Asynchronously

To receive a message asynchronously, you must create an asynchronous message consumer and pass the name of an MQMessageListenerFunc type callback function. (Therefore, you must set up the callback function before you create the asynchronous consumer that will use it.) You should start the connection only after creating an asynchronous consumer. If the connection is already started, you should stop the connection before creating an asynchronous consumer.

You are also responsible for writing the message listener function. Mainly, the function needs to process the incoming message by examining its header, body, and properties, or it needs to pass control to a function that can do this processing. The client is also responsible for freeing the message handle (either from within the listener or from outside of the listener) by calling the MQFreeMessage function.

When you create a session you must specify one of several acknowledge modes for that session. 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 about the signature and content of a call back function, see Callback Type for Asynchronous Message Consumption.

When the callback function is called by the session delivery of a message, it gives you a handle to the delivered message. You can pass that handle to the functions described in Processing a Message, in order to read message properties and information stored in the header and body of the message.