• Associated ObjectsThe 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).One consequence of this rule is that all the consumers of a session must deliver messages in the same mode—either synchronously or asynchronously.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).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.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.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.
tibems_status tibemsSession_Close(tibemsSession session );
session has usage pointer.Closing a session automatically closes its consumers (except for durable subscribers), producers and browsers.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.tibems_status tibemsSession_Commit(tibemsSession session );
session has usage pointer.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.
The session does not have transaction semantics. The client lacks permission to send one of messages in the transaction. Commit failed and the server automatically rolled back the transaction. tibems_status tibemsSession_CreateBrowser(tibemsSession session,tibemsQueueBrowser* browser,tibemsQueue queue,
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.tibems_status tibemsSession_CreateBytesMessage(tibemsSession session,tibemsBytesMsg* bytesMsg );
session and bytesMsg have usage pointer.
tibems_status tibemsSession_CreateConsumer(tibemsSession session,BY REFERENCE consumer,BY VALUE destination,BY VALUE noLocal,
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 null, or the empty string, the consumer receives messages without filtering. 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.tibems_status tibemsSession_CreateDurableSubscriber(tibemsSession session,tibems_bool noLocal );BY VALUE topic,
session, msgConsumer, and topic have usage pointer.
The function stores the new message consumer object in this location. Note that the message consumer must be a topic subscriber. This unique name lets the server associate the subscriber with a subscription. 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. 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.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
•
• 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.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 SelectorNotice 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).tibems_status tibemsSession_CreateMapMessage(tibemsSession session,tibemsMapMsg* mapMsg );
session and mapMsg have usage pointer.
tibems_status tibemsSession_CreateMessage(tibemsSession session,tibemsMsg* message );
session and message have usage pointer.
tibems_status tibemsSession_CreateProducer(tibemsSession session,tibemsMsgProducer* producer,BY VALUE destination,
When non-null, the producer sends messages to this destination.When null, the client program must specify the destination for each message individually.tibems_status tibemsSession_CreateStreamMessage(tibemsSession session,tibemsStreamMsg* streamMsg );
session and streamMsg have usage pointer.
tibems_status tibemsSession_CreateTemporaryQueue(tibemsSession session,tibemsTemporaryQueue* tmpQueue );
session and tmpQueue have usage pointer.
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.tibems_status tibemsSession_CreateTemporaryTopic(tibemsSession session,tibemsTemporaryTopic* tmpTopic );
session and tmpTopic have usage pointer.
The function stores the new temporary topic object in this location.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.tibems_status tibemsSession_CreateTextMessage(tibemsSession session,tibemsTextMsg* textMsg );tibems_status tibemsSession_CreateTextMessageEx(tibemsSession session,tibemsTextMsg* textMsg
session and textMsg have usage pointer.
tibems_status tibemsSession_DeleteTemporaryQueue(tibemsSession session,tibemsTemporaryQueue tmpQueue );
session and tmpQueue have usage pointer.
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.tibems_status tibemsSession_DeleteTemporaryTopic(tibemsSession session,tibemsTemporaryTopic tmpTopic );
session and tmpTopic have usage pointer.
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.tibems_status tibemsSession_GetAcknowledgeMode(tibemsSession session,tibemsAcknowledgeMode* acknowledgeMode );
session has usage pointer.
This mode governs message acknowledgement and redelivery for consumers associated with the session. For values, see tibemsAcknowledgeMode on page 312.tibems_status tibemsSession_GetTransacted(tibemsSession session,tibems_bool* isTransacted );
session has usage pointer.
When true, then the session has transaction semantics, and the session’s acknowledge mode is irrelevant.When false, it has non-transaction semantics.tibems_status tibemsSession_Recover(tibemsSession session );
session has usage pointer.
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.
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).Commit and rollback are more appropriate with transactions. When a session has transactional semantics, this call is illegal, and returns TIBEMS_INVALID_SESSION.tibems_status tibemsSession_Rollback(tibemsSession session );
session has usage pointer.
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.tibems_status tibemsSession_Unsubscribe(tibemsSession session
session has usage pointer.
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.
Copyright © TIBCO Software Inc. All Rights Reserved.