Session : tibemsSession

tibemsSession
Type
Purpose
Organizing context for message activity.
Remarks
Sessions combine several roles:
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.
 
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.
 
Commit failed and the server automatically rolled back the transaction.
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
 
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
 
See Also
tibemsBytesMsg on page 73
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
 
Create a consumer for this destination. The argument may be any destination (queue or topic).
When non-null, the server filters messages using this selector, so the consumer receives only matching messages; see Message Selectors.
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
 
The function stores the new message consumer object in this location. Note that the message consumer must be a topic subscriber.
When non-null, the server filters messages using this selector, so the subscriber receives only matching messages; see Message Selectors.
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
 
Remarks
The JMS specification requires this call. It is equivalent to tibemsMapMsg_Create on page 90.
See Also
tibemsMapMsg on page 89
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
 
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
 
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
 
Remarks
The JMS specification requires this call. It is equivalent to tibemsStreamMsg_Create on page 110.
See Also
tibemsStreamMsg on page 108
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
 
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
 
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
 
Remarks
The JMS specification requires these calls. It is equivalent to tibemsTextMsg_Create on page 124.
See Also
tibemsTextMsg on page 123
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
 
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
 
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
 
Remarks
This mode governs message acknowledgement and redelivery for consumers associated with the session. For values, see tibemsAcknowledgeMode on page 312.
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
 
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
 
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.
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.
 
Transactions
Commit and rollback are more appropriate with transactions. When a session has transactional semantics, this call is illegal, and returns TIBEMS_INVALID_SESSION.
See Also
tibemsMsg_Recover on page 57
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
 
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
 
Remarks
This function deletes the subscription from the server.
 
You must unsubscribe before closing the session.
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