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

MQCreateDurableMessageConsumer

The MQCreateDurableMessageConsumer function creates a synchronous durable message consumer for the specified topic destination.


MQCreateDurableMessageConsumer
          (const MQSessionHandle sessionHandle,
           const MQDestinationHandle destinationHandle,
           ConstMQString durableName,
           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) durable consumer, the session must have been created with the MQ_SESSION_SYNC_RECEIVE receive mode.

destinationHandle

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

durableName

An MQString specifying the name of the durable subscriber to the topic destination. The library makes a copy of the durableName string.

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. In this case, the consumer receives all messages. 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.

consumerHandle

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

The MQCreateDurableMessageConsumer function creates a synchronous message consumer for the specified destination. A durable consumer receives all the messages published to a topic, including the ones published while the subscriber is inactive.

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 durable message consumer for a destination, call the function MQCreateAsyncDurableMessageConsumer().

Durable consumers are for topic destinations. If you are creating a consumer for a queue destination or if you are not interested in messages that arrive to a topic while you are inactive, you should use the function MQCreateMessageConsumer.()

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 (see MQCreateConnection, clientID parameter). In addition, each durable consumer must specify a durable name using the durableName parameter, which uniquely identifies (for each client identifier) the durable subscription when it is created.

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 the 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 MQUnsubscribeDurableMessageConsumer() function after closing it to delete state information maintained by the broker on behalf of the durable consumer.

Common Errors

MQ_NOT_SYNC_RECEIVE_MODE
MQ_INVALID_MESSAGE_SELECTOR
MQ_DESTINATION_CONSUMER_LIMITE_EXCEEDEED
MQ_TEMPORARY_DESTINATION_NOT_IN_CONNECTION
MQ_CONSUMER_NO_DURABLE_NAME
MQ_QUEUE_CONSUMER_CANNOT_BE_DURABLE
MQ_CONCURRENT_ACCESS
MQ_SESSION_CLOSED
MQ_BROKER_CONNECTION_CLOSED