Loop - Array

Declaration

<AMLOOP ACTIVITY="array" DIRECTION="text (options)" 
ARRAY="text" RESULTVARIABLE="text" DATASET="text">

Description: Loops through an array, populating the specified variable with the current element. This activity supports looping the array “horizontally” (row by row, column by column) or “vertically” (column by column, row by row). It also supports any size array of any dimensions and can optionally populate a dataset with the array name and current index.

Practical Usage

Used to perform one or more operations on each element of data in an array.

General Parameters

Property

Type

Required

Default

Markup

Description

Array

Text

Yes

(Empty)

ARRAY="myarray"

The name of the array to loop. The array must be created and populated in a previous step using the Create Array activity and the Set Variable activity.

Store each array element in variable

Text

Yes

(Empty)

RESULTVARIABLE="varname"

The name of an existing variable that should be populated with the next data element on each successive loop.

Store array indices in dataset

Text

No

(Empty)

DATASET="ArrayIndex"

If enabled, specifies the name of a dataset to be created and populated with the array name and current index. This parameter is disabled by default.

Loop order (multi-dimensional arrays)

Number

No

Horizontal

DIRECTION="vertical"

The direction of the loop. The available options are: 

  • First dimension first (Horizontal) (default) - Loop is performed row by row, column by column.

  • Last dimension first (Vertical) - Loop is performed column by column, row by row.

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.)

Example

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

Description:This sample task demonstrates two-dimensioned arrays with loops, as well as the Ubound function which returns the highest index of a variable that holds an array of values. In order for this task to function properly, a folder named "test" must exist in the root of c:\ (example: c:\test\) with a few files in it. The Array has a row for each file in the folder. Three columns hold the filename, size and date.

<!-- Sample With Loops using two-dimentions 
(requires a folder called c:\test\ with a few files in it). 
Array has a row for each file in the folder. 
3 colums hold filename, 
size and date. -->
<AMVARIABLE NAME="thefilename">
</AMVARIABLE>
<AMVARIABLE NAME="counter">
</AMVARIABLE>
<AMARRAY NAME="myarray" ROWS="%FileCount('c:\test\')%" 
COLUMNS="3" 
DESCRIPTION="array to hold filename size and date" />
<AMLOOP ACTIVITY="folder" FOLDER="c:\test\" 
RESULTVARIABLE="thefilename">
<AMINCREMENTVARIABLE RESULTVARIABLE="counter" />
<AMSET VARIABLENAME="myarray(%counter%, 
1)">%thefilename%</AMSET>
<AMSET VARIABLENAME="myarray(%counter%, 
2)">%FileLen(thefilename)%</AMSET>
<AMSET VARIABLENAME="myarray(%counter%, 
3)">%FileDateTime(thefilename)%</AMSET>
</AMLOOP>
<AMLOOP TOTALLOOPS="%UBound(myarray, 
1)%" RESULTVARIABLE="counter">
<AMMESSAGEBOX>Filename: %myarray(counter, 1)%
File Size: %myarray(counter, 2)%
File Date: %myarray(counter, 3)%</AMMESSAGEBOX>
</AMLOOP>