Share via

3.1.4.14 R_QMEnlistInternalTransaction (Opnum 16)

  • Article

A client calls the R_QMEnlistInternalTransaction method to enlist the supporting server's resource manager (RM) in an internal transaction. The server returns a transaction handle associated with the given unit of work identifier (XACTUOW). The returned transaction handle is used when calling R_QMCommitTransaction or R_QMAbortTransaction. The XACTUOW structure ([MS-MQMQ] section 2.2.18.1.8) is provided for calls to rpc_ACSendMessageEx and rpc_ACReceiveMessageEx of the qmcomm2 RPC interface.

 HRESULT R_QMEnlistInternalTransaction(
   [in] handle_t hBind,
   [in] XACTUOW* pUow,
   [out] RPC_INT_XACT_HANDLE* phIntXact
 );

hBind:  MUST be set to an RPC binding handle as described in [MS-RPCE] section 2.

pUow:  MUST point to an XACTUOW structure that uniquely identifies the internal transaction in which the server is to enlist.<44>

phIntXact:  A pointer to receive the new RPC_INT_XACT_HANDLE which represents the new internal transaction context.

Return Values:  On success, this method MUST return MQ_OK (0x00000000); otherwise, the server MUST return a failure HRESULT, and the client MUST treat all failure HRESULTs identically. Additionally, if a failure HRESULT is returned, the client MUST disregard all out-parameter values.

Exceptions Thrown: No exceptions are thrown beyond those thrown by the underlying RPC protocol, as specified in [MS-RPCE].

This method is invoked at the dynamically assigned endpoint returned by the R_QMGetRTQMServerPort method when IP_HANDSHAKE (0x00000000) or IPX_HANDSHAKE (0x00000002) is the interface specified by the fIP parameter.

When processing this call, the server MUST:

  • Determine if input parameter values violate constraints specified above. If an invalid parameter is detected, the server MUST take no further action and return a failure HRESULT.

  • Look up a Transaction ([MS-MQDMPR] section 3.1.1.14) ADM element instance in the server's LocalQueueManager.TransactionCollection where Transaction.Identifier matches the pUow parameter.

  • If found:

    • Take no further action and return MQ_ERROR_TRANSACTION_SEQUENCE (0xC00E0051).

  • Else:

    • Generate a Create Transaction ([MS-MQDMPR] section 3.1.7.1.8) event with the following argument value:

      • iTransactionIdentifier := pUow

    • The Create Transaction event returns a reference to a Transaction ADM element instance rTransaction.

    • Declare iNewTransactionHandle as a TransactionHandle (section 3.1.1.10) ADM element instance and set its attributes to the following values:

      • Handle := A new RPC_INT_XACT_HANDLE context handle.

      • TransactionReference := rTransaction

    • Add iNewTransactionHandle to iTransactionHandleTable.

    • Set the phIntXact parameter to iNewTransactionHandle.Handle.

  • Return MQ_OK (0x00000000).