Select Configure For Each Loop in the context menu for the step or click Configure For Each Loop on the General tab of the Step Properties dialog box to launch the Configure For Each Loop dialog box from a TestStand User Interface .

The Configure For Each Loop dialog box contains the following options:

• Array/InputRecordStream to Interate Over —The expression that determines the array or InputRecordStream over which the loop iterates. The steps within the block execute once for each element in the array or stream. Choose whether to iterate over an array or a stream by selecting the appropriate option from the Iterate Over Array / Iterate Over Stream dropdown.
• Loop Variables (Optional) — Expressions that determine the location to store information about the current loop interation.
  • Current Element —An expression that determines the variable or property in which to reference the current element in the array or to store the next record from the InputRecordStream during each iteration of the loop.
    • Interating Over Arrays —The location the expression specifies must be of the same type as the element type for the Array to Iterate Over option. Typically, you specify a local variable so the steps in the block can read or modify the current array element by referring to the local variable. The current element reference is valid only while the loop executes, and the reference resets after the loop completes. If the loop prematurely exits, the current element references the array element of the exiting iteration.
    • Interating Over Streams — Current Element must refer to a container or array. Each iteration of the loop updates the value of the Current Element.
  • Current Offset —An expression that determines the numeric variable or property into which to store current offset during each iteration of the loop. For zero-based one-dimensional arrays, the offset is equal to the index of the array. For multi-dimensional arrays, the offset is the linearized index of the array. For streams, the offset is a zero-based counter of the number of loop iterations.
  • Current Subscript —An expression that determines the string variable or property into which to store the subscript of the current element in the Array to Iterate Over option. Examples of the subscripts include [23] and [1][3]. Current Subscript is disabled when Iterate Over Stream is selected.
• Interate Over Array/Interate Over Stream —Specifies if this For Each loop iterates over an array or an InputRecordStream.
• Stream Options —Settings that specify options specific to iterating over streams. These settings are hidden if Iterate Over Array is selected.
  • Field Mapping (Optional) —Specifies which container subproperties or array elements of the Current Element to store fields from the InputRecordStream to.
  • Auto Close at End of File —Check this box to automatically clean up the InputRecordstream being read at the end of the loop. When this box is checked, upon terminating the loop, the For Each step closes the stream and sets the object reference in the InputRecordStream to Iterate Over expression to Nothing.
    Note Automatic cleanup only occurs if the loop terminates normally by encountering end of file (EOF). Cleanup does not occur if execution flow exits the loop for some other reason, for example via a Goto step.

Specifying the Current Element and Mapping When Iterating Over Streams

When iterating over an InputRecordStream, Current Element may be a container or array. If Current Element is a container, the container represents the record, and each subproperty is a field. If Current Element is an array, the array represents the record, and each array element is a field.

Field Mapping specifies the mapping to subproperties or array elements in Current Element from fields in the stream. The mapping is a comma-separated list of index ranges. For example, "0, 3-5, 8-7" specifies that fields from the incoming record be stored to elements 0, 3, 4, 5, 8, and 7 of the container or array. The final range in the list may be open-ended. For example, "2, 3-" specifies that fields from the incoming record be written to elements 2, 3, and all elements beyond 3 of the container or array.

If Current Element is a container, the range list may include individual subproperty names. For example, "Temperature, Pressure, 0-1" specifies that fields from the incoming record be written to the subproperties Temperature and Pressure and then elements 0 and 1.

See Also

Flow Control Step Types

Step Properties dialog box