Use the For Loop and the While Loop to control repetitive operations.
|Note If you open a refnum inside a For Loop or While Loop, close that refnum for each iteration of the loop. Otherwise, LabVIEW repeatedly allocates memory for the refnum and does not free the memory until the VI finishes running.|
Add shift registers to For Loops or While Loops to pass data from the current iteration to the next iteration.
A For Loop, shown as follows, executes a subdiagram a set number of times.
The count terminal, shown as follows, is an input terminal whose value indicates how many times to repeat the subdiagram.
Set the count explicitly by wiring a value from outside the loop to the left or top side of the count terminal, or set the count implicitly with auto-indexing.
The iteration terminal, shown as follows, is an output terminal that contains the number of completed iterations.
The iteration count for the For Loop always starts at zero.
Both the count and iteration terminals are 32-bit signed integers. If you wire a floating-point or fixed-point number to the count terminal, LabVIEW rounds it and coerces it to within range. If you wire 0 or a negative number to the count terminal, the loop does not execute and the outputs contain the default data for that data type.
The parallel instances terminal, shown as follows, is an input terminal whose value specifies the number of loop instances LabVIEW uses to run parallel loop iterations.
When you enable parallel loop iterations on a For Loop, LabVIEW creates copies of the For Loop at compile time to run in parallel. At run time, each loop instance requests a chunk, or group, of iterations. Each loop instance then executes the chunk and requests another chunk until no more chunks exist.
If you wire -1 to the parallel instances terminal on a For Loop, LabVIEW uses all the loop instances to run parallel loop iterations. If you wire 0 to the parallel instances terminal or leave the terminal unwired, LabVIEW determines the number of available logical processors at run time and uses that number of loop instances to run the parallel loop iterations.
The chunk size terminal, shown as follows, is an input terminal whose value specifies the size of the parallel loop iterations.
To display the chunk size terminal, select the Specify partitioning with chunk size (C) terminal option in the Iteration partitioning schedule section in the For Loop Iteration Parallelism dialog box.
To convert a For Loop to a While Loop, right-click the For Loop and select Replace with While Loop from the shortcut menu.
You can add a conditional terminal to configure a For Loop to stop when a Boolean condition or an error occurs. A For Loop with a conditional terminal executes until the condition occurs or until all iterations complete, whichever happens first. For example, if you want a loop to execute a set number of times unless an error occurs, you can use a For Loop with a conditional terminal and wire an error cluster to the conditional terminal, shown as follows.
To add or remove a conditional terminal in a For Loop, right-click the loop border and select Conditional Terminal from the shortcut menu. If you add a conditional terminal to a For Loop, the conditional terminal appears in the bottom right of the loop and the count terminal appearance changes, as shown in the following illustration.
You cannot press the <Delete> key to remove a conditional terminal. In a For Loop with a conditional terminal, you must wire the conditional terminal and either wire a numeric value to the count terminal or auto-index an input array.
The number wired to the count terminal or the number of elements in the auto-indexed input array acts as the maximum number of loop iterations that complete only if the condition wired to the conditional terminal never occurs. If you want a loop to iterate until a condition occurs with no maximum number of iterations, use a While Loop instead.
To configure a conditional terminal, wire Boolean data, such as a Boolean control or an output from a Comparison function, to the conditional terminal. You also can wire an error cluster to the conditional terminal. The default behavior and appearance of the conditional terminal is Stop if True, shown as follows.
If a conditional terminal is Stop if True, the For Loop executes the subdiagram until the conditional terminal receives a TRUE value or until the For Loop completes the number of iterations wired to the count terminal or auto-indexed from an input array. You can change the behavior and appearance of the conditional terminal by right-clicking the terminal and selecting Continue if True, shown as follows, from the shortcut menu.
If a conditional terminal is Continue if True, the For Loop executes the subdiagram until the conditional terminal receives a FALSE value. You also can use the Operating tool to click the conditional terminal to change the condition.
|Note If you wire the conditional terminal in a For Loop, you cannot predetermine the number of iterations the loop executes. You can determine the number of iterations the loop completes by auto-indexing an output array and checking the number of elements after the loop executes or by wiring an indicator to the loop iteration terminal and checking the count after the loop executes.|
Similar to a Do Loop or a Repeat-Until Loop in text-based programming languages, a While Loop, shown as follows, executes a subdiagram until a condition occurs.
The While Loop executes the subdiagram until the conditional terminal, an input terminal, receives a specific Boolean value. The conditional terminal in a While Loop behaves the same as in a For Loop with a conditional terminal. However, because the For Loop also includes a set iteration count, it does not run infinitely if the condition never occurs. The While Loop does not include a set iteration count and runs infinitely if the condition never occurs.
If a conditional terminal is Stop if True, you place the terminal of a Boolean control outside a While Loop, and the control is FALSE when the loop starts, you cause an infinite loop, as shown in the following example. You also cause an infinite loop if the conditional terminal is Continue if True and the control outside the loop is set to TRUE.
To convert a While Loop to a For Loop, right-click the While Loop and select Replace with For Loop from the shortcut menu. (Windows, ETS, VxWorks) To convert a While Loop to a Timed Loop, right-click the While Loop and select Replace with Timed Loop from the shortcut menu.
Changing the value of the control does not stop the infinite loop because the value is only read once, before the loop starts. To stop an infinite loop, you must abort the VI by clicking the Abort Execution button on the toolbar.
You also can perform basic error handling using the conditional terminal of a While Loop. When you wire an error cluster to the conditional terminal, only the True or False value of the status parameter of the error cluster passes to the terminal. Also, the Stop if True and Continue if True shortcut menu items change to Stop if Error and Continue while Error.
The iteration terminal, shown as follows, is an output terminal that contains the number of completed iterations.
The iteration count for the While Loop always starts at zero.
By default, LabVIEW executes loops and block diagrams as quickly as possible. However, you might want to control the rate at which a process executes, such as the rate at which data values are plotted to a chart. You can use a Wait function in the loop to specify the amount of time in milliseconds before the loop re-executes. (Windows, ETS, VxWorks) You also can use a Timed Loop to execute code with time bounds and delays.
If you wire an array to the input tunnel of a For Loop or While Loop, you can read and process every element in that array by enabling auto-indexing.
When you wire an array from an external node to an input tunnel on the loop border and enable auto-indexing on the input tunnel, elements of that array enter the loop one at a time, starting with the first element. When auto-indexing is disabled, the entire array is passed into the loop. When you auto-index an array output tunnel, the output array receives a new element from every iteration of the loop. Therefore, auto-indexed output arrays are always equal in size to the number of iterations. For example, if the loop executes 10 times, the output array has 10 elements. If you disable auto-indexing on an output tunnel, only the element from the last iteration of the loop passes to the next node on the block diagram.
Right-click the tunnel at the loop border and select Enable Indexing or Disable Indexing from the shortcut menu to enable or disable auto-indexing. Auto-indexing for While Loops is disabled by default.
A bracketed glyph appears on the loop border to indicate that auto-indexing is enabled. The thickness of the wire between the output tunnel and the next node also indicates the loop is using auto-indexing. The wire is thicker when you use auto-indexing because the wire contains an array instead of a scalar.
The loop indexes scalar elements from 1D arrays, 1D arrays from 2D arrays, and so on. The opposite occurs at output tunnels. Scalar elements accumulate sequentially into 1D arrays, 1D arrays accumulate into 2D arrays, and so on.
If you enable auto-indexing on an array wired to a For Loop input terminal, LabVIEW sets the count terminal to the array size so you do not need to wire the count terminal. Because you can use For Loops to process arrays one element at a time, LabVIEW enables auto-indexing by default for every array you wire to a For Loop. You can disable auto-indexing if you do not need to process arrays one element at a time.
If you enable auto-indexing for more than one tunnel or if you wire the count terminal, the actual number of iterations becomes the smaller of the choices. For example, if two auto-indexed arrays enter the loop, with 10 and 20 elements respectively, and you wire a value of 15 to the count terminal, the loop still only executes 10 times, indexing all elements of the first array but only the first 10 elements of the second array. As another example, if you plot data from two sources on one graph and you want to plot the first 100 elements, wire 100 to the count terminal. However, if the smaller data source includes only 50 elements, the loop executes 50 times and indexes only the first 50 elements of each data source. Use the Array Size function to determine the size of arrays.
If you enable auto-indexing for an array entering a While Loop, the While Loop indexes the array the same way as a For Loop. However, the number of iterations a While Loop executes is not limited by the size of the array because the While Loop iterates until a specific condition occurs. When a While Loop indexes past the end of the input array, the default value for the array element type passes into the loop. You can prevent the default value from passing into the While Loop by using the Array Size function. The Array Size function indicates how many elements are in the array. Set up the While Loop to stop executing when the number of iterations equals the array size.
|Caution Because you cannot determine the size of the output array in advance, enabling auto-indexing for the output of a For Loop is more efficient than that of a While Loop. Iterating too many times can cause your system to run out of memory.|
In addition to using loops to read and process elements in an array, you also can use the For Loop and the While Loop to build arrays. Wire the output of a VI or function in the loop to the loop border. If you use a While Loop, right-click the resulting tunnel and select Enable Indexing from the shortcut menu. If you use a For Loop, indexing is enabled by default. The output of the tunnel is an array of every value the VI or function returns after each loop iteration.
Refer to the labview\examples\general\arrays.llb for examples of building arrays.
For Loops produce default data if you wire 0 or a negative number to the count terminal of the For Loop or if you wire an empty array to the For Loop as an input with auto-indexing enabled. The loop does not execute, and any output tunnel with auto-indexing disabled contains the default value for the tunnel data type. Use shift registers to transfer values through a loop regardless of whether the loop executes.