While

Repeats logic while the condition is true, then returns the result.

Format 

While ( [ initialVariable ] ; condition ; [ logic ] ; result )

Parameters 

initialVariable - variable definitions that will be available to use in the following parameters.

condition - a Boolean expression evaluated before each loop iteration. While True, the loop repeats. When False, the loop stops.

logic - variable definitions that are evaluated each time the loop is repeated.

result - an expression that is returned when the loop stops.

Data type returned 

text, number, date, time, timestamp, container

Originated in version 

18.0

Description 

The While function performs the following steps:

  1. Evaluates the initialVariable parameter.

  2. Evaluates the condition parameter.

  3. If condition is:

    • True (any non-zero numeric result), evaluates logic, then repeats step 2.

    • False (0), stops the loop and returns result.

You can specify multiple variable definitions for initialVariable and logic by enclosing them within brackets [ ] and separating each with a semicolon. For example:

Copy 
While ( 
    [ initVar1 = value1 ; initVar2 = value2 ; ...] ; 
    condition ; 
    [ logicVar1 = expression1 ; logicVar2 = expression2 ; ...] ; 
    result 
)

The variables specified in the initialVariable and logic parameters are evaluated from left to right. These variables are within the same scope and can be used in the condition and result parameters. See Using variables.

Variables that need to retain information from one loop iteration to the next must be initialized before they are used in the logic parameter. Otherwise, their values are deleted.

Notes 

  • To prevent infinite loops that would cause FileMaker clients to stop responding, this function returns "?" when the number of loop iterations exceeds a limit. To set the limit, use the SetRecursion function.

Example 1 

Returns the result of 5 to the power of 3. The Let statement establishes the initial value of 5 and power to be 3. The calculation loops multiple times until the result 5 * 5 * 5 = 125 is achieved.

Copy 
Let (
    [
        value = 5 ;
        power = 3
    ] ;
    While (
        [ result = value ; i = 1 ] ;
        i < power ;
        [ i = i + 1 ; result = result * value ] ;
        result
    )
)

Example 2 

Totals the values in the repeating variable $a. Each loop iteration increments count, uses it to specify the $a variable repetition, and adds the value to the running total. This example returns 150.

Copy 
While ( 
    [ 
        count = 0 ; 
        total = 0 ; 
        $a[1] = 25 ; 
        $a[2] = 50 ; 
        $a[3] = 75 
    ] ; 
    count < 3 ; 
    [
        count = count + 1 ; 
        total = total + $a[count]
    ] ;
    total
)

Example 3 

Adds five periods between two text values. The scope of the City function variable in the While function is separate from that in Let, so this example returns San Francisco.....Paris.

Copy 
Let (
    City = "Paris";
    While ( 
        [ City = "San Francisco"; i = 0 ] ; 
        i < 5 ;
        [
            i = i + 1 ;
            City = City & "."
        ] ; 
        City
    )
& City )

If every instance of the function variable City were replaced with the local variable $City, the example returns San Francisco.....San Francisco....., because $City has the same scope throughout the calculation.

Example 4 

Illustrates how the scope of function variables differs when they are defined before a While loop compared with when they're defined in the While loop's initialVariable and logic parameters.

The values of it1 and it2 defined before the While loop are available within the loop, but changes made to it1 and it2 within the loop don't affect the values of these variables after the loop. This example also shows how the value 2 of the it2 variable defined in the logic parameter gets lost after each loop iteration because it2 isn't initialized in the initialVariable parameter.

Copy 
Let (
    [ // Before While loop; sets line 1.0 of result
        it1 = "a"; // Defined in Let's scope
        it2 = 1; // Defined in Let's scope
        out = "1.0 " & it1 & " " & it2 & ¶
    ];
    While
    (
        [ // initialVariables; sets lines 2.0 and 3.0 of result
            i = 0;
            out = out & "2.0 " & it1 & " " & it2 & ¶;
            it1 = "b"; // Defined in While's scope
            out = out & "3.0 " & it1 & " " & it2 & ¶
        ];
        // Condition
        i < 2;
        [ // logic; sets lines 4.x and 5.x of result
          // Variables defined in the logic parameter in previous passes 
          // through the loop are deleted at this point
            i = i + 1;
            out = out & "4." & i & " " & it1 & " " & it2 & ¶;
            it1 = "c"; // Reused in While's scope
            it2 = 2; // Redefined in While's scope
            out = out & "5." & i & " " & it1 & " " & it2 & ¶
        ];
        // result; sets line 6.0 of result
        out & "6.0 " & it1 & " " & it2 & ¶
    )
    // After While loop; sets line 7.0 of result
    & "7.0 " & it1 & " " & it2 & ¶
)

The result is:

1.0 a 1
2.0 a 1
3.0 b 1
4.1 b 1
5.1 c 2
4.2 c 1
5.2 c 2
6.0 c 2
7.0 a 1

Related topics