This is a set of custom functions used for error handling in Claris FileMaker. They are NOT compatible with any prior release and should only be used for new projects, or those worth the effort to replace existing functions with. They are intended to be the only means of accessing error data. In other words: you don't have to keep track of an $error variable yourself (when comparing these to older versions in this repo, for example). They currently use a local variable under-the-hood, so the error information is only available within the current scope (script) and you must pass the error to any calling scripts yourself. Don't worry; the sample file included in this repository has examples of how to do that and use these functions in various situations.
All ErrorIf* functions will save error data to a local variable and return True if the error code is Truthy.
ErrorFound returns True if an error was saved with an ErrorIf* function.
ErrorGet* functions will retrieve info from a saved error.
ErrorIfSetCustomElement will save additional info with the error and return True if an error had already been saved or False if it wasn't. This allows you to call it in the same expression as an ErrorIf* function. For example:
ErrorIfFmpLastError ( "Insert from URL" )
and ErrorIfSetCustomElement ( "url" ; $url ; JSONString )
For further reading, the Custom Function Overview lists all the functions and their documentation.
Better yet, open the FileMaker-Error-Handling.fmp12 file for real-world(ish) examples of how I use these functions. As an added bonus, I integrated with an API in a way that I consider a best practice for doing so. If you want to, or have ever integrated with an API; you might want to review the scripts in this file just for that reason.
Why should I care about the "type" of an error?
Every error was generated by some code. The type tells you who owns that code. If you can imagine a world without error types (difficult, I know!) then error code 401 means No records match the request, right? Well, HTTP status codes would disagree and call that Unauthorized, so who's right? Both! as long as you save the type of error, so you can make sense of the error code.
But I only see "Fmp" and "App" error types; what if a plugin, API, or custom funciton generates an error?
Make up a type and use it as needed; I do it all the time! The ErrorFound function uses a type of CF: ErrorFound if the error data is invalid. I often use the BaseElements plugin and if I use it more than a few times in a project I usually add an ErrorIfPluginBaseElements custom function specifically to handle it's errors.
What do you mean, they currently use a local variable under-the-hood?
These functions intentionally abstract the storage method for the error information. They are meant to be used like an API (Application Programming Interface); a way for two or more computer programs or components to communicate with each other. So while you do have access to it's internal storage mechanisim it is highly recommended NOT to do so. Following this recommendation gives you the advantage of being able to support either future or past internal storage mechanisms without changing any code that calls these functions.
Note that I did not use a global variable because it's not clear to me how best to clear it. An ErrorIf* function could always clear it, but that leaves the last error always hanging out in that global variable so if some other script checked if an error was found before it set/cleared an error, that could cause issues. It also doesn't work in a multi-file solution, so there has to be a fall-back of passing an error to a calling script via a script result and I chose to only implement that method.
What's with "the" in parameter names?
It's to prevent naming collisions that might prevent you from easily installing these functions; or others after you install these. It's been a long time since I experienced this issue or tested it, but I have had some functions fail to paste because the function name matched the parameter name of an existing custom function (or vice-versa, maybe?).
I'm already using ___ error functions; how do I switch to these?
Honestly, you probably shouldn't. All past error functions in this repository are 100% valid in a current/modern solution. Those published by others are also likely to be equaly valid, but I can't can't really comment on the unknown. If you really want to switch and have determined that the cost to do so is is justafiable, I'd recommend renaming all existing error handling functions (prepend them with z_deprecated_, for example) before adding these functions to your solution.