Sun GlassFish Message Queue 4.4 Developer's Guide for C Clients


The MQCreateAsyncMessageConsumer function creates an asynchronous message consumer for the specified destination.

              (const MQSessionHandle sessionHandle,
               const MQDestinationHandle destinationHandle,
               ConstMQString messageSelector,
               MQBool noLocal,
               MQMessageListenerFunc messageListener,
               void * listenerCallBackData,
               MQConsumerHandle * consumerHandle);

Return Value

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



The handle to the session to which this consumer belongs. This handle is created and passed back to you by the MQCreateSession function. For this asynchronous consumer, the session must have been created with the MQ_SESSION_ASYNC_RECEIVE receive mode.


A handle to the destination on which the consumer receives messages. This handle remains valid after the call returns.


An expression (based on SQL92 conditional syntax) that specifies the criteria upon which incoming messages should be selected for this consumer.

Specify a NULL or empty string to indicate that there is no message selector for this consumer. In this case, all messages will be delivered.

The library makes a copy of the messageSelector string.

For more information about SQL, see X/Open CAE Specification Data Management: Structured Query Language (SQL), Version 2, ISBN 1-85912-151-9, March 1966.


Specify MQ_TRUE to inhibit delivery of messages published by this consumer’s own connection.

The setting of this parameter applies only to topic destinations. It is ignored for queues.


The name of an MQMessageListenerFunc type callback function that is to be called when this consumer receives a message for the specified destination.


A pointer to data that you want passed to your message listener function when it is called by the library.


Output parameter for the handle that references the consumer for the specified destination.

In the case of an asynchronous consumer, you should not start a connection before calling the MQCreateAsyncDurableMessageConsumer function. (You should create a connection, create a session, set up your asynchronous consumers, create the consumer, and then start the connection.) Attempting to create a consumer when the connection is not stopped will result in an MQ_CONCURRENT_ACCESS error.

The MQCreateAsyncMessageConsumer function creates an asynchronous message consumer for the specified destination. You can define parameters to filter messages and to inhibit the delivery of messages you published to your own connection. Note that the session’s receive mode (sync/async) must be appropriate for the kind of consumer you are creating (sync/async). To create a synchronous message consumer for a destination, use the MQCreateMessageConsumer() function.

If this consumer is on a topic destination, it will only receive messages produced while the consumer is active. If you are interested in receiving messages published while this consumer is not active, you should create a consumer using the MQCreateAsyncDurableMessageConsumer function instead.

A session’s consumers are automatically closed when you close the session or connection to which they belong. To close a consumer without closing the session or connection to which it belongs, use the MQCloseMessageConsumer function.

Common Errors