3.1.7.3.1 Wait For New Message

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 (section 3.1.1.2) ADM element instance on which this event waits.

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

• iDestructiveRead: A Boolean value that when True indicates that the generator of this event will destructively consume the new message.

• iTag (Optional): A unique identifier passed by the invoker of this event that identifies this particular wait request

• iCursor (Optional): A reference to a Cursor (section 3.2) ADM element instance that is associated with this wait request.

Return Values:

• rStatus: A status code indicating whether a new message was successfully retrieved that can be one of the following:

  • Success

  • Failed

• rMessagePosition: A reference to the MessagePosition (section 3.1.1.11) ADM element instance that has become available in iQueueDesc. If rStatus is not MQ_OK (0x00000000), the value of this argument is undefined.

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

• If iQueueDesc.QueueReference is NULL:

  • Set rStatus to Failed.

  • Take no further action.

• If the iTimeout argument is less-than-or-equal-to zero (0):

  • Set rStatus to Failed.

  • Take no further action.

• Else:

  • Create a new WaitingMessageReadOperation (section 3.1.1.10) ADM element instance, referred to as readOp, with the following ADM attribute values:

    • DestructiveRead := iDestructiveRead.

    • Tag := iTag or NULL if iTag is not supplied

    • CursorReference := iCursor or NULL if iCursor is not supplied

  • Add the new WaitingMessageReadOperation ADM element instance to iQueueDesc.WaitingMessageReadOperationCollection.

  • Generate a Waiting Message Read Timer Start (section 3.1.7.3.4) event with the following arguments:

    • iReader := readOp

    • iTimeout = iTimeout

  • Wait for one of the following events to occur:

    • Waiting Message Read Timer Stop (section 3.1.7.3.5) (where iReader is equivalent to the readOp created preceding):

      • Set rStatus to rStatus returned from the Waiting Message Read Timer Stop event.

    • Waiting Message Read Satisfied (section 3.1.7.3.6) (where iReader is equivalent to the readOp created preceding):

      • Set rStatus to Success.

      • Set rMessagePosition to iPosition from the Waiting Message Read Satisfied event.

  • Cancel the Waiting Message Read Timer (section 3.1.2.3) created preceding.

  • Delete the WaitingMessageReadOperation ADM element instance from iQueueDesc.WaitingMessageReadOperationCollection.