ForAll statement (LotusScript® Language)

The Notes® "product objects," built-in classes such as NotesDocumentCollection, are not usable as a collection for Forall. However, some properties of built-in objects (e.g. NotesDatabase.Forms) return an array value, and of course, these arrays can be scanned with Forall.

Syntax

ForAll refVar In container

[ statements ]

End ForAll

Elements

refVar

A reference variable for the array, list, or collection element. In the body of the ForAll loop, you use refVar to refer to each element of the array, list, or collection named by container. refVar can't have a data type suffix character appended.

container

The array, list, or collection whose elements you wish to process.

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.

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.

Example