LOTUSSCRIPT LANGUAGE


ForAll statement
Example

Executes a block of statements repeatedly for each element of an array, a list, or a collection.

Note ForAll works on Product collections; it does not support Notes collections.

Syntax

ForAll refVar In container

[ statements ]

End ForAll

Elements

refVar


container
Usage

On entry to the loop, refVar refers to the first element of the array, list, or collection. On each successive iteration, refVar refers to the next element of the array, list, or collection. Upon completion of the loop, execution continues with the first statement following the loop's End ForAll statement.

Note If you're using ForAll on an array of arrays, do not ReDim the iterator (this generates the "Illegal ReDim" error).

Collections

Here a collection means a class specifically enabled for use with Forall in an LSX module (see the LSX toolkit documentation). Some external programs accessed through OLE automation may also support the use of Forall with their objects.

The Notes product objects such as NotesDocumentCollection cannot be used as a collection with Forall. However, properties that return an array (for example, Forms in NotesDatabase) can be used with Forall.

Exiting the loop early

You can force the loop to be exited early with the Exit ForAll statement or the GoTo statement. When LotusScript encounters an Exit ForAll statement, execution immediately continues with the first statement following the loop's terminator (End ForAll). When LotusScript encounters a GoTo statement, execution immediately continues with the statement at the specified label.

Using refVar

Since refVar is an alias for the actual array, list, or collection element, you can change the value of the element to which it refers by assigning a new value to refVar. For example:

ForAll x In y
  x = x + 1
End ForAll

This adds 1 to the value of each element in the array, list, or collection named y.

If container is a list, you can pass refVar to the ListTag function to get the name (the list tag) of the list element that refVar currently refers to. For example:

Print ListTag(refVar)

Because refVar is implicitly defined by the ForAll statement, you should not include it in your variable declarations. The scope of refVar is the loop, so you can't refer to it from outside of the loop.

If container is an array or list, refVar has the data type of the array or list being processed. If this data type cannot be determined by LotusScript at compile time or if container is a collection, refVar is a Variant. In that case, the data type of the array or list cannot be a user-defined data type, because Variants cannot be assigned values of a user-defined data type.

You can reuse a refVar in a subsequent ForAll loop, provided that the data type of the container matches that of the container in the ForAll loop where refVar was first defined.

You can't use the ReDim statement on the reference variable. For example, suppose that zArr is an array of arrays, and a ForAll statement begins:

ForAll inzArr In zArr

Then the statement ReDim inzArr(2) generates an error.

Language cross-reference

@Transform function in formula language

Example
See Also