Loop - List

Declaration

<AMLOOP ACTIVITY="list" LIST="text" DELIMITER="text (options)theFile">

Description: Loops through delimited items in a list. The current index variable is updated with the next item in the list. With each loop the current item in the list is returned. The loop process ends when the last delimited item is reached or when a Break is encountered.

Practical Usage

Normally used in conjunction with the Read from file activity to perform operations on delimited text. Note that in certain situations, a Loop file contents activity may be preferable due to the fact that it combines the functionality of both the 'Read from file' and 'Loop list' activities into a single activity.

General Parameters

Property

Type

Required

Default

Markup

Description

List

Text

Yes

(Empty)

LIST="Item1,Item2,Item3"

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

Populate variable with list item

Text

Yes

(Empty)

RESULTVARIABLE="varname"

The name of 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 (options)

No

Comma

  1. DELIMITER="comma"

  2. DELIMITER="new_line"

  3. DELIMITER="semi-colon"

  4. DELIMITER="space"

  5. DELIMITER="tab"

The character used to delimit the items in the list. The available options are:

  • Comma - The delimiter is a comma (Example: item1,item2,item3).

  • New line - The delimiter is a new line.

  • Semi colon - The delimiter is a semi colon (Example: item1;item2;item3).

  • Space - The delimiter is a space (Example: item1 item2 item3).

  • Tabulation - The delimiter is a tab character.

  • Custom - The delimiter is another character as specified (enter the desired character in the provided text-box).

Advanced Parameters

Property

Type

Required

Default

Markup

Description

Output list sort order

Text  (options)

No

None

  1. SORT="none"

  2. SORT="ascending"

  3. SORT="descending"

Specifies the sort order that should be applied towards the list before the loop begins. The available options are:

  • None (default) - No sorting will be applied.

  • Ascending alphabetical order - The list will be sorted in ascending alphabetical order (A-Z).

  • Descending alphabetical order - The list will be sorted in descending alphabetical order (Z-A).

Description tab - A custom description can be provided on the Description tab to convey additional information or share special notes about a task step.

Error Causes tab - Specify how this step should behave upon the occurrence of an error. (Refer to Task Builder > Error Causes Tab for details.)

On Error tab - Specify what AWE should do if this step encounters an error as defined on the Error Causes tab. (Refer to Task Builder > On Error Tab for details.)

Examples

The sample AML code below can be copied and pasted directly into the Steps panel of the Task Builder.

Sample 1 - This task loops through comma delimited text and displays each delimited item in a message box during each loop process.   

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

Sample 2 - 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 of text to it.

<AMVARIABLE NAME="filecontents"></AMVARIABLE>
<AMVARIABLE NAME="currentitem"></AMVARIABLE>
<AMFILEREAD FILE="c:\thelistfile.txt" RESULTVARIABLE="filecontents" />
<AMLOOP TYPE="LIST" LIST="%filecontents%" RESULTVARIABLE="currentitem" DELIMITER="new_line">
<AMMESSAGEBOX>%currentitem%</AMMESSAGEBOX>
</AMLOOP>