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); |
MQStatus. See the MQStatusIsError() function for more information.
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.
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.
A callback function before asynchronous message delivery.
A callback function after asynchronous message delivery.
A data pointer to be passed to the beforeDelivery and afterDelivery functions.
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 beforeMessageListener 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.
During normal processing, the C-API runtime:
Calls the beforeMessageListener function.
Processes the message, calling the messageListener function.
Calls the afterMessageListener function.
However, errors can alter this processing sequence:
If the beforeMessageListener function returns an error (a value other than MQ_OK), the C-API runtime logs a warning message containing the error code and then stops processing the message. It does not call messageListener or afterMessageListener.
If the attempt to call messageListener fails, or if message acknowledgement fails, the C-API runtime passes the appropriate error code to afterMessageListener.
If the messageListener function returns an error, the C-API runtime logs a warning containing the error code and then passes the MQ_CALLBACK_RUNTIME_ERROR error to afterMessageListener, regardless of the actual error code returned.
If the afterMessageListener function returns an error, the C-API runtime logs a warning containing the error code.
Even if an error occurs, the callbackData parameter is passed to the beforeMessageListener and afterMessageListener functions unchanged.
MQ_NOT_XA_CONNECTION MQ_INVALID_RECEIVE_MODE MQ_BROKER_CONNECTION_CLOSED MQ_COULD_NOT_CREATE_THREAD