Variables are a powerful tool in FileMaker scripting. They allow you to temporarily store data, pass values between script steps and between scripts, and make scripts more dynamic and efficient. If you’re building scripts in FileMaker Pro, mastering variables is essential.
What is a variable?
A variable is a named space in memory that holds a value. In practice, it works much like a global field, but without the need for any schema definition. Like global fields, all variables are private to the user who created them.
Types of variables
There are three types of FileMaker variables – global, script and calculation. Each has a different scope. The scope of a variable defines where and when it can be accessed.
In this article, we will focus on script variables.
Global (or session)
These are written with a $$ prefix, e.g. $$HelpStatus or $$ALLOW. Global variables are available throughout a file while the file is open. They are most commonly created and updated in a script. Developers sometimes use obscure techniques such as layout calculations to create and update global variables.
Script (or local)
These are written with a $ prefix, e.g. $action or $index. Script variables are available throughout a script while the script is current and running. They are most commonly created and updated in a script.
Calculation
These do not require any specific prefix and are often written as plain words. They are defined within various calculation functions such as Let and While, and also in custom functions. Calculation variables are available within the function where they are defined.
Managing variables
Creating variables
Global and script variables are most commonly created using the Set Variable script step. This script step defines a name and a value. Unlike other programming environments, FileMaker variables do not need to be instantiated before use – simply assigning a value to a variable, creates the variable. Here are some examples:
Set Variable [ $index ; Value: 1 ]
Set Variable [ $index ; Value: $index + 1 ]
Set Variable [ $action ; Value: Get ( ScriptParameter ) ]
Set Variable [ $found ; Value: Get ( FoundCount ) ]
Set Variable [ $order ; Value: "Ascending" ]
Set Variable [ $id ; Value: Person::ID ]
Variables are set with a calculation expression, which can use constants, fields, variables, and functions.
Variables names are not case sensitive. This means that $action, $Action and $ACTION all refer to the same variable. Capitalisation of variable names is a developer convention that may be used to refer to the usage of a variable. For example, some developers always use all caps for global variables.
Updating variable values
If a variable already exists, the value it contains can be updated. While this is usually done with a Set Variable script step, variables can also be updated in other situations such as in a Let function.
Unlike updating data in fields, there are no security settings for variables. This means that any user can potentially update any variable value. While there may be security implications, the most common issue is when a variable value is accidentally updated in a script due to repeated use of the same variable name. This is usually developer error when creating or updating a script.
Clearing variables
Most variables do not need to be explicitly cleared – variables simply disappear when their scope ends. For example, when a script ends all script variables defined therein disappear.
However, a variable can be explicitly destroyed by setting its value to null (nothing):
Set Variable [ $action ; Value: "" ]
Variable Data Types
Variable values are explicitly text strings. However, FileMaker will do what it can to use the correct data type – text, number, date, etc.
When a variable is set using a field value, FileMaker will use the field data type. For example, if a person’s date of birth was set in a variable $dob using the date field dateOfBirth, FileMaker would see the stored value as a date. If the variable was then used in a calculation, FileMaker would treat the value as a date if needed.
Set Variable [ $dob ; Value: Person::dateofBirth ]
Set Variable [ $yearBorn ; Value: Year ( $dob ) ]
In this example, the Year function expects a date as input. When the script is run, the $yearBorn is evaluated correctly – it extracts the year from the $dob value. In addition, the $yearBorn value is a number data type. This is because the Year function returns number data (see Claris Help). When a variable is set using a calculation function, the data type is determined by data type returned by the function used.
We can prove this with a test calculation:
Set Variable [ $dataType ; If ( $yearBorn > 3; "Number"; "Text" ) ]
If the year is a number, then 1995 is greater than 3; if the year is text, then 1995 is less than 3.
What if the ‘number’ is extracted using a function like RightWords which returns text data?
Set Variable [ $text ; Value: "Born in the year 1995." ]
Set Variable [ $yearBorn ; Value: RightWords ( $text ; 1 ) ]
Now $yearBorn will contain 1995 as text. This can cause differing results depending on how the variable value is used.
To be clear about the data type, it is good practice to use a function to return the value as an explicit data type:
Set Variable [ $yearBorn ; Value: GetAsNumber ( RightWords ( $text ; 1 ) ) ]
Examples of Use – Script Variables
Once you start using script variables, you will come up with a myriad of uses. They will become an indispensable tool and component of your scripting. Here are just five common examples of scripting using variables.
Example 1: Reduce database hits
If field or session data is going to be used multiple times throughout a script, it is more efficient to get that data once, store it in a variable, and reference the variable when needed.
Set Variable [ $accountname ; Value: Get ( AccountName ) ]
Set Variable [ $today ; Value: Get ( CurrentDate ) ]
If [ $accountname = "Adam" or $accountname = "Barb" ]
# do stuff for them
Else If [ $accountname = "Carol" or $accountname = "David" ]
# do stuff for them
Else
# do stuff for everyone else
End If
Example 2: Store data before losing context
Often you will move away from one context but need to reference information about it later in the script. You can store that information in a variable before losing context. Examples of such information include the found record count, the current record, the ID of the current record, and the current layout.
The following script remembers the layout name before going to another layout. It then returns to that layout using Go to Layout by calculation.
Go to Layout [ "Company Form" (Company) ]
# do stuff here
Set Variable [ $layoutname ; Value: Get ( LayoutName ) ]
Go to Layout [ "Person Form" (Person) ]
# do stuff here
Go to Layout [ $layoutName ]
See also Example 5 for a case where the primary key is stored before moving away to create related records.
Example 3: Build dynamic paths
File paths are used to specify locations for export files. These need to be dynamic to suit the user and the FileMaker client being used (Pro, Server, Go, WebDirect). File paths can be calculated and stored in a variable for later use.
In this example, a file path is first calculated and stored in a variable, then used as the destination for a PDF export and then as the source for an email attachment.
Set Variable [ $filepath ; Value: Get ( TemporaryPath ) & "dailySales.PDF" ]
Save Records as PDF [ Restore ; With dialog: Off ; "$filePath" ; Records being browsed ; Create folders: On ]
Send Mail [ Send via SMTP Server ; No dialog ; To: $emailList ; Subject: "Daily Sales Report" ; Message: "Report attached" ; $filePath ]
Example 4: Passing data between scripts
Script variables are only available within the script where they are created. When variable data is needed by another script, it may be passed as a parameter. If that called script then has data to return, it can be passed back using Exit Script.
In the following example, Master script passes some data to Sub Script in a parameter. Sub Script extracts the data using the Get ( ScriptParameter ) function, and then processes it in some way. The processed data is sent back to Master script as a script result with the Exit Script step and extracted using the Get ( ScriptResult ) function.
In the Master script:
# do stuff
Set Variable [ $data ; Value: 12345 ]
Perform Script ( "Sub Script"; Specified: From list ; Parameter: $data ]
Set Variable [ $data; Get ( ScriptResult ) ]
# do stuff with the new data
In the (called) Sub Script:
Set Variable [ $dataSent ; Value: Get ( ScriptParameter ) ]
Set Variable [ $processedData ; Value: $dataSent * Random * 1000 ]
Exit Script [ Text Result: $processedData ]
Example 5: Loop settings
Scripted loops can be used to run a series of script steps a defined number of times. Variables can be used to store the number of loops required and to track how many have been run.
In this example, the user is asked how many new notes they want to create for the current person. There are a number of variables being used:
- $count is the number of notes required (entered by the user in a custom dialog)
- $personID is the primary key of the current person (used to link the new notes)
- $index is the number of times the loop has been run
The loop will only run if the number of notes required is greater than zero (0). Inside the loop, a new note is created and populated with the $personID as the foreign key. Then the index is incremented by one (1). The Exit Loop If condition tests if the $index is now equal to or greater than the $count (required number of records). If not, the loop is run again; if so, the loop exits and the script returns to the original person record.
Show Custom Dialog [ Message: "How many notes do you want to create?"; Input #1: $count, "New notes" ]
Set Variable [ $personID; Value:Person::ID ]
Go to Layout [ “Note” (Note) ]
Set Variable [ $index; Value:0 ]
If [ $count > 0 ]
Loop [ Flush: Always ]
New Record/Request
Set Field [ Note::IDperson; $personID ]
Set Variable [ $index; Value:$index + 1 ]
Exit Loop If [ $index >= $count ]
End Loop
End If
Go to Layout [ original layout ]
Conclusions
Script variables are a powerful scripting tool that will result in more efficient and more flexible scripts. It is important to know how they work as well as what they are. FileMaker variables have some important unique characteristics and behaviours as outlined above.
What to do next:
- Review the five examples given
- think about how you would implement them in your own database
- duplicate and update one of your existing scripts using variables
- Research how variables can be used to
- filter a portal
- display custom data on a layout
- Consider other uses of script variables in your own scripts