Share via

3.1.7.1.13 Read Message By Lookup Identifier

  • 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 the message is read.

  • iLookupId: The value of the LookupIdentifier ADM attribute of the Message (section 3.1.1.12) ADM element instance to be dequeued.

  • iPeekOperation: A Boolean that specifies whether the message MUST NOT be removed from the queue after being read.

  • iLookupOperation: A MessageSeekAction value.

  • 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. This argument MUST NOT be supplied if the iPeekOperation argument is True.

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

Return Values:

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

    • MQ_OK (0x00000000)

    • MQ_ERROR_MESSAGE_ALREADY_RECEIVED (0xC00E001D)

    • MQ_ERROR_QUEUE_NOT_AVAILABLE (0xC00E004B)

  • rMessage: A reference to the Message 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.

  • Set iQueue to iQueueDesc.QueueReference.

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

  • Generate a Seek Available Message Position With Id (section 3.1.7.3.3) event with the following arguments:

    • iQueue := iQueue

    • iLookupid := iLookupid

    • iPeekOperation := iPeekOperation

    • iLookupAction := iLookupOperation

  • Set iPosition to the returned rMessagePosition.

  • If rStatus returned from the Seek Available Message Position With Id event is not MQ_OK:

    • Set rStatus to the status code returned from the Seek Available Message Position With Id event.

    • Take no further action

  • After the preceding rules are successfully processed, iPosition references a MessagePosition ADM element instance in iQueue.MessagePositionList where the State ADM attribute equals Available or Locked.

  • If the iPeekOperation argument is False:

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

          • OperationType :=  Dequeue.

          • MessagePositionReference := iPosition.

          • DequeueReason := AckReceive.

        • Add the 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.