MQCreateMessageConsumer

The MQCreateMessageConsumer function creates a synchronous message consumer for the specified destination.

MQCreateMessageConsumer
                  (const MQSessionHandle sessionHandle,
                   const MQDestinationHandle destinationHandle,
                   ConstMQString messageSelector,
                   MQBool noLocal
                   MQConsumerHandle * consumerHandle);

Return Value

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

Parameters

sessionHandle

The handle to the session to which this consumer belongs. This handle is passed back to you by the MQCreateSession() function. For this (synchronous) consumer, the session must have been created with the MQ_SESSION_SYNC_RECEIVE receive mode.

destinationHandle

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

messageSelector

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 and that all messages should be returned.

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.

noLocal

Specify MQ_TRUE to inhibit delivery of messages published by this consumer’s own connection. This applies only to topic destinations; it is ignored for queues.

consumerHandle

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

The MQCreateMessageConsumer() function creates a synchronous 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 an asynchronous message consumer for a destination, use the MQCreateAsyncMessageConsumer() function.

If the consumer is a topic destination, it can only receive messages that are published while it is active. To receive messages published while this consumer is not active, you should create a consumer using either the MQCreateDurableMessageConsumer() function or the MQCreateAsyncDurableMessageConsumer() function, depending on the receive mode you defined for the session.

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

MQ_NOT_SYNC_RECEIVE_MODE
MQ_INVALID_MESSAGE_SELECTOR
MQ_DESTINATION_CONSUMER_LIMIT_EXCEEDEED
MQ_TEMPORARY_DESTINATION_NOT_IN_CONNECTION
MQ_CONCURRENT_ACCESS
MQ_SESSION_CLOSED
MQ_BROKER_CONNECTION_CLOSED