FileMaker 18: Data File Script Steps and Error Logging in FileMaker

With the release of FileMaker 18 comes several new utility script steps. The ability to activate error logging will provide developers and database admins easy access to valuable troubleshooting data that previously existed only via a download from FileMaker Server. This in combination with a full palette of new data file interaction script steps offers some interesting possibilities for developers in any field. We’ve put together a nice sample file that demonstrates one possible use case, but before diving into that, let’s cover the new features themselves.

Error Logging

Error trapping is a task that sooner or later becomes part of any development project. FileMaker Server has the ability to keep an error log, but devising a system that captures errors in a readily available (and useful) way has traditionally been on the shoulders of the developer. We at Skeleton Key have our own set of scripts and custom functions that are part of a standard template for any new development project. The downside of such a system is that it is incumbent on the developer to identify those script steps that could be prone to errors and to make sure the custom “Capture Error” scripts are inserted in just the right places in the parent script to accurately log those errors. Never mind the decision tree of possible actions that should be taken in reaction to any given specific error. A single new script step available in FileMaker 18 has made at least the former task much simpler.

By calling Set Error Logging [On] a script can initiate the creation of a ScriptErrors.log file directly in the user’s Documents folder. Once turned on, any script step that returns a non-zero error code will be recorded in the log. Each log entry will include the following information:

• Timestamp
• Database session number
• Filename
• Account name
• Script name [script index]
• Step name [line number]
• Error code

In addition, a custom expression can be entered into the Set Error Logging step that will evaluate whenever an error gets logged. This can be used to capture any kind of custom info needed.

Data File Handling

Eleven new script steps have been introduced that annex a number of functions that, until now, have required either a plugin or use of the command line.

• Open Data File – Opens a data file for use with other data file script steps.
• Close Data File
• Create Data File – Creates an empty, closed data file, to then open with the Open Data File script step and add data to using the Write to Data File script step.
• Delete File
• Read from Data File – Reads data from an open data file.
• Write to Data File – Writes data to an open data file.
• Get Data File Position – Returns the read-write position in an open data file.
• Set Data File Position – Sets the read-write position in an open data file.
• Rename File
• Get File Exists – Returns 1 (true) if a file exists; otherwise, returns 0 (false).
• Get File Size – Returns the size, in bytes, of a file.

Opening & Closing Data Files

To open a file, the script step requires 2 parameters. The file path (which uses the standard methods for FileMaker) and the name of a field or variable where the ID of the file will be held. Example: The following steps will open the file named “notes.txt” located in the user’s Documents folder and set the $FileID variable to the ID of the file. (Note: If the variable declared in the script step does not already exist, it will be created)

The same file could then be closed by calling the file ID.

Creating & Deleting Data Files

Files can be created by specifying the file path in the script step. Example: The following steps would create a new file named “results.txt” in the user’s Documents folder. (Note: In order to create the containing ‘test’ folder, if it does not exist, the option to create folders must be [On].)

Upon creation, new files are empty and closed. The Open Data File step would need to be used before writing to the file. The same file could be deleted by specifying the file path.

Reading & Writing to Data Files

The Read from Data File script step will read a specified amount of data from a specified (and opened) file starting at the current read-write position. (see Set/Get Data File Position steps). Example: The following will open the text file named ‘results.txt’ and read the first 250 bytes of data, setting the data read into the $$FileText variable.

The ‘Read as’ option will default to “Bytes”, but can be changed to either UTF-16 or UTF-8. If the ‘Amount’ option is left blank FileMaker will read in the entire data file. Data can also be written to a file using the Write to Data File step. Example: The following steps will open the file named ‘results.txt’ and write to it the data stored in the $$TextToWrite variable.

Data File Position

When a data file is first opened the default read/write position is 0. The current read/write position can be retreived by calling the Get Data File Position script step. This position can also be changed by using the Set Data File Position script step.

The above steps would set the read/write position of the opened file to the position of the 100th byte. (Note: The last available position of a file is equal to the file size.)

Demo Error File in FileMaker

The ErrorLogSample.fmp12 file uses a number of the new functions described above to demonstrate a basic version of an error log utility that could be implemented in any FileMaker solution.

To start, the file will run a script that has been created to be intentionally buggy. The ScriptErrors.log file that FileMaker creates when error logging is turned on can then be read into the file and displayed in a web viewer object. The error logging script steps take advantage of the ‘custom debug info’ option to include a small block of HTML as part of each error that gets logged. When displayed in a web viewer, this HTML makes it possible, using an FMP url with script and parameter tags, to navigate directly to the exact record that experienced the error. This ability would prove very useful as a debug tool as well as tracking down any records that may contain inaccurate data as a result of a scripting error.

In addition, once read into the file, the error log can be exported to the desktop as a file that includes, as part of its header, the text that is entered into the field provided. An implementation of this type could easily be followed up by additional scripts that sent the resulting file as an email attachment. Using something similar to this demo, users could send error logs to a developer or admin with a click of a button complete with any additional information needed from the user such as what actions they were performing when the error occurred.

Jeremy Upton is a FileMaker Certified developer at Skeleton Key.

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.