Dequeue Operation

Use the Dequeue operation to remove an element and/or store the data from an element.

The Dequeue operation contains the following options:

• Queue Name or Reference Expression —The queue on which to perform the operation. You can specify the queue by name or by the object reference you receive when you create the queue using the Use Object Reference for the Queue Reference Lifetime option. You can specify multiple queues using either a string array containing the names of the queues, or an object reference array containing ActiveX references to the queues. When you specify multiple queues, the Dequeue operation dequeues an element from the first queue you specify that has an element available. You can ascertain which queue the operation dequeues from by using the Which Queue control to specify a location to store the array offset of the queue.
• Location to Store Element (optional output) —The location in which to store the queue element. Leave this control blank when you do not want to store the data. The type of the location must be compatible with the data the element stores. The following tables illustrate the outcomes depending on the type of the data in the queue and the data type of the storage location. In these tables, Simple Type refers to a number, string, Boolean, or array of any type, and Structured Type refers to an instance of a user-defined type where the root property is a container.

  Table 1. Dequeue Behaviors for Data You Enqueue by Value

  Dequeue Type—Destination	Enqueue Type (By Value)—Source
  Simple Type	Structured Type	Object Reference
  Simple Type	If the types match, Dequeue copies the data to the location you specify. If types do not match, Dequeue reports a type mismatch error.	Type mismatch error.	Type mismatch error.
  Structured Type	Type mismatch error.	Replaces the property you specify as the dequeue location with a copy of the structured value the queue stores.	Type mismatch error.
  Object Reference	Type mismatch error.	Stores an ActiveX reference to the structured value the queue stores.	Copies the ActiveX reference the queue stores to the location you specify.

  Table 1. Dequeue Behaviors for Data You Enqueue by Reference

  Dequeue Type—Destination	Enqueue Type (By Reference)—Source
  Simple Type	Structured Type	Object Reference
  Simple Type	If the types match, Dequeue copies the data to the location you specify. If types do not match, Dequeue reports a type mismatch error.	Type mismatch error.	Type mismatch error.
  Structured Type	Type mismatch error.	Makes a copy of the structured value the queue stores by reference, and replaces the property you specify as the dequeue location with the copy.	Type mismatch error.
  Object Reference	Stores an ActiveX reference to the simple type as it is stored in the queue.	Stores an ActiveX reference to the structured value the queue stores.	Stores an ActiveX reference to the ActiveX reference the queue stores.

• Dequeue From —Specifies where in the queue to dequeue from. The options are Front of Queue and Back of Queue.
• Remove Element —When you enable this option, the operation removes the element from the queue. When you do not enable this option, the operation retrieves the value of the element without removing it from the queue.
• Which Queue? (optional output) —Use this control to specify a location to store the array offset of the queue on which the dequeue operation occurs. Typically, you do not use this control unless you are dequeuing from multiple queues. Refer to the description for the Queue Name or Reference Expression control for this operation for more information about dequeuing with multiple queues.
• Timeout Enabled, Timeout Expression, Timeout Causes Run-Time Error —A timeout behavior when waiting to dequeue an element. If a timeout occurs, the Step.Result.TimeoutOccurred property is set to True .