Robo-FTP User's Guide > Script Programming > Select Topics in Script Programming

An array is a data structure consisting of a group of elements that are accessed by indexing. In the Robo-FTP scripting language, arrays are implemented as a set of extended features available only to variables that are named according to this array naming convention:

variable_name[index]

The Robo-FTP scripting language does not support multi-dimensional arrays.

Creating and Assigning Values to Array Elements

Each element of an array is also a normal script variable. A simple method of creating an array is to declare one or more script variables adhering to the array naming convention:

SET var[0] = "fly"

SET var[1] = "spider"

SET var[2] = "bird"

Although two of the extended array features (re-indexing and automatic indexing) work best on arrays that have a zero-based sequential numeric index, the array naming convention does not require that index values actually be numeric. The KEYS command provides a method to programmatically iterate through an array with non-numeric indices.

SET emp["first"] = "Susie"

SET emp["last"] = "Jones"

SET emp["email"] = "[email protected]"

Array elements may be assigned the value of another variable and other variables may be assigned the value of an array element:

SET animal = "bird"

SET var[2] = animal ;; element 2 now has a value of "bird"

SET pet = var[2] ;; pet variable now has a value of "bird"

Array elements may also be assigned the value of other array elements:

SET var[2] = var[1]

A user-defined variable may be used instead of the array index:

SET num = 2

SET var[num] = "bird"

Automatic Indexing for New Array Elements

The following syntax may be used to add an element to an array using an automatically derived numeric index value. If the array does not already exist it will be created with 0 as the index of the first element:

SET var[var[*]] = "frog"

Note: The syntax above should only be used on an array that has a sequential zero-based numeric index. It is possible that an existing element will be overwritten if the syntax above is used on an array that was not properly re-indexed after an element was deleted.

Finding the Size of an Array

As mentioned above, array variables are the same as normal variables except with some additional features that are available via special syntax involving the asterisk "*" character. The number of elements in an array is returned by passing an asterisk instead of an index value:

SET ArraySize = var[*] ;; save number of array elements to a variable

DISPLAY var[*] ;; write the number of elements to the console window

The following code snippet contains a loop that iterates once for each element of an array with a zero-based numeric index. It is not necessary to change the code if this array grows or shrinks because the number of loop iterations is determined dynamically:

SETNUM counter = 0

SET size = var[*]

IFNUM= size 0 GOTO loop_done ;; skip loop if array is empty

:top_of_loop

DISPLAY var[counter]

SETNUM counter = counter + 1

IFNUM< counter size GOTO top_of_loop

:loop_done

Destroying Array Elements

Array elements may be removed by using the SET command with no value; the same way user-defined variables are deallocated or destroyed. Attempting to access the value of an element that does not exist in an array results in the same error as attempting to access a non-existent user-defined variable. Destroying all elements destroys the array. It is important to re-index an array after deleting an element (see below.)

SET var[1]

DISPLAY var[1] ;; this line will cause an error

The entire array may be deleted with a single line of script as follows:

SET var[*]

Copying Array Elements

Another special syntax uses the "&" and "*" characters. You can use the following syntax to copy the elements from one array to another array.

SET first_array[0] = "first item"

SET first_array[1] = "second item"

SET second_array[&] = first_array[*]

Re-Indexing an Array

Arrays with numeric indices should be re-indexed immediately after an element is removed, otherwise logic that programmatically iterates through the array as shown above will fail. The following special array syntax replaces all existing index values in the array with sequential numeric values, beginning with "0" zero:

SET var[*] = var[*] ;; first element is now var[0]

Array Elements as Arguments or Options

Like other script variables, an array element may be passed as script command argument or option, like this:

DISPLAY var[1]

FTPLOGON site["address"] /user=site["userID"] /pw=site["pw"]

Related command(s): KEYS, SET