3.1.7.3.3 Seek Available Message Position With Id

  • Article

This event MUST be generated with the following arguments:

  • iQueue: A reference to the Queue (section 3.1.1.2) ADM element instance in which the iteration occurs.

  • iLookupId: A value that contains the LookupIdentifier ADM attribute of the Message (section 3.1.1.12) ADM element instance that is to be read from the queue.

  • iPeekOperation: A Boolean that indicates whether this seek is for a non-destructive read operation.

  • iLookupAction: A MessageSeekAction enumerated value.

Return Values:

  • rMessagePosition: A reference to a MessagePosition (section 3.1.1.11) ADM element instance that is available in iQueue or the special End position defined for the MessagePositionList ADM attribute of a Queue ADM element instance. The End position indicates that no message is available.

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

    • MQ_OK (0x00000000)

    • MQ_ERROR_MESSAGE_ALREADY_RECEIVED (0xC00E001D)

    • MQ_ERROR_MESSAGE_NOT_FOUND (0xC00E0088)

    • MQ_ERROR_TRANSACTION_USAGE (0xC00E0050)

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

  • Set rStatus to MQ_OK.

  • Find the MessagePosition ADM element instance, referred to as iInitialPosition, in iQueue.MessagePositionList such that iInitialPosition.MessageReference.LookupIdentifier is equal to the supplied iLookupId.

  • If no such MessagePosition ADM element instance is found:

    • Set rStatus to MQ_ERROR_MESSAGE_NOT_FOUND.

    • Take no further action.

  • Depending on the value of iLookupAction, perform the following actions:

    • SeekFirst:

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

        • iInitialPosition := Start

        • iQueue := iQueue

        • iPeekOperation := iPeekOperation

        • iSeekDirection := Forward

      • Set rMessagePosition to the rMessagePosition returned by the Seek Available Message Position event.

    • SeekPrevious:

      • Generate a Seek Available Message Position event with the following arguments:

        • iInitialPosition := iInitialPosition

        • iQueue := iQueue

        • iPeekOperation := iPeekOperation

        • iSeekDirection := Backward

      • Set rMessagePosition to the rMessagePosition returned by the Seek Available Message Position event.

    • SeekCurrent:

      • Find the MessagePosition ADM element instance in iQueue.MessagePositionList, referred to as messagePos, for which messagePos.ReferenceMessage.LookupIdentifier equals iLookupId.

      • If no such MessagePosition ADM element instance is found:

        • Set rStatus to MQ_ERROR_MESSAGE_NOT_FOUND.

      • Else if the MessagePosition ADM element instance is found:

        • If messagePos.State is Available:

          • Set rMessagePosition to messagePos.

        • Else if iPeekOperation is True:

          • If messagePos.State is Locked:

            • If messagePos.MessageReference.AllowPeekWhileLocked is True:

              • Set rMessagePosition to messagePos.

            • Else:

              • Set rStatus to MQ_ERROR_TRANSACTION_USAGE.

          • Else if messagePos.State is Deleted:

            • Set rStatus to MQ_ERROR_MESSAGE_ALREADY_RECEIVED.

        • Else:

          • Set rStatus to MQ_ERROR_MESSAGE_NOT_FOUND.

    • SeekNext:

      • Generate a Seek Available Message Position event with the following arguments:

        • iInitialPosition := iInitialPosition

        • iQueue := iQueue

        • iPeekOperation := iPeekOperation

        • iSeekDirection := Forward

      • Set rMessagePosition to the rMessagePosition returned by the Seek Available Message Position event.

    • SeekLast:

      • Generate a Seek Available Message Position event with the following arguments:

        • iInitialPosition := End

        • iQueue := iQueue

        • iPeekOperation := iPeekOperation

        • iSeekDirection := Backward

  • Set rMessagePosition to the rMessagePosition returned by the Seek Available Message Position event.