MQCreateSession

The MQCreateSession function creates a session, defines its behavior, and passes back a handle to the session.

MQCreateSession(const MQConnectionHandle connectionHandle,
                 MQBool isTransacted,
                 MQAckMode acknowledgeMode,
                 MQReceiveMode receiveMode
                 MQSessionHandle * sessionHandle);

Return Value

MQStatus. See the MQStatusIsError() function for more information.

Parameters

connectionHandle

The handle to the connection to which this session belongs. This handle is passed back to you by the MQCreateConnection() function. You can create multiple sessions on a single connection.

isTransacted

An MQBool specifying whether this session is transacted. Specify MQ_TRUE if the session is transacted. In this case, the acknowledgeMode parameter is ignored.

acknowledgeMode

An enumeration of the possible kinds of acknowledgement modes for the session. See Acknowledge Modes for information on these values.

After you have created a session, you can determine its acknowledgement mode by calling the MQGetAcknowledgeMode() function.

receiveMode

An enumeration specifying whether this session will do synchronous or asynchronous message receives. Specify MQ_SESSION_SYNC_RECEIVE or MQ_SESSION_ASYNC_RECEIVE.

If the session is only for producing messages, the receiveMode has no significance. In that case, specify MQ_SESSION_SYNC_RECEIVE to optimize the session’s resource use.

sessionHandle

A handle to this session. You will need to pass this handle to the functions you use to manage the session and to create destinations, consumers, and producers associated with this session.

The MQCreateSession function creates a new session and passes back 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. A session is a single-thread context for producing and consuming messages. You can create multiple producers and consumers for a session, but you are restricted to use them serially. In effect, only a single logical thread of control can use them.

A session with a registered message listener is dedicated to the thread of control that delivers messages to the listener. This means that if you want to send messages, for example, you must create another session with which to do this. The only operations you can perform on a session with a registered listener, is to close the session or the connection.

After you create a session, you can create the producers, consumers, and destinations that use the session context to do their work.

• For a session that is not transacted, use the MQRecoverSession() function to restart message delivery with the last unacknowledged message.

• For a session that is transacted, use the MQRollBackSession() function to roll back any messages that were delivered within this transaction. Use the MQCommitSession() function to commit all messages associated with this transaction.

• For a session that has acknowledgeMode set to MQ_CLIENT_ACKNOWLEDGE, use the function MQAcknowledgeMessages to acknowledge consumed messages.

• Use the MQCloseSession() function to close a session and all its associated producers and consumers. This function also frees memory allocated for the session.