FileMaker 18: The While Function (looping in calculations)

FileMaker 18  introduces a new function that developers have long anticipated. The FileMaker While function gives developers the ability to create looping calculations. Although Custom Functions (introduced in version 7) have given us a form of looping via recursion, the While function simplifies the looping process as well as brings that functionality into the calculation engine which makes it a vastly more powerful tool.

In this article, we will explore the FileMaker While function, its parameters, and some examples. We will also discuss infinite FileMaker loops.

How the FileMaker While Function Works

A “While” loop functions by repeating the logic (i.e. looping) as long as the condition is true or to say that another way “while” the condition is true.

There are four parameters for the While function:

1. Initial Variable
2. Condition
3. Logic
4. Result

To write it out as it will appear in the calculation engine:

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

Let’s start with an example of how the FileMaker while loop functions and then we’ll dig into the pieces.

An example

One of the first simple recursive functions that I saw, called itself in order to loop over some text and make a multi-line key. It would take some text like “FileMaker” and the output would be a text block like this:

F
Fi
Fil
File
FileM
FileMa
FileMak
FileMake
FileMaker

If I use that as an example, creating a While function to produce that kind of output looks like this:

While ( 
[ 
  theText = "FileMaker"; 
  textLength = Length( theText ); 
  theResult = ""; 
  counter = 0 
] ;

counter < textLength ; 

[ 
  counter = counter + 1 ;
  theResult = theResult & Left( theText ; counter ) & "¶"
] ; 

theResult

)

Breaking the Function Apart

Ok, so let’s zoom in on each section of the function and discuss what is happening.

Initial Variable

The initial variable parameter is where you establish one or more variables that will be available to use by the other parameters. This is where you will define the variables that will be needed later in the function.

While ( 
[ 
  theText = "FileMaker"; 
  textLength = Length( theText ); 
  theResult = ""; 
  counter = 0 
] ;

The first two variables make sense as they are establishing the text we will be looping over and the information we need to exit the loop.

• theText: The text we are going to loop over
• textLength: provides an exit condition for our loop

The second two variables can be slightly confusing as they don’t seem to be needed until later. The reason they are here is because the variables need to be initialized (i.e. established) if we want them to retain their value throughout the entire looping process. If we don’t include those variables in this section then we can’t add to the counter and we can’t build up a list in theResult. 

• theResult: Has to be initialized here so it can be used later
• counter: Has to be initialized here so it can be used later

Condition

The condition parameter is a test. It is a Boolean expression that is evaluated before each loop iteration. As long as the condition is true…or while the condition is true, the loop repeats. When false, the loop stops (and jumps to the result).

counter < textLength ;

In our example, the loop will continue as long as the counter is less than the textLength.

Logic

The logic parameter is the section that gets evaluated each time the loop is repeated. Variables that are established here will be “reset” or rather “reevaluated” for each loop.

[
counter = counter + 1 ;
theResult = theResult & Left( theText ; counter ) & "¶"
] ;

In our example, the counter variable is incremented by 1 and theResult uses the Left function to build a simple list.

Result

The result parameter is an expression that is returned when the loop stops. Just as the name implies, this is where the result of the function (i.e. the result of your calculation) will go.

theResult

)

In our example we placed our array into theResult variable, so now all we need to do is have our calculation return its contents.

Variable clarification

There are two places in the While function where you can set function variables (Initial Variable and Logic). The initial variable will be available throughout the looping process, while the variables set in the Logic section will be evaluated each time the loop is repeated.

One way to think about it is kind of like a script variable and global variables ($var & $$var). In the same way that global variables ($$var) survive outside of the currently running script, variables created in the Initial Variable parameter survive outside of each individual iteration of the loop that is happening inside the While function. Also, in the same way that script variables ($var) do not survive outside of the currently running script, variables created in the Logic parameter do not survive outside of the current iteration of the loop.

Variable Scope

In the FileMaker 18 Help documents, there is an example (shown below) that includes a While function within a Let function.  Since calculation variables can be created in both of these functions, the scope of each calculation’s variable can get confusing. To put it simply, a function’s variables are available from any place within that function. Let’s look at the example and then dissect it. I’ll number each line so it is easier to refer to.

1 Let (
2   City = "Paris";
3   While(
4     [ City = "San Francisco"; i = 0 ] ;
5     i < 5 ;
6     [
7      i = i + 1 ;
8      City = City & "."
9     ] ;
10    City
11  )
& City )

So, the “City” variable in the Let function above is available to the Let function at any place contained within the Let function (i.e. inside the While function). The “City” variable in the While function is available to the While function, but not to the Let function.

In the real world, I’d probably try to avoid having the same variable name in both places, but it is an interesting example to copy out to data viewer and play with to see how things work. For example, the current result to this calculation is “San Francisco…..Paris”, but if you change:

1. Line 4 to [ City = City; i = 0 ] ; the result is “Paris…..Paris”.
   • The While’s city variable is getting set to Paris. The While function can see the Let’s variables because While is inside the Let function.
2. Line 8 to Town = City & "." and line 10 to Town the result is San Francisco.Paris.
   • Town isn’t initialized on line 4, so it gets reset on each loop. It doesn’t build on itself but rather gets reset to “San Francisco.” each loop iteration.
   • You could almost think of this as putting the cursor in a field 5 times and typing “San Francisco.” each time, but the field is set to “Select entire contents on entry”…at the end of that activity you’d just have “San Francisco.” once in the field because you’d be overwriting it each time.

Variable scopes behave the same no matter how the nesting occurs. If you have a While function and inside one of the parameters you decide to include a Let function, then the Let’s variables will only be available to the Let function, but the While’s variables will be available to both the While function and the Let function.

Can I get stuck in a FileMaker loop?

We’ve all done it. Whenever a developer has the power to build a looping process, we inevitably eventually end up in an infinite loop situation. The While function will return a “?” when the number of iterations exceeds a limit. What is the limit (I knew you were going to ask that)? Here is how to fix FileMaker while loops that are infinite.

FileMaker 18 gives us another new function so we can control that limit. SetRecursion ( expression ; maxIterations ) allows you to specify the max number of iterations to allow. This function is pretty straight forward. By default, the While function maxIteration limit is set to 50,000. To use the SetRecursion function you would place the While function as the “expression” parameter and the set the “maxIterations” parameter to the number you want.

You can also use the SetRecursion function to control how many times a custom function that uses “non-tail” recursion will iterate. To be clear, you don’t add the SetRecursion function to the Custom Function’s definition, but rather when calling the Custom Function, you wrap it inside the SetRecursion function to control how many iterations to process before returning a “?”.

Shoot me an email if you’d like to discuss the new While function. It is a powerful new tool that will help developers work faster and create complex processes more efficiently than ever before.

Chad Adams is a FileMaker Certified Developer at Skeleton Key in St. Louis, MO.

About Skeleton Key

Skeleton Key develops apps on the FileMaker platform making them easy-to-integrate, easy-to-use, and quick to build and deploy. Our team of experts takes a comprehensive consulting approach to focus on learning how your organization operates. With deeper insights into the way your team works, we’re able to create an ideal solution built around your operations while forming a partnership founded on trust and transparency. We hope you found this content useful and we would love to hear from you if we can be of any further assistance.