> tibemsSession
> Type
> Purpose
> Organizing context for message activity.
> Remarks
> Sessions combine several roles:

> ● | Create message producers and consumers

> ● | Create message objects

> ● | Create temporary destinations

> ● | Create dynamic destinations

> ● | Create queue browsers

> ● | Serialize for inbound and outbound messages

> ● | Serialize for asynchronous message events (or message listeners) of its consumer objects

> ● | Cache inbound messages (until the program acknowledges them).

> ● | Transaction support (when enabled).

> Single Thread
> The JMS specification restricts programs to use each session within a single thread.
> Associated Objects
> The same single-thread restriction applies to objects associated with a session—namely, messages, message consumers, durable subscribers, message producers, queue browsers, and temporary destinations (however, static and dynamic destinations are exempt from this restriction).
> Corollary
> One consequence of this rule is that all the consumers of a session must deliver messages in the same mode—either synchronously or asynchronously.
> Asynchronous
> In asynchronous delivery, the program registers message handler events or message listeners with the session’s consumer objects. An internal dispatcher thread delivers messages to those event handlers or listeners (in all the session’s consumer objects). No other thread may use the session (nor objects created by the session).
> Synchronous
> In synchronous delivery, the program explicitly begins a thread for the session. That thread processes inbound messages and produces outbound messages, serializing this activity among the session’s producers and consumers. Functions that request the next message (such as tibemsMsgConsumer_Receive) can organize the thread’s activity.
> Close
> The only exception to the rule restricting session calls to a single thread is the function tibemsSession_Close; programs can call Close from any thread at any time.
> Transactions
> A session has either transaction or non-transaction semantics. When a program specifies transaction semantics, the session object cooperates with the server, and all messages that flow through the session become part of a transaction.

> ● | When the program calls tibemsSession_Commit, the session acknowledges all inbound messages in the current transaction, and the server delivers all outbound messages in the current transaction to their destinations.

> ● | If the program calls tibemsSession_Rollback, the session recovers all inbound messages in the current transaction (so the program can consume them in a new transaction), and the server destroys all outbound messages in the current transaction.

> After these actions, both Commit and Rollback immediately begin a new transaction.

> Function | Description | Page
> Messages
> tibemsSession_CreateBytesMessage | Create a byte array message. | 292
> tibemsSession_CreateMapMessage | Create a map message. | 298
> tibemsSession_CreateStreamMessage | Create a stream message. | 301
> tibemsSession_CreateTextMessage | Create a text message. | 304
> Destinations
> tibemsSession_CreateBrowser | Create a queue browser. | 291
> tibemsSession_CreateTemporaryQueue | Create a temporary queue. | 302
> tibemsSession_CreateTemporaryTopic | Create a temporary topic. | 303
> Consumers & Producers
> tibemsSession_CreateConsumer | Create a message consumer. | 293
> tibemsSession_CreateDurableSubscriber | Create a durable topic subscriber. | 295
> tibemsSession_CreateProducer | Create a message producer. | 300
> tibemsSession_Unsubscribe | Unsubscribe a durable topic subscription. | 312
> Transactions
> tibemsSession_Commit | Commit the open transaction. | 290
> tibemsSession_Rollback | Roll back messages in the current transaction. | 311
> Other
> tibemsSession_Close | Close a session; reclaim resources. | 289
> tibemsSession_Recover | Recover from undetermined state during message processing. | 309

> tibemsSession_Close
> Function
> Purpose
> Close a session; reclaim resources.
> C Declaration
> tibems_status tibemsSession_Close(
> tibemsSession session );
> COBOL Call
> CALL "tibemsSession_Close"
> USING BY VALUE session,
> RETURNING tibems-status
> END-CALL.

> | session has usage pointer.

> Remarks
> Closing a session automatically closes its consumers (except for durable subscribers), producers and browsers.
> Blocking
> If any message listener or receive call associated with the session is processing a message when the program calls this function, all facilities of the connection and its sessions remain available to those listeners until they return. In the meantime, this function blocks until that processing completes—that is, until all message listeners and receive calls have returned.
> Transactions
> Closing a session rolls back the open transaction in the session.
> tibemsSession_Commit
> Function
> Purpose
> Commit the open transaction.
> C Declaration
> tibems_status tibemsSession_Commit(
> tibemsSession session );
> COBOL Call
> CALL "tibemsSession_Commit"
> USING BY VALUE session,
> RETURNING tibems-status
> END-CALL.

> | session has usage pointer.

> Remarks
> A session (with transaction semantics) always has exactly one open transaction. Message operations associated with the session become part of that transaction. This call commits all the messages within the transaction, and releases any locks. Then it opens a new transaction.

> Status Code | Description
> TIBEMS_OK | Successful commit.
> TIBEMS_ILLEGAL_STATE | The session does not have transaction semantics.
> TIBEMS_SECURITY_EXCEPTION | The client lacks permission to send one of messages in the transaction.
> TIBEMS_TRANSACTION_FAILED | Commit failed and the server automatically rolled back the transaction.
> TIBEMS_TRANSACTION_ROLLBACK

> tibemsSession_CreateBrowser
> Function
> Purpose
> Create a queue browser.
> C Declaration
> tibems_status tibemsSession_CreateBrowser(
> tibemsSession session,
> tibemsQueueBrowser* browser,
> tibemsQueue queue,
> const char* messageSelector );
> COBOL Call
> CALL "tibemsSession_CreateBrowser"
> USING BY VALUE session,
> BY REFERENCE browser,
> BY VALUE queue,
> BY REFERENCE messageSelector,
> RETURNING tibems-status
> END-CALL.

> | session, browser and queue have usage pointer.

> Parameters

> Parameter | Description
> session | Create a browser in this session.
> browser | The function stores the new browser object in this location.
> queue | Browse this queue.
> messageSelector | When non-null, the browser presents only messages that match this selector; see Message Selectors. When null, or the empty string, the browser views all messages in the queue.

> See Also
> tibemsQueue on page 150
> tibemsQueueBrowser on page 316
> tibemsSession_CreateBytesMessage
> Function
> Purpose
> Create a byte array message.
> C Declaration
> tibems_status tibemsSession_CreateBytesMessage(
> tibemsSession session,
> tibemsBytesMsg* bytesMsg );
> COBOL Call
> CALL "tibemsSession_CreateBytesMessage"
> USING BY VALUE session,
> BY REFERENCE bytesMsg,
> RETURNING tibems-status
> END-CALL.

> | session and bytesMsg have usage pointer.

> Parameters

> Parameter | Description
> session | Create the message in this session.
> bytesMsg | The function stores the new message object in this location.

> See Also
> tibemsBytesMsg on page 72
> tibemsSession_CreateConsumer
> Function
> Purpose
> Create a message consumer.
> C Declaration
> tibems_status tibemsSession_CreateConsumer(
> tibemsSession session,
> tibemsMsgConsumer* consumer,
> tibemsDestination destination,
> const char* messageSelector,
> tibems_bool noLocal );
> COBOL Call
> CALL "tibemsSession_CreateConsumer"
> USING BY VALUE session,
> BY REFERENCE consumer,
> BY VALUE destination,
> BY REFERENCE messageSelector,
> BY VALUE noLocal,
> RETURNING tibems-status
> END-CALL.

> | session, consumer and destination have usage pointer.

> Parameters

> Parameter | Description
> session | Create the consumer in this session.
> consumer | The function stores the new consumer object in this location.
> destination | Create a consumer for this destination. The argument may be any destination (queue or topic).
> 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.
> noLocal | When true, the server filters messages so the consumer does not receive messages that originate locally—that is, messages sent through the same connection. When false, the consumer receives messages with local origin.

> See Also
> tibemsDestination on page 144
> tibemsMsgConsumer on page 162
> tibemsSession_CreateDurableSubscriber
> Function
> Purpose
> Create a durable topic subscriber.
> C Declaration
> tibems_status tibemsSession_CreateDurableSubscriber(
> tibemsSession session,
> tibemsMsgConsumer* msgConsumer,
> tibemsTopic topic,
> const char* name,
> const char* messageSelector,
> tibems_bool noLocal );
> COBOL Call
> CALL "tibemsSession_CreateDurableSubscriber"
> USING BY VALUE session,
> BY REFERENCE msgConsumer,
> BY VALUE topic,
> BY REFERENCE name,
> BY REFERENCE messageSelector,
> BY VALUE noLocal,
> RETURNING tibems-status
> END-CALL.

> | session, msgConsumer, and topic have usage pointer.

> Parameters

> Parameter | Description
> session | Create the topic subscriber in this session.
> msgConsumer | The function stores the new message consumer object in this location. Note that the message consumer must be a topic subscriber.
> topic | Create a durable subscriber for this topic (which cannot be a tibemsTemporaryTopic).
> name | This unique name lets the server associate the subscriber with a subscription.
> messageSelector | When non-null, the server filters messages using this selector, so the subscriber receives only matching messages; see Message Selectors. When null, or the empty string, the subscriber receives messages without filtering.
> noLocal | When true, the server filters messages so the subscriber does not receive messages that originate locally—that is, messages sent through the same connection. When false, the consumer receives messages with local origin.

> Remarks
> The server associates a durable subscription with at most one subscriber object at a time. When a subscriber object exists, the subscription is active, and the server delivers messages to it; when no subscriber object exists, the subscription is inactive.
> Durable subscriptions guarantee message delivery across periods during which the subscriber is inactive. The server retains unacknowledged messages until the subscriber acknowledges them, or until the messages expire.
> Subscription Continuity
> Continuity across inactive periods uses two data items from the client:

> ● | Subscription Name a parameter of this call

> ● | Client ID an optional property of the tibemsConnection (used only when supplied)

> The server uses one or both of these two items to match a subscriber object with its subscription. If a matching subscription exists, and it is inactive, then the server associates it with the subscriber (and the subscription becomes active). The server delivers unacknowledged messages to the subscriber.
> If a matching subscription exists, but it is already active, this function fails with TIBEMS_INVALID_CONSUMER.
> If a matching subscription to the topic does not yet exist, the server creates one.
> Matching Client ID

> ● | If the tibemsConnection’s client ID is non-null when a session creates a durable subscription, then only sessions of a connection with the same client ID can attach to that subscription.

> ● | If the tibemsConnection’s client ID is null when a session creates a durable subscription, then any session can attach to that subscription (to receive its messages).

> Changing Topic or Selector
> Notice that the server does not use the topic and message selector arguments to match a subscriber to an existing subscription. As a result, client programs can change a subscription by altering either or both of these arguments. The effect is equivalent to deleting the existing subscription (from the server) and creating a new one (albeit with the same client ID and subscription name).
> See Also
> tibemsTopic on page 156
> tibemsMsgConsumer on page 162
> tibemsConnection on page 202
> tibemsSession_CreateMapMessage
> Function
> Purpose
> Create a map message.
> C Declaration
> tibems_status tibemsSession_CreateMapMessage(
> tibemsSession session,
> tibemsMapMsg* mapMsg );
> COBOL Call
> CALL "tibemsSession_CreateMapMessage"
> USING BY VALUE session,
> BY REFERENCE mapMsg,
> RETURNING tibems-status
> END-CALL.

> | session and mapMsg have usage pointer.

> Parameters

> Parameter | Description
> session | Create the message in this session.
> mapMsg | The function stores the new message object in this location.

> Remarks
> The JMS specification requires this call. It is equivalent to tibemsMapMsg_Create on page 89.
> See Also
> tibemsMapMsg on page 88
> tibemsSession_CreateMessage
> Function
> Purpose
> Create a message.
> C Declaration
> tibems_status tibemsSession_CreateMessage(
> tibemsSession session,
> tibemsMsg* message );
> COBOL Call
> CALL "tibemsSession_CreateMessage"
> USING BY VALUE session,
> BY REFERENCE message,
> RETURNING tibems-status
> END-CALL.

> | session and message have usage pointer.

> Parameters

> Parameter | Description
> session | Create the message in this session.
> message | The function stores the new message object in this location.

> Remarks
> The JMS specification requires this call. It is equivalent to tibemsMsg_Create on page 28.
> See Also
> tibemsMsg on page 21
> tibemsSession_CreateProducer
> Function
> Purpose
> Create a message producer.
> C Declaration
> tibems_status tibemsSession_CreateProducer(
> tibemsSession session,
> tibemsMsgProducer* producer,
> tibemsDestination destination );
> COBOL Call
> CALL "tibemsSession_CreateProducer"
> USING BY VALUE session,
> BY REFERENCE producer,
> BY VALUE destination,
> RETURNING tibems-status
> END-CALL.

> | session, producer and destination have usage pointer.

> Parameters

> Parameter | Description
> session | Create the producer in this session.
> producer | The function stores the new producer object in this location.
> destination | When non-null, the producer sends messages to this destination. When null, the client program must specify the destination for each message individually.

> See Also
> tibemsDestination on page 144
> tibemsMsgProducer on page 174
> tibemsSession_CreateStreamMessage
> Function
> Purpose
> Create a stream message.
> C Declaration
> tibems_status tibemsSession_CreateStreamMessage(
> tibemsSession session,
> tibemsStreamMsg* streamMsg );
> COBOL Call
> CALL "tibemsSession_CreateStreamMessage"
> USING BY VALUE session,
> BY REFERENCE streamMsg,
> RETURNING tibems-status
> END-CALL.

> | session and streamMsg have usage pointer.

> Parameters

> Parameter | Description
> session | Create the message in this session.
> streamMsg | The function stores the new message object in this location.

> Remarks
> The JMS specification requires this call. It is equivalent to tibemsStreamMsg_Create on page 109.
> See Also
> tibemsStreamMsg on page 107
> tibemsSession_CreateTemporaryQueue
> Function
> Purpose
> Create a temporary queue.
> C Declaration
> tibems_status tibemsSession_CreateTemporaryQueue(
> tibemsSession session,
> tibemsTemporaryQueue* tmpQueue );
> COBOL Call
> CALL "tibemsSession_CreateTemporaryQueue"
> USING BY VALUE session,
> BY REFERENCE tmpQueue,
> RETURNING tibems-status
> END-CALL.

> | session and tmpQueue have usage pointer.

> Parameters

> Parameter | Description
> session | Create the queue in this session.
> tmpQueue | The function stores the new temporary queue object in this location.

> Remarks
> A temporary queue lasts no longer than the connection. That is, when the connection is closed or broken, the server deletes temporary queues associated with the connection.
> If the named queue already exists at the server, then this function returns that queue. (That queue can be either static or dynamic.)
> If the named queue does not yet exist at the server, and the server allows dynamic queue, then this function creates a dynamic queue.
> Dynamic destinations are provider-specific, so programs that use them might not be portable to other providers.
> See Also
> tibemsTemporaryQueue on page 154
> tibemsSession_CreateTemporaryTopic
> Function
> Purpose
> Create a temporary topic.
> C Declaration
> tibems_status tibemsSession_CreateTemporaryTopic(
> tibemsSession session,
> tibemsTemporaryTopic* tmpTopic );
> COBOL Call
> CALL "tibemsSession_CreateTemporaryTopic"
> USING BY VALUE session,
> BY REFERENCE tmpTopic,
> RETURNING tibems-status
> END-CALL.

> | session and tmpTopic have usage pointer.

> Parameters

> Parameter | Description
> session | Create the queue in this session.
> tmpTopic | The function stores the new temporary topic object in this location.

> Remarks
> A temporary topic lasts no longer than the connection. That is, when the connection is closed or broken, the server deletes temporary topic associated with the connection.
> If the named topic already exists at the server, then this function returns that topic. (That topic can be either static or dynamic.)
> If the named topic does not yet exist at the server, and the server allows dynamic topics, then this function creates a dynamic topic.
> Dynamic destinations are provider-specific, so programs that use them might not be portable to other providers.
> See Also
> tibemsTemporaryTopic on page 155
> tibemsSession_CreateTextMessage
> Function
> Purpose
> Create a text message.
> C Declaration
> tibems_status tibemsSession_CreateTextMessage(
> tibemsSession session,
> tibemsTextMsg* textMsg );
> tibems_status tibemsSession_CreateTextMessageEx(
> tibemsSession session,
> tibemsTextMsg* textMsg
> const char* text );
> COBOL Call
> CALL "tibemsSession_CreateTextMessage"
> USING BY VALUE session,
> BY REFERENCE textMsg,
> RETURNING tibems-status
> END-CALL.
> CALL "tibemsSession_CreateTextMessageEx"
> USING BY VALUE session,
> BY REFERENCE textMsg,
> BY REFERENCE text,
> RETURNING tibems-status
> END-CALL.

> | session and textMsg have usage pointer.

> Parameters

> Parameter | Description
> session | Create the message in this session.
> textMsg | The function stores the new message object in this location.
> text | Create a text message with this text as its body.

> Remarks
> The JMS specification requires these calls. It is equivalent to tibemsTextMsg_Create on page 123.
> See Also
> tibemsTextMsg on page 122
> tibemsSession_DeleteTemporaryQueue
> Function
> Purpose
> Delete a temporary queue.
> C Declaration
> tibems_status tibemsSession_DeleteTemporaryQueue(
> tibemsSession session,
> tibemsTemporaryQueue tmpQueue );
> COBOL Call
> CALL "tibemsSession_DeleteTemporaryQueue"
> USING BY VALUE session,
> BY VALUE tmpQueue,
> RETURNING tibems-status
> END-CALL.

> | session and tmpQueue have usage pointer.

> Parameters

> Parameter | Description
> session | Delete a temporary queue from this session.
> tmpQueue | Delete this temporary queue.

> Remarks
> When a client deletes a temporary queue, the server deletes any unconsumed messages in the queue.
> If the client still has listeners or receivers for the queue, then this delete call returns TIBEMS_ILLEGAL_STATE.
> See Also
> tibemsTemporaryQueue on page 154
> tibemsSession_DeleteTemporaryTopic
> Function
> Purpose
> Delete a temporary topic.
> C Declaration
> tibems_status tibemsSession_DeleteTemporaryTopic(
> tibemsSession session,
> tibemsTemporaryTopic tmpTopic );
> COBOL Call
> CALL "tibemsSession_DeleteTemporaryTopic"
> USING BY VALUE session,
> BY VALUE tmpTopic,
> RETURNING tibems-status
> END-CALL.

> | session and tmpTopic have usage pointer.

> Parameters

> Parameter | Description
> session | Delete a temporary topic from this session.
> tmpTopic | Delete this temporary topic.

> Remarks
> When a client deletes a temporary topic, the server deletes any unconsumed messages in the topic.
> If the client still has listeners or receivers for the topic, then this delete call returns TIBEMS_ILLEGAL_STATE.
> See Also
> tibemsTemporaryTopic on page 155
> tibemsSession_GetAcknowledgeMode
> Function
> Purpose
> Get the acknowledge mode of a session.
> C Declaration
> tibems_status tibemsSession_GetAcknowledgeMode(
> tibemsSession session,
> tibemsAcknowledgeMode* acknowledgeMode );
> COBOL Call
> CALL "tibemsSession_GetAcknowledgeMode"
> USING BY VALUE session,
> BY REFERENCE acknowledgeMode,
> RETURNING tibems-status
> END-CALL.

> | session has usage pointer.

> Parameters

> Parameter | Description
> session | Get the property from this session.
> acknowledgeMode | The function stores the property value in this location.

> Remarks
> This mode governs message acknowledgement and redelivery for consumers associated with the session. For values, see tibemsAcknowledgeMode on page 313.
> This property is irrelevant when the session has transactional semantics.
> tibemsSession_GetTransacted
> Function
> Purpose
> Get the transactional semantics property of a session.
> C Declaration
> tibems_status tibemsSession_GetTransacted(
> tibemsSession session,
> tibems_bool* isTransacted );
> COBOL Call
> CALL "tibemsSession_GetTransacted"
> USING BY VALUE session,
> BY REFERENCE isTransacted,
> RETURNING tibems-status
> END-CALL.

> | session has usage pointer.

> Parameters

> Parameter | Description
> session | Get the property from this session.
> isTransacted | The function stores the property value in this location.

> Remarks
> When true, then the session has transaction semantics, and the session’s acknowledge mode is irrelevant.
> When false, it has non-transaction semantics.
> tibemsSession_Recover
> Function
> Purpose
> Recover from undetermined state during message processing.
> C Declaration
> tibems_status tibemsSession_Recover(
> tibemsSession session );
> COBOL Call
> CALL "tibemsSession_Recover"
> USING BY VALUE session,
> RETURNING tibems-status
> END-CALL.

> | session has usage pointer.

> Parameters

> Parameter | Description
> session | Recover this session.

> Remarks
> Exceptions during message processing can sometimes leave a program in an ambiguous state. For example, some messages might be partially processed. This function lets a program return to an unambiguous state—the point within the message stream when the program last acknowledged the receipt of inbound messages. Programs can then review the messages delivered since that point (they are marked as redelivered), and resolve ambiguities about message processing.
> Programs can also use this function to resolve similar ambiguities after a tibemsConnection stops delivering messages, and then starts again.
> Operation
> This function requests that the server do this sequence of actions:

> 1. | Stop message delivery within the session.

> 2. | Mark as redelivered, any messages that the server has attempted to deliver to the session, but for which it has not received acknowledgement (that is, messages for which processing state is ambiguous).

> According to the JMS specification, the server need not redeliver messages in the same order as it first delivered them.

> 3. | Restart message delivery (including messages marked as redelivered in step 2).

> Transactions
> When a session has transactional semantics, this call is inappropriate, and returns TIBEMS_INVALID_SESSION (commit and rollback are more appropriate with transactions).
> tibemsSession_Rollback
> Function
> Purpose
> Roll back messages in the current transaction.
> C Declaration
> tibems_status tibemsSession_Rollback(
> tibemsSession session );
> COBOL Call
> CALL "tibemsSession_Rollback"
> USING BY VALUE session,
> RETURNING tibems-status
> END-CALL.

> | session has usage pointer.

> Parameters

> Parameter | Description
> session | Rollback the messages in this session.

> Remarks
> When a session does not have transactional semantics, this function returns TIBEMS_ILLEGAL_STATE.
> Messages sent to a queue with prefetch=none and maxRedelivery=number properties are not received number times by an EMS application that receives in a loop and does an XA rollback after the XA prepare phase.
> tibemsSession_Unsubscribe
> Function
> Purpose
> Unsubscribe a durable topic subscription.
> C Declaration
> tibems_status tibemsSession_Unsubscribe(
> tibemsSession session
> const char* name );
> COBOL Call
> CALL "tibemsSession_Unsubscribe"
> USING BY VALUE session,
> BY REFERENCE name,
> RETURNING tibems-status
> END-CALL.

> | session has usage pointer.

> Parameters

> Parameter | Description
> session | Delete a subscription in this session.
> name | This name lets the server locate the subscription.

> Remarks
> This function deletes the subscription from the server.

> | You must unsubscribe before closing the session. It is illegal to delete an active subscription—that is, while a tibemsMsgConsumer exists. It is illegal to delete a subscription while one of its messages is either unacknowledged, or uncommitted (in the current transaction). Attempting to do so results in a status of TIBEMS_EXCEPTION.

> See Also
> tibemsMsgConsumer on page 162
> tibemsTopic on page 156
> tibemsSession_CreateDurableSubscriber on page 295

Copyright © TIBCO Software Inc. All Rights Reserved.