# 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`

Copyright © Cloud Software Group, Inc. All rights reserved.