3.2.4.4.2 Receive a Message with a Transaction

  • Article

  • The message queuing application MUST specify a transaction identifier for a Receive a Message With a Transaction event. If the message queuing application has not previously done so, it MUST enlist the server in a transaction by generating an Enlisting in a Transaction (section 3.2.4.2) event.

  • The client MUST call the R_StartTransactionalReceive (Opnum 13) (section 3.1.4.13) method and MUST specify the following parameter values:

    • phContext set to a QUEUE_CONTEXT_HANDLE_NOSERIALIZE (section 2.2.4.1) RPC context handle that has been returned by the server in the pphQueue output parameter of a prior call to the R_OpenQueue (Opnum 2) (section 3.1.4.2) method and that MUST NOT have been previously closed through a call to the R_CloseQueue (Opnum 3) (section 3.1.4.3) method. This value MUST NOT be NULL.

    • hCursor set to NULL.

    • ulAction set to the value specified by the message queuing application.

    • LookupId set to the value specified by the message queuing application.

    • ulTimeout set to the time-out value specified by the message queuing application.

    • dwMaxBodySize set to the value specified by the message queuing application.

    • dwRequestId set to a value that uniquely identifies this call from all other pending calls to this protocol.

    • pTransactionId set to the transaction identifier specified by the message queuing application.

  • Let readAck be a DWORD value initialized to RR_ACK (0x00000002).

  • The client MUST reconstruct the message from the SectionBuffers (section 2.2.6) structure received in the ppPacketSections parameter, as specified in the R_StartTransactionalReceive method. If the message cannot be reconstructed, the client MUST set readAck to RR_NACK (0x00000001).

  • If the R_StartTransactionalReceive method was invoked with a Receive action type, as specified in the ulAction parameter, then the client MUST advise the server that the message has been received by the client by calling the R_EndTransactionalReceive (Opnum 15) (section 3.1.4.15) method with:

    • The same phContext parameter as in the call to the R_StartTransactionalReceive method.

    • dwAck := readAck.

    • The same dwRequestId parameter as in the call to the R_StartTransactionalReceive method.

  • If MQ_OK (0x00000000) is returned:

    • The client MUST return the reconstructed message to the message queuing application.

  • Else if the return value is not MQ_OK:

    • The client MUST return the value to the message queuing application.