Set Error Capture[On] – Or Oops I Did It Again

Document created by jameshea on Feb 6, 2019Last modified by jameshea on Feb 6, 2019
Version 2Show Document
  • View in full screen mode

By James Hea

Project Manager

FileMaker 17 Certified

Direct Impact Solutions

 

OK. I got busted. I was reviewing my code with a colleague and some errors came up while executing the code. He immediately asked, “Do you have error capture on for that?” Blush. I should’ve known better. So I thought it would be a good time to brush up on my error capture skills and the various ways to make my code bulletproof. (Does bullet proof mean .22 calibre or .44 calibre?) Since there are many ways errors can occur, your results may vary.

 

What is an Error?

FileMaker captures ‘errors’ when something you expect to happen doesn’t. For example, you perform a find and expect to get a found set or at least one record. And then you don’t. At this point, FileMaker will pop up an error message. In this case, ‘No records match this find criteria’. The purpose of providing feedback to a user when something unexpected happens is to allow them a course of action to correct or escape from the error. In this case, the user is offered those two choices: modify their find (as the default choice) or simply cancel the Find request. FileMaker’s built-in error capture provides the simplest of choices which may or may not meet your user’s needs.

FM_Message_125px.png

Why Error Capture?

Capturing errors is as critical in your solution as your solution is critical to your workflow. For example, it may not matter so much if you can’t find an album you have in your personal music library because you misspelled the name of the artist. Simply modify your find and try again. But what if you are looking for a legal document critical for a court case or a client’s purchase order? Or a file you are posting to an FTP site or query you are retrieving from a REST API? What if your criteria were correct but the web service is down? Or the FTP credentials have been updated without your knowledge? Wouldn’t it be more useful to know what type of error you’re having and how to address it? If you can identify the type of error in your solution and address it before the user even knows, then you’ve done them a great service and saved them some anxiety. If the error cannot be addressed directly, then letting them know what type of error occurred can greatly increase their opportunity to resolve or work around it. With the updated Get(LastExternalErrorDetail) function for ODBC imports and Execute SQL script steps and the standard Get(LastError) for FileMaker errors, you’ve gotten a lot covered. But you can go even further with the “--show-error” cURL command in the Insert from URL script step to help identify errors from web services and more.

 

Error capture is not just a one-time event in a script. If you have multiple routines in your script, then you’ll need to capture errors along the way. Proceeding in a script without capturing and appropriately halting or exiting the script can lead to further errors such as landing on the wrong layout, the wrong found set or worst of all, deleting all your records!

 

If you are using plug-ins in your solutions, most of them have error capture functions. Some of these allow you to get error codes and descriptions from standard libraries, thereby adding richer error capture options for you as a developer and more importantly, to help the user see what has gone wrong.

 

Error Capturing Tools

There are built-in tools in the FileMaker Platform to capture errors. There are script steps to enable error capture such as Allow User Abort, Set Error Capture, and Exit Script as well as functions such as Get(ErrorCaptureState), Get(LastError), Get(LastExternalErrorDetail) and Get(ScriptResult) to actually capture the errors. And there are custom functions (included with the demo file) to capture all the FileMaker 17 Error Codes. The Script Debugger has the option of turning on Pause on error, which displays the error code and description as you step through the script. And don’t forget the Data Viewer. By looking at the data during a debugging session you can determine if the error is in your code, the data architecture or in the data itself. Too many times I found that data I thought was in a field, variable or parameter had not been captured or was incorrect.

 

Error Categories

FileMaker Error Codes, accessible through FileMaker Help at

https://fmhelp.filemaker.com/help/17/fmp/en/#page/FMP_Help%2Ferror-codes.html

is an invaluable resource. The list of errors and their codes fall into several categories:

• General Errors;

• Security and Access Errors;

• Missing Elements Errors;

• Busy Elements Errors;

• Search, Sort, Import and Export Errors;

• Data Value Errors;

• Print Errors;

• File Errors;

• OS Errors;

• Spelling Errors;

• Calculation Errors;

• Function Errors;

• ODBC Errors;

• SMTP/SSL Errors; Plugin Errors;

• Web Connection Errors.

 

We won’t tackle all of these, but it is good to become familiar with the categories and codes as you work in each area. Not all categories are worth error trapping either. It’s those that can break or make your script should be treated carefully. Normally I only trap for those that I intend to handle in my script.

 

For example, if a user cancels out of printing, FileMaker does yield an error, and it can be trapped. But usually the user doesn’t want to know about it.

 

However let’s say you have a bunch of Set Field script steps following a New Record. Then an error on New Record could break your script and causing the following Set Field to set data in the wrong record.

 

Getting Started

The first thing to do with error capture is to add two script steps at the top of your script: Allow User Abort [Off] and Set Error Capture [On]. Allow User Abort [On] will allow the user to cancel a script in the middle of its execution. Depending upon the circumstances that may or may not be a good thing. Assuming that you want to manage the user experience through the whole script, turn the setting to [Off]. Setting error capture to [On] allows you to start managing the responses to the errors a user may encounter while running the script. NOTE: There are some scenarios where you may want to NOT enable Set Error Capture[On] at the beginning of the script. Instead, you may want to do this for a particular script step and then turn it off again when the following script steps can be satisfactorily addressed by the FileMaker default error messages.

Getting_Started.png

When to Handle Errors

When an error occurs in a script, you need to capture it right away. The Get(LastError) and the Get(LastExternalErrorDetail) functions need to be called right after the script step is executed. In the script below, you can see that by using the Get(LastError) function after the Perform Find script step, we can capture an error, in this case, no records found.

 

Pic1.png

The trick is to place your error capture right after executing a logical step. In the following example, a user has decided to not print. Clicking on ‘Cancel’ is an unexpected behaviour when you’ve just invoked the Print dialog box. Cancelling any user interface dialog is an error code “-1”. Capturing for the -1 error, you can gracefully dismiss the Print dialog box without getting a FileMaker message.

Pic2.png

Pause On Error

Using the Script Debugger while testing your code allows you to examine every step of your code and capture and identify any errors, you come across during testing. The script debugger has a setting at the bottom of the debugger called Pause on error. Turning this on will not only capture the error but tell you which error code and its description.

 

As you can see in the screenshot, the Pause on error checkbox is enabled and immediately after the find, you can see the Last error: [401] No records match the request. This is a very handy way to see which type of error is occurring and allow you to handle it specifically.

 

Pic4.png

Calculation Errors

There are other types of errors to capture besides script step errors. For instance, you can encounter an error within a calculation or a function. For instance, how can you handle when your JSON function produces a question mark?

 

JSON Errors

When constructing JSON queries and extracting JSON data, you may want to check that your code is working. In the screenshot below, you’ll see I have some well-formed JSON on the left and the JSONFormatElements on the right, which is simply a calculation field set to take the input field on the left and format it.

 

Pic5.png

Notice that if I remove the opening array square bracket on the left, I get the error on the right.

Pic6.png

This can help you identify where the error might be. If I copy the code on left and paste it into the JSON test field at www.jsonlint.com, it can provide a more accurate description of the error.

 

What about Related Records?

The error codes provided by FileMaker are usually looking for local records, not related records. Now this isn’t entirely true. For instance, the following error codes such as 103 – “Relationship is missing” and 110 – “Related tables are missing” are displayed when a file is missing a reference to a related table from another file. However, if you have a valid relationship but no related records, you will get the 101 – “Record is missing error”, which is obscure. This can be particularly dangerous if the followup script step is to delete the related records. Instead, the script will end up deleting records in the parent table and not in the child table. Instead, it would be better to test for a valid relationship by using the If script step and the following logic:

 

If [ not IsEmpty(relatedTableName::field))]

{Go to Related records}

{Perform some action}

Else

{Do something else, since no records are found]

EndIf

 

Another way of writing this validation is by using the IsValid function. IsValid checks for a valid entry in the field such as ‘text’ in a date field, <field missing> or another invalid indicator. I have used both.

 

If [ IsValid(relatedTableName::field))]

{Go to Related records}

{Perform some action}

Else

{Do something else, since no records are found]

EndIf

 

It is very important to check for valid related records – ensure that there is not a NULL set, otherwise the rest of your script may perform actions on the parent set and not on the related records you assumed you would find.

 

Another validation to ensure that you are on the correct context when going to related records would be to perform a layout table name validation. This is pretty much the same as the script steps above except for adding an additional condition:

 

If [ not IsEmpty(relatedTableName::field))]

{Go to Related records}

If [ Get(LayoutTableName) <> “ExpectedTableName”]

Exit Script

EndIf

{Perform some action}

Else

{Do something else, since no records are found]

EndIf

 

Conclusion

Error Capture is a big part of writing robust, reliable, quality solutions. There are many nuances to it and some script templates can help you ensure that your scripting is properly capturing errors along the way. The next article will dive deep into the structure of these templates, which also use the custom function to capture the FileMaker error code and its meaning, thus providing your users with clear meaningful messages should something go wrong with their system. There are also errors that can occur with SQL functions, XML data exchange, invalid characters pasted into fields, more JSON errors, and data validation. We’ll cover these in the next article as well. Until then, Set Error Capture [On].

9 people found this helpful

Attachments

    Outcomes