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.

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

Functions

Summary of functions:
Function Description
xmsSessClose Close the session.
xmsSessCommit Commit all messages processed in the current transaction.
xmsSessCreateBrowser Create a queue browser for the specified queue.
xmsSessCreateBrowserSelector Create a queue browser for the specified queue using a message selector.
xmsSessCreateBytesMessage Create a bytes message.
xmsSessCreateConsumer Create a message consumer for the specified destination.
xmsSessCreateConsumerSelector Create a message consumer for the specified destination using a message selector.
xmsSessCreateConsumerSelectorLocal 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.
xmsSessCreateDurableSubscriber Create a durable subscriber for the specified topic.
xmsSessCreateDurableSubscriberSelector 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.
xmsSessCreateMapMessage Create a map message.
xmsSessCreateMessage Create a message that has no body.
xmsSessCreateObjectMessage Create an object message.
xmsSessCreateProducer Create a message producer to send messages to the specified destination.
xmsSessCreateStreamMessage Create a stream message.
xmsSessCreateTextMessage Create a text message with an empty body.
xmsSessCreateTextMessageInit Create a text message whose body is initialized with the specified text.
xmsSessGetAcknowledgeMode Get the acknowledgement mode for the session.
xmsSessGetTransacted Determine whether the session is transacted.
xmsSessRecover Recover the session.
xmsSessRollback Rollback all messages processed in the current transaction.
xmsSessUnsubscribe Delete a durable subscription.

xmsSessClose – Close Session

Interface:
xmsRC xmsSessClose(xmsHSess *session,
                   xmsHErrorBlock errorBlock);

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:
session (input/output)
On input, the handle for the session. On output, the function returns a null handle.
errorBlock (input)
The handle for an error block or a null handle.
Thread context:
Any
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsSessCommit – Commit

Interface:
xmsRC xmsSessCommit(xmsHSess session,
                    xmsHErrorBlock errorBlock);

Commit all messages processed in the current transaction.

Parameters:
session (input)
The handle for the session. The session must be a transacted session.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_ILLEGAL_STATE_EXCEPTION
  • XMS_X_TRANSACTION_ROLLED_BACK_EXCEPTION

xmsSessCreateBrowser – Create Queue Browser

Interface:
xmsRC xmsSessCreateBrowser(xmsHSess session,
                           xmsHDest queue,
                           xmsHQueueBrowser *browser
                           xmsHErrorBlock errorBlock);

Create a queue browser for the specified queue.

Parameters:
session (input)
The handle for the session.
queue (input)
The handle for a Destination object representing the queue.
browser (output)
The handle for the queue browser.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_INVALID_DESTINATION_EXCEPTION

xmsSessCreateBrowserSelector – Create Queue Browser (with message selector)

Interface:
xmsRC xmsSessCreateBrowserSelector(xmsHSess session,
                                   xmsHDest queue,
                                   xmsCHAR *messageSelector,
                                   xmsINT length,
                                   xmsHQueueBrowser *browser
                                   xmsHErrorBlock errorBlock);

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

Parameters:
session (input)
The handle for the session.
queue (input)
The handle for a Destination object representing the queue.
messageSelector (input)
A message selector expression as a character array. Only those messages with properties that match the message selector expression are delivered to the queue browser.

A value of null or an empty string means that there is no message selector for the queue browser.

length (input)
The length of the message selector expression in bytes. If the message selector expression is null terminated with no embedded null characters, you can specify XMSC_CALCULATE_STRING_SIZE instead and allow XMS to calculate its length.
browser (output)
The handle for the queue browser.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_INVALID_DESTINATION_EXCEPTION
  • XMS_X_INVALID_SELECTOR_EXCEPTION

xmsSessCreateBytesMessage – Create Bytes Message

Interface:
xmsRC xmsSessCreateBytesMessage(xmsHSess session,
                                xmsHMsg *message,
                                xmsHErrorBlock errorBlock);

Create a bytes message.

Parameters:
session (input)
The handle for the session.
message (output)
The handle for the bytes message.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsSessCreateConsumer – Create Consumer

Interface:
xmsRC xmsSessCreateConsumer(xmsHSess session,
                            xmsHDest destination,
                            xmsHMsgConsumer *consumer,
                            xmsHErrorBlock errorBlock);

Create a message consumer for the specified destination.

Parameters:
session (input)
The handle for the session.
destination (input)
The handle for the destination.
consumer (output)
The handle for the message consumer.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_INVALID_DESTINATION_EXCEPTION

xmsSessCreateConsumerSelector – Create Consumer (with message selector)

Interface:
xmsRC xmsSessCreateConsumerSelector(xmsHSess session,
                                    xmsHDest destination,
                                    xmsCHAR *messageSelector,
                                    xmsINT length,
                                    xmsHMsgConsumer *consumer,
                                    xmsHErrorBlock errorBlock);

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

Parameters:
session (input)
The handle for the session.
destination (input)
The handle for the destination.
messageSelector (input)
A message selector expression as a character array. Only those messages with properties that match the message selector expression are delivered to the message consumer.

A value of null or an empty string means that there is no message selector for the message consumer.

length (input)
The length of the message selector expression in bytes. If the message selector expression is null terminated with no embedded null characters, you can specify XMSC_CALCULATE_STRING_SIZE instead and allow XMS to calculate its length.
consumer (output)
The handle for the message consumer.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_INVALID_DESTINATION_EXCEPTION
  • XMS_X_INVALID_SELECTOR_EXCEPTION

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

Interface:
xmsRC xmsSessCreateConsumerSelectorLocal(xmsHSess session,
                                         xmsHDest destination,
                                         xmsCHAR *messageSelector,
                                         xmsINT length,
                                         xmsBOOL noLocal,
                                         xmsHMsgConsumer *consumer,
                                         xmsHErrorBlock errorBlock);

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:
session (input)
The handle for the session.
destination (input)
The handle for the destination.
messageSelector (input)
A message selector expression as a character array. Only those messages with properties that match the message selector expression are delivered to the message consumer.

A value of null or an empty string means that there is no message selector for the message consumer.

length (input)
The length of the message selector expression in bytes. If the message selector expression is null terminated with no embedded null characters, you can specify XMSC_CALCULATE_STRING_SIZE instead and allow XMS to calculate its length.
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.
consumer (output)
The handle for the message consumer.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_INVALID_DESTINATION_EXCEPTION
  • XMS_X_INVALID_SELECTOR_EXCEPTION

xmsSessCreateDurableSubscriber – Create Durable Subscriber

Interface:
xmsRC xmsSessCreateDurableSubscriber(xmsHSess session,
                                     xmsHDest topic,
                                     xmsCHAR *subscriptionName
                                     xmsHMsgConsumer *subscriber,
                                     xmsHErrorBlock errorBlock);

Create a durable subscriber for the specified topic.

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

For more information about durable subscribers, see Durable subscribers.

Parameters:
session (input)
The handle for the session.
topic (input)
The handle for a Destination object representing the topic. The topic must not be a temporary topic.
subscriptionName (input)
A name that identifies the durable subscription. The name must be unique within the client identifier for the connection, and is in the format of a null terminated string.
subscriber (output)
The handle for the MessageConsumer object representing the durable subscriber.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_INVALID_DESTINATION_EXCEPTION

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

Interface:
xmsRC xmsSessCreateDurableSubscriberSelector(xmsHSess session,
                                             xmsHDest topic,
                                             xmsCHAR *subscriptionName
                                             xmsCHAR *messageSelector,
                                             xmsINT length,
                                             xmsBOOL noLocal,
                                             xmsHMsgConsumer *subscriber,
                                             xmsHErrorBlock errorBlock);

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 function is not valid for a real-time connection to a broker.

For more information about durable subscribers, see Durable subscribers.

Parameters:
session (input)
The handle for the session.
topic (input)
The handle for a Destination object representing the topic. The topic must not be a temporary topic.
subscriptionName (input)
A name that identifies the durable subscription. The name must be unique within the client identifier for the connection, and is in the format of a null terminated string.
messageSelector (input)
A message selector expression as a character array. Only those messages with properties that match the message selector expression are delivered to the durable subscriber.

A value of null or an empty string means that there is no message selector for the durable subscriber.

length (input)
The length of the message selector expression in bytes. If the message selector expression is null terminated with no embedded null characters, you can specify XMSC_CALCULATE_STRING_SIZE instead and allow XMS to calculate its length.
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.
subscriber (output)
The handle for the MessageConsumer object representing the durable subscriber.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_INVALID_DESTINATION_EXCEPTION
  • XMS_X_INVALID_SELECTOR_EXCEPTION

xmsSessCreateMapMessage – Create Map Message

Interface:
xmsRC xmsSessCreateMapMessage(xmsHSess session,
                              xmsHMsg *message,
                              xmsHErrorBlock errorBlock);

Create a map message.

Parameters:
session (input)
The handle for the session.
message (output)
The handle for the map message.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsSessCreateMessage – Create Message

Interface:
xmsRC xmsSessCreateMessage(xmsHSess session,
                           xmsHMsg *message,
                           xmsHErrorBlock errorBlock);

Create a message that has no body.

Parameters:
session (input)
The handle for the session.
message (output)
The handle for the message.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsSessCreateObjectMessage – Create Object Message

Interface:
xmsRC xmsSessCreateObjectMessage(xmsHSess session,
                                 xmsHMsg *message,
                                 xmsHErrorBlock errorBlock);

Create an object message.

Parameters:
session (input)
The handle for the session.
message (output)
The handle for the object message.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsSessCreateProducer – Create Producer

Interface:
xmsRC xmsSessCreateProducer(xmsHSess session,
                            xmsHDest destination,
                            xmsHMsgProducer *producer,
                            xmsHErrorBlock errorBlock);

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

Parameters:
session (input)
The handle for the session.
destination (input)
The handle for the destination.

If you specify a null handle, 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.

producer (output)
The handle for the message producer.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_INVALID_DESTINATION_EXCEPTION

xmsSessCreateStreamMessage – Create Stream Message

Interface:
xmsRC xmsSessCreateStreamMessage(xmsHSess session,
                                 xmsHMsg *message,
                                 xmsHErrorBlock errorBlock);

Create a stream message.

Parameters:
session (input)
The handle for the session.
message (output)
The handle for the stream message.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsSessCreateTextMessage – Create Text Message

Interface:
xmsRC xmsSessCreateTextMessage(xmsHSess session,
                               xmsHMsg *message,
                               xmsHErrorBlock errorBlock);

Create a text message with an empty body.

Parameters:
session (input)
The handle for the session.
message (output)
The handle for the text message.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsSessCreateTextMessageInit – Create Text Message (initialized)

Interface:
xmsRC xmsSessCreateTextMessageInit(xmsHSess session,
                                   xmsCHAR *text
                                   xmsINT length
                                   xmsHMsg *message,
                                   xmsHErrorBlock errorBlock);

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

Parameters:
session (input)
The handle for the session.
text (input)
A character array containing the text to initialize the body of the text message.
length (input)
The length of the text in bytes. If the text is null terminated with no embedded null characters, you can specify XMSC_CALCULATE_STRING_SIZE instead and allow XMS to calculate its length.
message (output)
The handle for the text message.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsSessGetAcknowledgeMode – Get Acknowledgement Mode

Interface:
xmsRC xmsSessGetAcknowledgeMode(xmsHSess session,
                                xmsINT *acknowledgeMode,
                                xmsHErrorBlock errorBlock);

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:
session (input)
The handle for the session.
acknowledgeMode (output)
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 function returns XMSC_SESSION_TRANSACTED instead.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsSessGetTransacted – Determine Whether Transacted

Interface:
xmsRC xmsSessGetTransacted(xmsHSess session,
                           xmsBOOL *transacted,
                           xmsHErrorBlock errorBlock);

Determine whether the session is transacted.

Parameters:
session (input)
The handle for the session.
transacted (output)
The value is xmsTRUE if the session is transacted. The value is xmsFALSE if the session is not transacted.

For a real-time connection to a broker, the value is always xmsFALSE.

errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION

xmsSessRecover – Recover

Interface:
xmsRC xmsSessRecover(xmsHSess session,
                     xmsHErrorBlock errorBlock);

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:
session (input)
The handle for the session.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_ILLEGAL_STATE_EXCEPTION

xmsSessRollback – Rollback

Interface:
xmsRC xmsSessRollback(xmsHSess session,
                      xmsHErrorBlock errorBlock);

Rollback all messages processed in the current transaction.

Parameters:
session (input)
The handle for the session. The session must be a transacted session.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_ILLEGAL_STATE_EXCEPTION

xmsSessUnsubscribe – Unsubscribe

Interface:
xmsRC xmsSessUnsubscribe(xmsHSess session,
                         xmsCHAR *subscriptionName,
                         xmsHErrorBlock errorBlock);

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 function is not valid for a real-time connection to a broker.

Parameters:
session (input)
The handle for the session.
subscriptionName (input)
The name that identifies the durable subscription. The name is in the format of a null terminated string.
errorBlock (input)
The handle for an error block or a null handle.
Exceptions:
  • XMS_X_GENERAL_EXCEPTION
  • XMS_X_INVALID_DESTINATION_EXCEPTION
  • XMS_X_ILLEGAL_STATE_EXCEPTION

Reference topic

Terms of Use | Rate this page

Last updated: 24 May 2011

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