Loop List Action

Declaration

<AMLOOPLIST LIST="text [list]" RESULTVARIABLE="text [varname]" DELIMITER="text [options]" SORT="text [options]">
  (block of steps to loop)

See Also

Loop, Loop Files, Loop Windows, Loop Processes, Loop Expression, Loop Dataset, Break, End Loop

Description

Loops through items in a list (comma, carriage return, or other delimited text). With each successive loop a block of steps is executed and the current index variable is updated with the next item in the list. The loop ends when at the end of the list or when a Break is encountered.

Practical Usage

To loop a block of steps through the records (rows) in a list (which is a variable containing multiple rows of data). With each loop the current record (row) in the list is incremented, until the last row is reached at which point the loop is ended.

Parameters

General Tab

List

Text, Required
MARKUP: LIST="Dustin,Scott,Jeff,Kirsten"

Specifies a list of data to Loop through. The List can be delimited by a variety of characters.

Variable Name

Number, Optional Default - 0
MARKUP: RESULTVARIABLE="VARNAME"

Specifies the variable to populate with the current list item. With each successive loop, this variable will be populated with the next item in the list.

Delimiter

Text, Optional - Default - Comma
MARKUP: DELIMITER="new_line"

Specifies the character that delimits the items in the list.

The available options are:

Advanced Tab

Output List

Text [options], Optional (default "none")
MARKUP: SORT="ascending"

Specifies whether a sort order should be applied to the values before the loop begins. For example, selecting "ascending" would return the list items in alphabetical order.

The available options are:

Notes

Custom Description

This action includes the Description tab for entering a custom step description.

More on setting custom step description

Standard Error Handling Options

This action also includes the standard Error Causes and On Error failure handling options/tabs.

More on Error Handling Options

Variables and Expressions

All text fields allow the use of expressions, which can be entered by surrounding the expression in percentage signs (example: %MYVARIABLE%, %Left('Text',2)%). To help construct these expressions, you can open Expression Builder from these fields by pressing F2.

More on variables
More on expressions

More on the expression builder

Examples

NOTE: The code below can be copied and pasted directly into the Steps pane of the Task Builder.

<AMVARIABLE NAME="thenames">Dustin,Scott,Jeff,Kirsten</AMVARIABLE>
<AMVARIABLE NAME="currentitem"></AMVARIABLE>
<AMLOOPLIST LIST="%thenames%" RESULTVARIABLE="currentitem">
<AMMESSAGEBOX>%currentitem%</AMMESSAGEBOX>
</AMLOOP>

<!--- This task shows reading in a file with multiple lines. Each line of the file is treated as a list item. To use it, you must create a  text file called c:\thelistfile.txt and add a few lines to it--->
<AMVARIABLE NAME="filecontents"></AMVARIABLE>
<AMVARIABLE NAME="currentitem"></AMVARIABLE>
<AMFILEREAD FILE="c:\thelistfile.txt" RESULTVARIABLE="filecontents">
<AMLOOPLIST LIST="%filecontents%" RESULTVARIABLE="currentitem" DELIMITER="new_line">
<AMMESSAGEBOX>%currentitem%</AMMESSAGEBOX>
</AMLOOP>