This page describes the intended implementation of error management within a FileMaker solution. This page outlines a method of error handling which extends far beyond using FileMaker's own built-in Get ( LastError ) function. Your FileMaker solution can potentially experience far more errors than just those generated by FileMaker itself.
The temporary GitHub repository contains the custom functions mentioned on this page, and a sample FileMaker 12 file. Once the functions are complete, they will be moved to the main fmpstandards repository.
There are many places where an error can occur within a FileMaker solution. It doesn't stop with just FileMaker the application. The most fundamental errors within FileMaker are obviously those generated by FileMaker itself. These FileMaker error codes could be handled with FileMaker's own Get ( LastError ) function. However, there are many external technologies (such as plugins), as well as the logic used to create your FileMaker solution which can also generate errors. We refer to the origin of an error as an error type. The following items are the suggested classifications for error types.
|type||explanation of this type|
An error which the developer generates within the logic of your own solution. An example of this would be a Perform script step higher in a sequence of steps which is required in order for subsequent Perform script steps to function properly.
|Plugin: Name||Plug-in specific error, specify the name of the plugin such as "Plugin: ScriptMaster", "Plugin: BaseElements", "Plugin: TroiDialog", etc.|
|Function: Name||Custom function specific error. Specify the name of the function. When saving error data in a custom function, use the reserved variable $functionError.|
Any error source can have it's own error type associated with it; here are some examples:
Because any error may have many different causal facets, such as relevant associated environmental information at the time the error occurred, a predefined number of error attributes is unrealistic. One of the primary goals is to capture environment specific information at the time of the error. Due to the amount of possible supporting information around any given error, all information relating to the error should be saved to the reserved variable $error. This variable contains name/value pairs, encoded by the # ( name ; value ) function and accessible by the #Get and #Assign functions.
Using a unique custom function for every unique source of an error provides a powerful method of capturing all necessary data about an error in a standardized format. All error specific functions are prefixed with the reserved domain of "Error".
Error ( theErrorType ; theErrorCode ; theErrorDescription ; theErrorInfo )
Return Let Notation containing information about the error and the environment it occurred in.
This function contains a recommended set of environmental data, but you may choose to add or remove name/value pairs from this function as you see fit for your solution. All error type specific custom functions call this function, so it is the central place to define default environmental data collected when an error occurs.
ErrorFmp ( theErrorCode ; theErrorInfo )
Return Let Notation containing information about a FileMaker error and the environment it occurred in.
ErrorFmpGetLast ( theErrorInfo )
Return Let Notation containing information about the last FileMaker error and the environment it occurred in.
Produces the same result as
ErrorFmp ( Get ( LastError ) ; "info about where the error occurred" ), but does not depend on ErrorFmp function.
ErrorFmp vs ErrorFmpGetLast
Typically, when evaluating a FileMaker error, you want to evaluate the last error that occurred, so you would use ErrorFmpGetLast.
In certain circumstances* however, this is not sufficient, so I have also created ErrorFmp.
ErrorApp ( theErrorCode ; theErrorInfo )
Return Let Notation containing information about the specified solution-specific error and the environment it occurred in.
This function should be modified by each developer/solution to map your own error codes to error descriptions.
ErrorFound ( theErrorData )
Return errorCode contained in theErrorData as a Boolean. In other words, if any error occurred at all, return True (1), otherwise return False (0).
Since $error is the reserved variable name for storing error data, this function will almost always be uses like this:
ErrorFound ( $error )
Error[SOURCE] ( any ; parameters ; necessary ; theErrorInfo )
Where SOURCE is unique to the origination of the error and is the same as/similar to errorType. Examples of plugin error functions would be ErrorPlugInScriptMaster or ErrorPlugInTroiDialog. The code repository contains some examples of this type of function. The intention of these functions are to translate the error information provided by the SOURCE into the standardized format implemented by these custom functions.
Over time, it would be nice to see the community and plugin developers contribute error handling custom functions for various plugins and services.
Using the Custom Functions
Additional name/value pairs can be added to the $error variable using the # ( name ; value ) function: