Sun Java System Message Queue 4.3 Developer's Guide for C Clients

Working With Sessions and Destinations

A session is a single-threaded context for producing and consuming messages. You can create multiple producers and consumers for a session, but you are restricted to using them serially. In effect, only a single logical thread of control can use them. A session supports reliable delivery through acknowledgment options or by using transactions.

Table 2–4 describes the functions you use to create and manage sessions.

Table 2–4 Functions Used to Work with Sessions




Creates the specified session and passes back a handle to it. 


Passes back the acknowledgement mode of the specified session. 


Stops message delivery and restarts message delivery with the oldest unacknowledged message. (For non-transacted sessions.) 


Rolls back a transaction associated with the specified session. 


Commits a transaction associated with the specified session. 


Closes the specified session. 

Creating a Session

The MQCreateSession function creates a new session and initializes a handle to it in the sessionHandle parameter. The number of sessions you can create for a single connection is limited only by system resources. You can create a session after you have created a connection.

When you create a session, you specify whether it is transacted, the acknowledge mode, and the receive mode. After you create a session, you can create the producers, consumers, and destinations that use the session context to do their work.

Transacted Sessions

If you specify that a session be transacted, the acknowledge mode is ignored. Within a transacted session, the broker tracks sends and receives, completing these operations only when the client issues a call to commit the transaction. If a send or receive operation fails, the operation will return an error. Your application can handle the error by ignoring it, retrying it, or rolling back the entire transaction. When a transaction is committed, all the successful operations are completed. When a transaction is rolled back, all the successful operations are cancelled. A transaction cannot encompass both the production and consumption of the same message.

The scope of a local transaction is a single session. One or more producer or consumer operations can be grouped into a single local transaction only if performed in the context of a single session.

To extend the scope of a transaction beyond a single session, you can use a distributed transaction. A distributed transaction is managed by an external distributed transaction manager, as described in Working With Distributed Transactions.

Message Acknowledgement





Note –


Receive Mode

You can specify a session’s receive mode as either MQ_SESSION_SYNC_RECEIVE or MQ_SESSION_ASYNC_RECEIVE. If the session you create will be used for sending messages only, you should specify MQ_SESSION_SYNC_RECEIVE for its receive mode for optimization because the asynchronous receive mode automatically allocates an additional thread for the delivery of messages it expects to receive.

Managing a Session



Creating Destinations


Table 2–5 Functions Used to Work with Destinations




Creates a destination and initializes a handle to it. 


Creates a temporary destination and initializes a handle to it. 






Programming Domains


Auto-Created Destinations


Temporary Destinations



Getting Information About Destinations
