Navigation:  Actions > System >

Loop Action

Previous pageReturn to chapter overviewNext page

The Loop action creates a step to repeat a set of child steps a specific number of times, once for each value in a list, a file, ADO recordset, MSXML node list, dictionary, or forever.


Create one or more child steps of any type (including Subroutine Call actions) and use the macros below to operate on each matching value.  This action can be used with the Read File, Read INI, Read XML actions or any string or macro value to iterate over the contents of a file, a section of an INI file, matching values in an XPath query, a list of values, etc.


Each child step is built once for each value, and the following temporary macros are available (use in child steps to process each iteration value):

LOOP_VALUE: The loop value for the current iteration (empty string for Forever loop type).
LOOP_COUNT: The number of matching values for the last Loop action (-1 for Forever loop type).
LOOP_INDEX: The index of the current iteration (1-based).


Type: The type of loop to perform:

Count: repeats the child steps the number of times specified in the Count field.
List of values: repeats once for each value in the Value field.
File contents: repeats for the contents of a file (using the specified delimiter).
ADO recordset: repeats for each record in an ADO recordset object (the ADO recordset object will be stored in the LOOP_VALUE macro).
MSXML node list: repeats for each node in an MSXML node list (the MSXML node object for the current iteration will be stored in the LOOP_VALUE macro).
Forever repeats the child steps continuously (until aborted or exited with the Exit action or by using the step failure exit build/subroutine option).
Dictionary repeats for each item in a Scripting.Dictionary object (the key for the current iteration will be stored in the LOOP_VALUE macro).


Value: The count, string or array value, filename, or name of a macro containing the ADO recordset, MSXML node list, or Dictionary object to iterate over (required).


Delimiter: The delimiter to split the string for values to iterate over (optional; uses newline or each array element if blank).  This action splits the given value into separate strings and then performs all child steps once for each value.


Process empty values: If checked, even empty values will be processed.


Log value used for each iteration: If checked, each value that is found will be logged.



See the Advanced, Files, Server, XML, and ContinuousIntegration samples for a demonstration of using the Loop action.
This is an iterative action; if used with the Rebuild Selected build action or Test button, the values will be logged, but the child steps will not be processed; see the Methods of Building help topic for other ways to test iterating steps.
A Loop action must be a child of a subroutine step (it can't be the subroutine entry point). Use a Group action as the subroutine entry point and the Loop step as a child of it.