Share via

3.1.7.1.10 Dequeue Message

  • Article

This event MUST be generated with the following arguments:

  • iQueueDesc: A reference to an OpenQueueDescriptor (section 3.1.1.16) ADM element instance that specifies the queue from which a message is dequeued.

  • iTimeout (Optional): The amount of time to wait in seconds.

  • iCursor (Optional): A reference to a Cursor (section 3.2) ADM element instance that is used for the dequeue operation.

  • iTransaction (Optional): A reference to a Transaction (section 3.1.1.14) ADM element instance that provides the unit of work for the dequeue operation.

  • iTag (Optional): An identifier passed by the invoker of the Dequeue Message event that uniquely identifies the dequeue operation request.

  • iTwoPhaseRead (Optional): A Boolean that specifies whether the dequeue operation MUST NOT delete the message that was returned. The default for this argument is False.

The iTransaction and iTwoPhaseRead arguments are mutually exclusive. The invoker MUST supply values for only one of these arguments.

Return Values:

  • rStatus: A status code that can be one of the following:

    • MQ_OK (0x00000000)

    • MQ_ERROR_IO_TIMEOUT (0xC00E001B)

    • MQ_ERROR_MESSAGE_NOT_FOUND (0xC00E0088)

    • MQ_ERROR_MESSAGE_ALREADY_RECEIVED (0xC00E001D)

    • MQ_ERROR_QUEUE_NOT_AVAILABLE (0xC00E004B)

  • rMessage: A reference to the Message (section 3.1.1.12) ADM element instance that was dequeued. This value is undefined if rStatus is not MQ_OK.

The queue manager MUST perform the following actions to process this event:

  • If iQueueDesc.QueueReference is NULL:

    • Set rStatus to MQ_ERROR_QUEUE_NOT_AVAILABLE (0xC00E004B).

    • Take no further action.

  • If the iTimeout argument is not specified, set it to Infinite.

  • Define iQueue as a reference to a Queue (section 3.1.1.2) ADM element instance and set it to iQueueDesc.QueueReference.

  • Define iPosition as a MessagePosition (section 3.1.1.11) ADM element reference.

  •  If the iCursor argument is supplied:

    • Generate the Get Next Message For Dequeue (section 3.2.7.4) event on the iCursor argument with the following inputs:

      • iNoWait := True if the iTimeout argument is set to zero or False otherwise.

    • If the rStatus return value from the Get Next Message For Dequeue event is set to Succeeded:

      • Set iPosition to the returned rPosition.

    • Else, if the returned rStatus is set to AlreadyReceived:

      • Set rStatus to MQ_ERROR_MESSAGE_ALREADY_RECEIVED (0xC00E001D).

      • Take no further action.

    • Else, if the returned rStatus is set to NotFound:

      • Set rStatus to MQ_ERROR_MESSAGE_NOT_FOUND (0xC00E0088).

      • Take no further action.

    • Else, if the returned rStatus is set to Waiting:

      • Generate a Wait For New Message (section 3.1.7.3.1) event with the following inputs:

        • iQueueDesc := iQueueDesc

        • iTimeout := iTimeout

        • iDestructiveRead := True

        • If the iTag argument is supplied: iTag := iTag

        • iCursor := iCursor

      • If the rStatus return value from the Wait For New Message event is Success:

        • Set iPosition to the rMessagePosition returned from the Wait For New Message event.

        • Generate the Message Available (section 3.2.7.5) event on the iCursor argument with the following inputs:

          • iMessagePosition := rMessagePosition returned from the Wait For New Message event.

      • Else:

  • Else, if the iCursor argument is not supplied:

    • Generate a Seek Available Message Position (section 3.1.7.3.2) event with the following inputs:

      • iInitialPosition := iQueue.MessagePositionList.Head

      • iQueue:= iQueue

      • iPeekOperation := False

      • iSeekDirection := Forward

        If rMessagePosition returned from the Seek Available Message Position event is equivalent to iQueue.MessagePositionList.End:

        Generate a Wait For New Message event with the following inputs:

      • iQueueDesc := iQueueDesc

      • iTimeout := iTimeout

      • iDestructiveRead := True

      • If the iTag argument is supplied: iTag := iTag

      • iCursor := NULL

    • If the rStatus return value from the Wait For New Message event is Success:

      • Set iPosition to the rMessagePosition return value from the Wait For New Message event.

    • Else:

      • Set rStatus to the rStatus returned from the Wait For New Message event.

      • Take no further action.

  • After the preceding rules are successfully processed, iPosition references a MessagePosition ADM element instance in the iQueue.MessagePositionList for which the value of its State ADM attribute equals Available.

  •  If the iTransaction argument is supplied:

    • If iTransaction.Identifier is not NULL:

      • Set iPosition.State to Locked.

      • Create a new TransactionalOperation (section 3.1.1.13) ADM element instance with the following ADM attribute values:

        • OperationType := Dequeue.

        • MessagePositionReference := iPosition.

        • DequeueReason := AckReceive.

      • Add this new TransactionalOperation ADM element instance to the end of iTransaction.TransactionalOperationCollection.

  • Else:

    • If the iTwoPhaseRead argument is True

      • Set iPosition.State to Locked.

    • Else:

  • Set rMessage to iPosition.MessageReference.

  • Set rStatus to MQ_OK.