Array - Create

Declaration

<AMARRAY NAME="text" ROWS="text1" COLUMNS="text2" 
DEPTH="text3" DESCRIPTION="text" TYPE="text" 
PRIVATE="YES/NO" ISPARAMETER="YES/NO" />

Description: Creates a one, two or three dimensional array for storing multiple items in sequential order with the same variable name.

Practical Usage

An array is a special type of variable used to store data with multiple rows and/or columns. It could be useful to create an array to store data read from a text file or other system containing customer data. If there were 10 customers, the array would need to have 10 rows, if the data consisted of first name, last name, and company name it would need 3 columns and would need to be a two dimensioned array. An array can also be a simple list of text values which would take up multiple rows but only a single column, also known as a single dimensioned array.

General Parameters

Property

Type

Required

Default

Markup

Description

Array name

Text

Yes

(Empty)

NAME="myarray"

The name of the array to create. It is important that this value is unique, descriptive and does not conflict with any BASIC scripting keywords (examples of common conflicts include: date, day, week, etc).

One dimension

Number

No

(Empty)

ROWS="value"

If enabled (default), specifies creation of a one-dimensional array (or single dimension array). Accessing its elements involves a single subscript which represent a row index. If this parameter is enabled, the Two dimension and Three dimension parameters are ignored.

Two dimension

Number

No

Disabled

ROWS="value1" COLUMNS="value2"

If enabled, specifies creation of a two-dimensional array (or double-dimension array). Its elements represent a row and column index. If this parameter is enabled, the One dimension and Three dimension parameters are ignored. Disabled by default.

Three dimension

Number

No

Disabled

ROWS="value1" COLUMNS="value2" DEPTH="value3"

If enabled, specifies creation of a three-dimensional array (or triple-dimension array). Its elements represent a row, column and depth index. If this parameter is enabled, the One dimension and Two dimension parameters are ignored. Disabled by default.

Description (optional)

Text

No

(Empty)

DESCRIPTION="Date variable"

An optional text description that describes the purpose of the variable, this information will be displayed at design time in the Variable debug pane.

Advanced Parameters

Property

Type

Required

Default

Markup

Description

Variable type

Text (options)

No

Auto

  1. TYPE="auto"

  2. TYPE="text"

  3. TYPE="number"

Causes the variable to assume a specific type. The available options are:

  • Auto (default) - Variable will auto-detect whether it contains a number or text. Variable will adapt to the proper type when possible depending on the operation being performed.

  • Text - Variable will always be treated as text regardless of it's contents. If an operation is attempted that is only valid for numbers, an error will be thrown.

  • Number - Variable will always be treated as a number regardless of it's contents. If an operation is attempted that is only valid for numbers, an error will be thrown.

Variable is private

Yes/No

No

No

PRIVATE="yes"

If set to YES, specifies that the variable is only available to the current (or parent) task and not to any sub-tasks (or child tasks) that were started with the Start task activity. If this value is set to NO, the variable will be available to sub-tasks. Set to NO by default.

Treat as parameter

Yes/No

No

No

ISPARAMETER="YES"

If set to YES, specifies that the variable will only be created if it does not already exist. This is particularly useful when a task may have parameters passed to it at runtime (that is, variables of the same name will be created automatically) but a default value should be assumed when debugging and parameters are not present.

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.

Example 1: Simple array example.

<AMARRAY NAME="myarray" TYPE="TEXT" ROWS="3" />
<AMSET VARIABLENAME="myarray(1)">Red</AMSET>
<AMSET VARIABLENAME="myarray(2)">Blue</AMSET>
<AMSET VARIABLENAME="myarray(3)">Green</AMSET>
<AMSHOWDIALOG MESSAGE="%myarray(1)%; 
%myarray(2)%; %myarray(3)%" />

Example 2: Sample with Loops (requires a folder called c:\test\ with a few files in it).

<AMVARIABLE NAME="thefilename"></AMVARIABLE>
<AMVARIABLE NAME="counter"></AMVARIABLE>
<AMARRAY NAME="myarray" TYPE="TEXT" 
ROWS="%FileCount('c:\test\')%" />
<AMLOOP TYPE="FOLDER" FOLDER="c:\test\" 
RESULTVARIABLE="thefilename" ACTIVITY="folder">
<AMINCREMENTVARIABLE RESULTVARIABLE="counter" />
<AMSET VARIABLENAME="myarray(%counter%)">%thefilename%</AMSET>
</AMLOOP>
<AMLOOP TOTALLOOPS="%UBound(myarray, 1)%" RESULTVARIABLE="counter">
<AMSHOWDIALOG MESSAGE="%myarray(counter)%" />
</AMLOOP>

Example 3: Sample with Loops using two dimensions (requires a folder called c:\test\ with a few files in it. Array has a row for each file in the folder. 3 columns hold filename, size and date).

<AMVARIABLE NAME="thefilename"></AMVARIABLE>
<AMVARIABLE NAME="counter"></AMVARIABLE>
<AMARRAY NAME="myarray" ROWS="%FileCount('c:\test\')%" 
COLUMNS="3" DESCRIPTION="arrayto hold filename size and date" />
<AMLOOP TYPE="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">
<AMSHOWDIALOG>Filename: 
%myarray(counter, 1)%
File Size: %myarray(counter, 2)%
File Date: %myarray(counter, 3)%</AMSHOWDIALOG>
</AMLOOP>