3.1.4.12 R_QMEnlistRemoteTransaction (Opnum 12)

  • Article

The R_QMEnlistRemoteTransaction method propagates a distributed atomic transaction context to the server. The server MUST enlist in the transaction context. The client MUST call this method prior to the R_StartTransactionalReceive (Opnum 13) (section 3.1.4.13) method or the R_MoveMessage (Opnum 10) (section 3.1.4.10) method calls.<27> Subsequent calls to the R_StartTransactionalReceive method and the R_MoveMessage method that use the same transaction identifier are coordinated such that either all occur or none occurs, depending on whether the transaction outcome is Commit or Rollback.

 HRESULT R_QMEnlistRemoteTransaction(
   [in] handle_t hBind,
   [in] XACTUOW* pTransactionId,
   [in, range(0, 131072)] DWORD cbPropagationToken,
   [in, size_is(cbPropagationToken)] 
     unsigned char* pbPropagationToken,
   [in] QUEUE_FORMAT* pQueueFormat
 );

hBind: MUST be an RPC binding handle parameter, as specified in [MS-RPCE] section 2.

pTransactionId: MUST be a pointer to a transaction identifier obtained as specified in [MS-DTCO] section 3.3.4.1. This value MUST NOT be NULL.

cbPropagationToken: MUST be the size, in bytes, of the pbPropagationToken parameter.

pbPropagationToken: MUST be a transaction propagation token, as specified in [MS-DTCO] section 2.2.5.4, that represents the transaction identified by the pTransactionId parameter. This parameter MUST NOT be NULL.

pQueueFormat: MUST be a pointer to a QUEUE_FORMAT ([MS-MQMQ] section 2.2.7) structure that identifies the queue to be passed to the R_StartTransactionalReceive method. SHOULD<28> be ignored by the server.

Return Values: On success, this method MUST return MQ_OK (0x00000000).

If an error occurs, the server MUST return a failure HRESULT, and the client MUST treat all failure HRESULTs identically.

MQ_OK (0x00000000)

Exceptions Thrown:

No exceptions are thrown except those that are thrown by the underlying RPC protocol, as specified in [MS-RPCE].

While processing this operation, the server MUST:

  • Enlist into the transaction as specified in [MS-DTCO] section 3.5.4.3.

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

    • iTransactionIdentifier := pTransactionId

  • Return MQ_OK (0x00000000).