Chapter 7. Custom Functions Primer

Custom functions are without a doubt one of the most powerful features in FileMaker; we cannot advocate their use strongly enough.

Simply described, custom functions become available in the calculation dialog as additional functions for use within expressions. They are snippets of code that, just as FileMaker’s pre-established functions do, accept parameters and produce output. One example might be

    fnCommission (unitPrice; quantity; discount)

This function would then presumably return a dollar amount based on some formula that multiplied unitPrice and quantity, subtracted a discount from the total, and then applied a percentage or some internal factoring to arrive as a sales commission.

Note that as a developer using the function, we need not even know what that formula might be. All we require is, when fed the three parameters in question, that the function return a meaningful and consistent result.

For example, if ever an organization’s commission rates needed to change, the developer could edit a single custom function and all the calculations based on that function would immediately (depending on their storage settings) reflect and make use of the change.

Custom functions allow developers to abstract portions of their code, independent from database schema or scripts, where it’s possible to reuse a particular piece of logic throughout one’s database (or, by recreating the function in other files, across dozens of databases).

Custom functions can also serve as permanent “system variables” that are not subject to session issues as global fields and global variables are. The values within a custom function do not expire at the end of a user’s session, they are consistent across all users of a database, and a developer can change them centrally as needed.

For more detail and explanation on custom functions, see Chapter 14, “Advanced Calculation Techniques,” in our companion book, Special Edition Using FileMaker 8.

The Custom Function Interface

Figure 7.1. The Custom Function dialog allows developers to define parameters that then serve as input for an expression that is then written to reference those parameters.

Custom Functions: Things to Remember

Custom functions work much like calculations, but it’s important to understand the following aspects of custom functions:

• Custom functions follow the same rules for syntax that calculation functions follow.

  For a review of calculation syntax, see Chapter 4 “Working with Calculations Primer.”

• Instead of referencing schema information (data fields), custom functions make use of parameters. Values for these parameters are passed into the custom function from elsewhere in one’s database via the calculations dialog.
• Custom functions return a single result.
• Custom functions cannot directly incorporate use of container data.
• Writing custom functions requires FileMaker Pro Advanced; however, once written, anyone with access to a calculation dialog can make use of a custom function.
• Custom functions can make use of all the functions built into FileMaker, including other custom functions and external functions.
• It is possible to make use of schema data fields by using the Evaluate() function. The following example illustrates a scenario where a sales commission is referenced:

  

• Just as custom functions can reference other functions, they can reference themselves as well. This allows you to write recursive functions in FileMaker.
  
  If no exit condition exists or an error in logic occurs, the maximum number of recursions a function can make is 50,000 deep. If you create multiple branches of recursion, the most branches a custom function can perform is 10,000.
  
  The following is an example of a simple recursive function that reorders a carriage return–delimited list from bottom to top:

  

• Custom functions can interact with global and local variables. In the case of local variables ($myVar), FileMaker will store values specific to a currently running script. In the case of a global variable ($$myVar), the value in the variable will be updated and maintained throughout the file.
  If you wish to create or set variables within a custom function, use the Let() function:

  

Custom functions are extremely powerful tools for building abstract units of logic that can then be reused throughout a solution. Indeed, once a custom function has been created (and tested!) it’s easy enough to recreate them in other files and use them throughout all your solutions. We strongly recommend you create a library of tools to refine and reuse over time. To that end, visit the next chapter for a selection of some of our favorites.