# tibemsSession_CreateSharedDurableConsumer

Function

## Purpose

Create a shared durable consumer.

## C Declaration

    tibems_status tibemsSession_CreateSharedDurableConsumer(
        tibemsSession session,
        tibemsMsgConsumer* consumer,
        tibemsTopic topic,
        const char* durableName,
        const char* messageSelector );

## COBOL Call

    CALL "tibemsSession_CreateSharedDurableConsumer"
         USING BY VALUE session,
               BY REFERENCE consumer,
               BY VALUE topic,
               BY REFERENCE durableName,
               BY REFERENCE messageSelector,
               RETURNING tibems-status
    END-CALL.

Note: `session`, `consumer` and `topic` have usage pointer.

## Parameters

Parameter | Description
--- | ---
`session` | Create the shared durable consumer in this session.
`consumer` | The function stores the new message consumer object in this location.
`topic` | Create the shared durable consumer for this topic.
`durableName` | The name used to identify the shared 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 durable subscription on the specified topic (if one does not already exist), optionally specifying a message selector, and creates a consumer on that durable subscription.

A durable subscription is used by an application that needs to receive all the messages published on a topic, including the ones published when there is no active consumer associated with it. The server retains a record of this durable subscription and ensures that all messages from the topic's publishers are retained until they are delivered to, and acknowledged by, a consumer on this durable subscription, or until they have expired.

A durable subscription will continue to accumulate messages until it is deleted using the `tibemsSession_Unsubscribe` function.

This method may only be used with shared durable subscriptions. Any durable subscription created using this method is shared. This means that multiple active (that is, not closed) consumers on the subscription may exist at the same time. The term consumer here means a `tibemsMsgConsumer` object in any client.

A shared 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 durable subscription must use the same client identifier.

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

If a shared 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 no consumer already active (that is, not closed) on the durable subscription, then this is equivalent to unsubscribing (deleting) the old one and creating a new one.

If a shared 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 (that is, not closed) on the durable subscription, then an error is returned.

A shared durable subscription and an unshared durable subscription may not have the same name and client identifier (if set). If an unshared durable subscription already exists with the same name and client identifier (if set) then an error is 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_CreateSharedConsumer`

`tibemsSession_Unsubscribe`

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