WebSphere Message Service Client for C/C++, Version 2.0.2 Operating Systems: AIX, Linux, Solaris, Windows

Session

A session is a single threaded context for sending and receiving messages.

Inheritance hierarchy:
xms::PropertyContext
   |
   +----xms::Session

For a list of the XMS defined properties of a Session object, see Properties of Session.

Methods

Summary of methods:
Method Description
close Close the session.
commit Commit all messages processed in the current transaction.
createBrowser Create a queue browser for the specified queue.
createBrowser Create a queue browser for the specified queue using a message selector.
createBytesMessage Create a bytes message.
createConsumer Create a message consumer for the specified destination.
createConsumer Create a message consumer for the specified destination using a message selector.
createConsumer Create a message consumer for the specified destination using a message selector and, if the destination is a topic, specifying whether the message consumer receives the messages published by its own connection.
createDurableSubscriber Create a durable subscriber for the specified topic.
createDurableSubscriber Create a durable subscriber for the specified topic using a message selector and specifying whether the durable subscriber receives the messages published by its own connection.
createMapMessage Create a map message.
createMessage Create a message that has no body.
createObjectMessage Create an object message.
createProducer Create a message producer to send messages to the specified destination.
createQueue Create a Destination object to represent a queue in the messaging server.
createStreamMessage Create a stream message.
createTemporaryQueue Create a temporary queue.
createTemporaryTopic Create a temporary topic.
createTextMessage Create a text message with an empty body.
createTextMessage Create a text message whose body is initialized with the specified text.
createTopic Create a Destination object to represent a topic.
getAcknowledgeMode Get the acknowledgement mode for the session.
getHandle Get the handle that a C application would use to access the session.
getTransacted Determine whether the session is transacted.
isNull Determine whether the Session object is a null object.
recover Recover the session.
rollback Rollback all messages processed in the current transaction.
unsubscribe Delete a durable subscription.

close – Close Session

Interface:
xmsVOID close();

Close the session. If the session is transacted, any transaction in progress is rolled back.

All objects dependent on the session are deleted. For information about which objects are deleted, see Object Deletion.

If an application tries to close a session that is already closed, the call is ignored.

Parameters:
None
Returns:
Void
Thread context:
Any
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

commit – Commit

Interface:
xmsVOID commit();

Commit all messages processed in the current transaction.

The session must be a transacted session.

Parameters:
None
Returns:
Void
Exceptions:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_ILLEGAL_STATE_EXCEPTION
  • XMS_X_TRANSACTION_ROLLED_BACK_EXCEPTION

createBrowser – Create Queue Browser

Interface:
QueueBrowser createBrowser(const Destination & queue) const;

Create a queue browser for the specified queue.

Parameters:
queue (input)
A Destination object representing the queue.
Returns:
The QueueBrowser object.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_INVALID_DESTINATION_EXCEPTION

createBrowser – Create Queue Browser (with message selector)

Interface:
QueueBrowser createBrowser(const Destination & queue
                           const String & messageSelector) const; 

Create a queue browser for the specified queue using a message selector.

Parameters:
queue (input)
A Destination object representing the queue.
messageSelector (input)
A String object encapsulating a message selector expression. Only those messages with properties that match the message selector expression are delivered to the queue browser.

A null String object means that there is no message selector for the queue browser.

Returns:
The QueueBrowser object.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_INVALID_DESTINATION_EXCEPTION
  • XMS_X_INVALID_SELECTOR_EXCEPTION

createBytesMessage – Create Bytes Message

Interface:
BytesMessage createBytesMessage() const;

Create a bytes message.

Parameters:
None
Returns:
The BytesMessage object.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

createConsumer – Create Consumer

Interface:
MessageConsumer createConsumer(const Destination & destination) const;

Create a message consumer for the specified destination.

Parameters:
destination (input)
The Destination object.
Returns:
The MessageConsumer object.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_INVALID_DESTINATION_EXCEPTION

createConsumer – Create Consumer (with message selector)

Interface:
MessageConsumer createConsumer(const Destination & destination,
                               const String & messageSelector) const;

Create a message consumer for the specified destination using a message selector.

Parameters:
destination (input)
The Destination object.
messageSelector (input)
A String object encapsulating a message selector expression. Only those messages with properties that match the message selector expression are delivered to the message consumer.

A null String object means that there is no message selector for the message consumer.

Returns:
The MessageConsumer object.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_INVALID_DESTINATION_EXCEPTION
  • XMS_X_INVALID_SELECTOR_EXCEPTION

createConsumer – Create Consumer (with message selector and local message flag)

Interface:
MessageConsumer createConsumer(const Destination & destination,
                               const String & messageSelector,
                               const xmsBOOL noLocal) const;

Create a message consumer for the specified destination using a message selector and, if the destination is a topic, specifying whether the message consumer receives the messages published by its own connection.

Parameters:
destination (input)
The Destination object.
messageSelector (input)
A String object encapsulating a message selector expression. Only those messages with properties that match the message selector expression are delivered to the message consumer.

A null String object means that there is no message selector for the message consumer.

noLocal (input)
The value xmsTRUE means that the message consumer does not receive the messages published by its own connection. The value xmsFALSE means that the message consumer does receive the messages published by its own connection. The default value is xmsFALSE.
Returns:
The MessageConsumer object.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_INVALID_DESTINATION_EXCEPTION
  • XMS_X_INVALID_SELECTOR_EXCEPTION

createDurableSubscriber – Create Durable Subscriber

Interface:
MessageConsumer
createDurableSubscriber(const Destination & topic,
                        const String & subscriptionName) const;

Create a durable subscriber for the specified topic.

This method is not valid for a real-time connection to a broker.

For more information about durable subscribers, see Durable subscribers.

Parameters:
topic (input)
A Destination object representing the topic. The topic must not be a temporary topic.
subscriptionName (input)
A String object encapsulating a name that identifies the durable subscription. The name must be unique within the client identifier for the connection.
Returns:
The MessageConsumer object representing the durable subscriber.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_INVALID_DESTINATION_EXCEPTION

createDurableSubscriber – Create Durable Subscriber (with message selector and local message flag)

Interface:
MessageConsumer createDurableSubscriber(const Destination & topic,
                                        const String & subscriptionName;
                                        const String & messageSelector,
                                        const xmsBOOL noLocal) const;

Create a durable subscriber for the specified topic using a message selector and specifying whether the durable subscriber receives the messages published by its own connection.

This method is not valid for a real-time connection to a broker.

For more information about durable subscribers, see Durable subscribers.

Parameters:
topic (input)
A Destination object representing the topic. The topic must not be a temporary topic.
subscriptionName (input)
A String object encapsulating a name that identifies the durable subscription. The name must be unique within the client identifier for the connection.
messageSelector (input)
A String object encapsulating a message selector expression. Only those messages with properties that match the message selector expression are delivered to the durable subscriber.

A null String object means that there is no message selector for the durable subscriber.

noLocal (input)
The value xmsTRUE means that the durable subscriber does not receive the messages published by its own connection. The value xmsFALSE means that the durable subscriber does receive the messages published by its own connection. The default value is xmsFALSE.
Returns:
The MessageConsumer object representing the durable subscriber.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_INVALID_DESTINATION_EXCEPTION
  • XMS_X_INVALID_SELECTOR_EXCEPTION

createMapMessage – Create Map Message

Interface:
MapMessage createMapMessage() const;

Create a map message.

Parameters:
None
Returns:
The MapMessage object.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

createMessage – Create Message

Interface:
Message createMessage() const;

Create a message that has no body.

Parameters:
None
Returns:
The Message object.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

createObjectMessage – Create Object Message

Interface:
ObjectMessage createObjectMessage() const;

Create an object message.

Parameters:
None
Returns:
The ObjectMessage object.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

createProducer – Create Producer

Interface:
MessageProducer createProducer(const Destination & destination) const;

Create a message producer to send messages to the specified destination.

Parameters:
destination (input)
The Destination object.

If you specify a null Destination object, the message producer is created without a destination. In this case, the application must specify a destination every time it uses the message producer to send a message.

Returns:
The MessageProducer object.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_INVALID_DESTINATION_EXCEPTION

createQueue – Create Queue

Interface:
Destination createQueue(const String & queueName) const;

Create a Destination object to represent a queue in the messaging server.

This method does not create the queue in the messaging server. You must create the queue before an application can call this method.

Parameters:
queueName (input)
A String object encapsulating the name of the queue, or encapsulating a uniform resource identifier (URI) that identifies the queue.
Returns:
The Destination object representing the queue.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

createStreamMessage – Create Stream Message

Interface:
StreamMessage createStreamMessage() const;

Create a stream message.

Parameters:
None
Returns:
The StreamMessage object.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

createTemporaryQueue – Create Temporary Queue

Interface:
Destination createTemporaryQueue() const;

Create a temporary queue.

The scope of the temporary queue is the connection. Only the sessions created by the connection can use the temporary queue.

The temporary queue remains until it is explicitly deleted, or the connection ends, whichever is the sooner.

For more information about temporary queues, see Temporary destinations.

Parameters:
None
Returns:
The Destination object representing the temporary queue.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

createTemporaryTopic – Create Temporary Topic

Interface:
Destination createTemporaryTopic() const;

Create a temporary topic.

The scope of the temporary topic is the connection. Only the sessions created by the connection can use the temporary topic.

The temporary topic remains until it is explicitly deleted, or the connection ends, whichever is the sooner.

For more information about temporary topics, see Temporary destinations.

Parameters:
None
Returns:
The Destination object representing the temporary topic.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

createTextMessage – Create Text Message

Interface:
TextMessage createTextMessage() const;

Create a text message with an empty body.

Parameters:
None
Returns:
The TextMessage object.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

createTextMessage – Create Text Message (initialized)

Interface:
TextMessage createTextMessage(const String & text) const;

Create a text message whose body is initialized with the specified text.

Parameters:
text (input)
A String object encapsulating the text to initialize the body of the text message.
None
Returns:
The TextMessage object.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

createTopic – Create Topic

Interface:
Destination createTopic(const String & topicName) const;

Create a Destination object to represent a topic.

Parameters:
topicName (input)
A String object encapsulating the name of the topic, or encapsulating a uniform resource identifier (URI) that identifies the topic.
Returns:
The Destination object representing the topic.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

getAcknowledgeMode – Get Acknowledgement Mode

Interface:
xmsINT getAcknowledgeMode() const;

Get the acknowledgement mode for the session. The acknowledgement mode is specified when the session is created.

A session that is transacted has no acknowledgement mode.

For more information about acknowledgement modes, see Message acknowledgement.

Parameters:
None
Returns:
The acknowledgement mode. Provided the session is not transacted, the acknowledgement mode is one of the following values:
  • XMSC_AUTO_ACKNOWLEDGE
  • XMSC_CLIENT_ACKNOWLEDGE
  • XMSC_DUPS_OK_ACKNOWLEDGE
If the session is transacted, the method returns XMSC_SESSION_TRANSACTED instead.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

getHandle – Get Handle

Interface:
xmsHSess getHandle() const;

Get the handle that a C application would use to access the session.

Parameters:
None
Returns:
The handle for the session.
Thread context:
Any
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

getTransacted – Determine Whether Transacted

Interface:
xmsBOOL getTransacted() const;

Determine whether the session is transacted.

Parameters:
None
Returns:
  • xmsTRUE, if the session is transacted.
  • xmsFALSE, if the session is not transacted.

For a real-time connection to a broker, the method always returns xmsFALSE.

Exceptions:
  • XMS_X_GENERAL_EXCEPTION

isNull – Check Whether Null

Interface:
xmsBOOL isNull() const;

Determine whether the Session object is a null object.

Parameters:
None
Returns:
  • xmsTRUE, if the Session object is a null object.
  • xmsFALSE, if the Session object is not a null object.
Thread context:
Any
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

recover – Recover

Interface:
xmsVOID recover() const;

Recover the session. Message delivery is stopped and then restarted with the oldest unacknowledged message.

The session must not be a transacted session.

For more information about recovering a session, see Message acknowledgement.

Parameters:
None
Returns:
Void
Exceptions:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_ILLEGAL_STATE_EXCEPTION

rollback – Rollback

Interface:
xmsVOID rollback() const;

Rollback all messages processed in the current transaction.

The session must be a transacted session.

Parameters:
None
Returns:
Void
Exceptions:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_ILLEGAL_STATE_EXCEPTION

unsubscribe – Unsubscribe

Interface:
xmsVOID unsubscribe(const String & subscriptionName) const;

Delete a durable subscription. The messaging server deletes the record of the durable subscription that it is maintaining and does not send any more messages to the durable subscriber.

An application cannot delete a durable subscription in any of the following circumstances:
  • While there is an active message consumer for the durable subscription
  • While a consumed message is part of a pending transaction
  • While a consumed message has not been acknowledged

This method is not valid for a real-time connection to a broker.

Parameters:
subscriptionName (input)
A String object encapsulating the name that identifies the durable subscription.
Returns:
Void
Exceptions:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_INVALID_DESTINATION_EXCEPTION
  • XMS_X_ILLEGAL_STATE_EXCEPTION

Inherited methods


Reference topic

Terms of Use | Rate this page

Last updated: 24 May 2011

(C) Copyright IBM Corporation 2005, 2011. All Rights Reserved.