Share via

3.1.4.13 R_QMEnlistTransaction (Opnum 15)

  • Article

A client calls the R_QMEnlistTransaction method to enlist the supporting server's resource manager (RM) in an external transaction.

 HRESULT
 R_QMEnlistTransaction(
     [in] handle_t hBind,
     [in] XACTUOW* pUow,
     [in, range(0, 131072)] DWORD cbCookie,
     [in, size_is (cbCookie)]  unsigned char* pbCookie 
     );

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

pUow:  MUST point to an XACTUOW structure ([MS-MQMQ] section 2.2.18.1.8) that identifies the external transaction in which the server is to enlist, as specified in section 2.2.3.1.

cbCookie:  MUST be set to the byte length of the buffer pointed to by pbCookie.

pbCookie: MUST be a pointer to an array of bytes containing an exported transaction cookie, which can be obtained as specified in [MS-DTCO] section 3.3.4.14.

Return Values:  On success, this method MUST return MQ_OK (0x00000000); otherwise, the server MUST return a failure HRESULT,<43> and the client MUST treat all failure HRESULTs identically.

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:

  • 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:

    • The transaction has already been enlisted. Take no further action and return MQ_OK (0x00000000).

  • Else:

    • Raise the Importing a Transaction event as specified in [MS-DTCO] section 3.3.4.6. Provide pbCookie as the STxInfo structure.

    • Raise the Enlisting on a Specific Transaction event as specified in [MS-DTCO] section 3.5.4.3. Provide the transaction object that was created while importing the transaction in the previous step as the transaction object argument to this event.

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

      • iTransactionIdentifier := pUow

  • Return MQ_OK (0x00000000).