3.7.4.1.1 BeginTransaction (Opnum 7)

The BeginTransaction method is received by the server in an RPC_REQUEST packet. In response, the server initiates a new external transaction. This method returns an IMSMQTransaction3 object that represents the underlying newly-created transaction.

 HRESULT BeginTransaction(
   [out, retval] IMSMQTransaction3** ptransaction
 );

ptransaction: A pointer to an IMSMQTransaction3 pointer that represents the newly-created transaction.

Return Values: The method MUST return S_OK (0x00000000) to indicate success or an implementation-specific error HRESULT on failure.<28>

When the server processes this call, it MUST follow these guidelines:

  • Initiate a new distributed transaction by using the distributed transaction manager. For more details about beginning a new distributed transaction, refer to [MS-DTCO] sections 2.2.8.1.2.2 and 3.3.4.1.1.

  • Retrieve the transaction object that represents the newly-created distributed transaction.<29> Create an instance of the TransactionImpl (section 3.8) class and set its TransactionIdentifier instance variable to the identifier of the newly-created distributed transaction.

  • Set the isInternal instance variable of the created transaction object to False.

  • Generate a Create Transaction event as defined in [MS-MQDMPR] section 3.1.7.1.8 with the following inputs:

    • iTransactionIdentifier = TransactionIdentifier instance variable of the created transaction object.

  • Create an instance of the MSMQTransaction Coclass, and assign the created internal transaction object to the Transaction instance variable of the Coclass instance.

  • Invoke the IUnknown::QueryInterface method, as described in 3.1, on the MSMQTransaction instance with the interface identifier of IMSMQTransaction3 to retrieve a pointer to its IMSMQTransaction3 interface.

  • Set the ptransaction output variable to the retrieved pointer to the IMSMQTransaction3 interface.