tibemsSession_CreateSharedConsumer

Function

Purpose

Create a shared consumer.

C Declaration

tibems_status tibemsSession_CreateSharedConsumer(
    tibemsSession session,
    tibemsMsgConsumer* consumer,
    tibemsTopic topic,
    const char* sharedSubscriptionName,
    const char* messageSelector );

COBOL Call

CALL "tibemsSession_CreateSharedConsumer"
     USING BY VALUE session,
           BY REFERENCE consumer,
           BY VALUE topic,
           BY REFERENCE sharedSubscriptionName,
           BY REFERENCE messageSelector,
           RETURNING tibems-status
END-CALL.
Note: session, consumer and topic have usage pointer.

Parameters

Parameter Description
session Create the shared non-durable consumer in this session.
consumer The function stores the new message consumer object in this location.
topic Create the shared consumer for this topic.
sharedSubscriptionName The name used to identify the shared non-durable subscription.
messageSelector When non-null, the server filters messages using this selector, so the consumer receives only matching messages; see Message Selectors.

When null, or the empty string, the consumer receives messages without filtering.

Remarks

Creates a shared non-durable subscription with the specified name on the specified topic (if one does not already exist), optionally specifying a message selector, and creates a consumer on that subscription.

If a shared non-durable subscription already exists with the same name and client identifier (if set), and the same topic and message selector has been specified, then this method creates a tibemsMsgConsumer on the existing subscription.

A non-durable shared subscription is used by a client that needs to be able to share the work of receiving messages from a topic subscription amongst multiple consumers. A non-durable shared subscription may therefore have more than one consumer. Each message from the subscription will be delivered to only one of the consumers on that subscription. Such a subscription is not persisted and is deleted (together with any undelivered messages associated with it) when there are no consumers on it. The term consumer here means a tibemsMsgConsumer object in any client.

A shared non-durable subscription is identified by a name specified by the client and by the client identifier (which may be unset). An application which subsequently wishes to create a consumer on that shared non-durable subscription must use the same client identifier.

If a shared non-durable subscription already exists with the same name and client identifier (if set) but a different topic or message selector has been specified, and there is a consumer already active (i.e. not closed) on the subscription, then an error will be returned.

There is no restriction on durable subscriptions and shared non-durable subscriptions having the same name and clientId (which may be unset). Such subscriptions would be completely separate.

See Also

tibemsSession_CreateSharedDurableConsumer