MQCreateXASession

The MQCreateXASession function creates a distributed transaction (XA) session on an XA connection, defines its behavior, and passes back a handle to the session.

MQCreateXASession(const MQConnectionHandle connectionHandle,
                 MQReceiveMode receiveMode
                 MQMessageListenerBAFunc     beforeMessageListener,
                 MQMessageListenerBAFunc     afterMessageListener,
                 void *                      callbackData,
                 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 MQGetXAConnection function. You can create multiple sessions on a single connection.

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.

beforeMessageListener

A callback function before asynchronous message delivery.

afterMessageListener

A callback function after asynchronous message delivery.

callbackData

A data pointer to be passed to the beforeDelivery and afterDelivery functions.

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.

If receiveMode is MQ_SESSION_SYNC_RECEIVE, pass NULL for beforeMessageListener, afterMessageListener, and callbackData.

The MQCreateXASession function creates a new distributed transaction (XA) session. The connectionHandle must be a XA connection handle.

An XA session is the same as a regular session created by MQCreateSession (see MQCreateSession) except:

• An XA session is always XA transacted and the distributed transaction is managed by a X/Open distributed transaction manager. MQCommitSession and MQRollbackSession should not be called on a XA session.

• Sending/receiving messages with an XA session must be done in an XA transaction.

• If receiveMode is MQ_SESSION_ASYNC_RECEIVE, callback functions beforeMessageListener and afterMessageListener must be specified. beforeMessageListener will be called by the C-API runtime before it calls the messageListener callback; afterMessageListener will be called by the C-API runtime after it calls the messageListener callback.

  The beforeMesageListener and afterMessageListener functions are provided to the application to associate and disassociate the C-API runtime calling thread with an XA transaction, to demarcate XA transactions, and to set appropriate application association context to the calling thread if the application's distributed transaction processing environment requires that.

  The beforeMessageListener callback can return an error to the C-API runtime, however like the MQMessageListenerFunc callback, a well programmed application, should not return runtime error from afterMessageListener callback. On calling afterMessageListener callback, the C-API runtime passes an errorCode to the callback to indicate whether the processing of the message acknowledgement successful (see MQMessageListenerBAFunc type). The callbackData parameter will be passed to the beforeMessageListener and afterMessageListener callback functions unchanged.

Common Errors

MQ_NOT_XA_CONNECTION
MQ_INVALID_RECEIVE_MODE
MQ_BROKER_CONNECTION_CLOSED
MQ_COULD_NOT_CREATE_THREAD