Handling Errors

As discussed on Section 9.2.2.2, when an error occurs during a script (a Perform Find finds no records, for instance), FileMaker shows an error message almost like the one it would if you were doing the steps manually. The one difference is a button called Continue, as Figure 15-12 explains.

If the user clicks a Cancel button in an error message, the script stops immediately, and leaves the user wherever the script was when it stopped. If he clicks Continue instead, FileMaker ignores the error and moves on with the script. In the Perform Find example, for instance, the script continues with no records in the found set. Some errors (like the one in Figure 15-12) give the user a third choice. If the user clicks Modify Find, for instance, FileMaker takes him to Find mode on the current layout and pauses the script.

Figure 15-12. The message on top is what you see when a script performs a find that doesn't find any records. The one on the bottom is what you see when you perform the same find manually (using Find mode). The only difference is the Continue button in the script version of the message. When an error occurs during a script, FileMaker gives the user all the normal choices, plus the option to ignore the error and continue the script.

Sometimes this error-handling approach is just fine. If the script is simple and everyone using it knows a little about FileMaker, it isn't too big a problem. But often, you simply need more control:

• If your system is complex and/or your users inexperienced with FileMaker, all sorts of confusion can result. First, the error message may make absolutely no sense to the user. The message complains, for instance, about not finding any records. But the user thinks, "I just wanted to create a new invoice for this job. Who said anything about finding records?" Even worse, if the user clicks Cancel, he could wind up just about anywhere: some layout in some window on some record. It could be a layout (like the Line Items layout) that he's never even seen before.
• If an error happens in the middle of a larger multi-step process, it might be really important that the script know about it and deal with it appropriately. But it's the user, not the script, which decides whether to continue or cancel. You might want to make sure the script always continues, so it can get on with important work.

Luckily, you can opt for more control over error handling if you want it. FileMaker gives you three functions for finding and dealing with errors that may occur when scripts run.

15.4.1. The Set Error Capture Script Step

The Set Error Capture script step lets you turn on error capture. That way, instead of displaying potentially confusing error messages to your database's users, FileMaker keeps track of error information (captures it) so you can pull it into your script and handle it there. Although error capturing is a great feature, it's not part of FileMaker's normal behavior. You have to activate it by adding the Set Error Capture step to your script, and choosing the On option. At any time in the script, you can turn it back off again by using the step a second time and switching the option off.

If a script turns error capture on, and then uses the Perform Script step to run another script, the second script also runs with error capture on. In other words, the error capture setting sticks around as long as scripts call other scripts. But as soon as script execution stops for good, FileMaker turns off error capture. Understanding this behavior helps you determine when you need an Error Capture script step and when it would just be redundant. Figure 15-13 shows a script that turns error capture on before performing a find, then turns it back off when it's done.

Figure 15-13. This script performs a find, but first it turns error capture on. If the find fails, the user doesn't see an error. The script can then check for no found records (in the If step) and show the user a more customized error.

As discussed in the box on Section 15.4.2, you could just turn error capture on so that your script ignores any and all errorsbut that's not good script writing. The best way to use Set Error Capture is hand-in-hand with the Get ( LastError ) function, described next, to achieve error-free results.

15.4.2. The Get ( LastError ) Function

When error capture is on, FileMaker doesn't just ignore the errors. Rather, it remembers which error occurred and gives you the chance to ask about it if you're interested. The script in Figure 15-13, for example, isn't interested. It doesn't ask if an error occurred at all. Instead, it just checks to see if the find worked by counting the records in the found set.

WORD TO THE WISE
Keep It Off

Using Set Error Capture to eliminate those pesky dialog boxes sounds so cool, you may be tempted to turn it on at the start of every script. You can't anticipate every error, but at least you can keep FileMaker from casting doubt on your database skills by throwing error messages in your users' faces. But if all your script does is turn on error capture, but then never checks to see which errors are happening, you're not doing your usersor yourselfany favors.

If odd error messages pop up, your users probably let you know about it (perhaps via cellphone), giving you a chance to figure out the problem and improve your script. With error capture turned on, a script might seem to be working because no warning dialog box shows up, but really, something's gone kablooie and error capture suppresses the dialog box that would have explained what happened.

You have little hope of figuring out what went wrongespecially if no one realizes there's been a problem until long after the script has run.

Usually, you find errors when you're developing your scripts, and you can use a custom dialog box (Section 15.1) or error capture to deal with them. Don't turn error capture on unless you've already anticipated an error and figured out how your script can handle it; then turn it off again. That way, unanticipated errors don't get swept under the rug. In general, you should have just a few steps between Set Error Capture [On] and Set Error Capture [Off].

But sometimes you can use such error information within your script, much like any other value, to trigger other script steps. To check an error, use the Get ( ErrorLastError ) function to find out what happened. This function returns an error code, which is always a number. If there was no error in the previous step, Get ( LastError ) returns a zero. In other words, it doesn't return the number of the last error that occurred. Instead, it returns the error number for the last step that ran. You wouldn't, therefore, put a comment step before the step that checks the last error, since the comment step itself always sets the last error back to zero. The same goes for End If and even Set Error Capture [Off].

In FileMaker, just about everything that could possibly go wrong has its own error number. This feature gives you a lot of flexibility, but it also makes it a real pain to figure out which errors you should check for. A complete list of error numbers is found in Appendix B. Luckily, most of these errors are pretty obscure, and chances are you'll never have to worry about them. Here's a list of the more common error numbers you might actually be interested in:

• Error 9, 200 - 211, 723 - 725: Assorted security-related errors (see Chapter 16).
• Error 112: Window is missing (you get this error if you try to select, close, or move/resize a window that doesn't exist).
• Error 301: Record is in use by another user (you get this error when you try to modify a record that is locked in another window or by another user).
• Error 400: Find criteria are empty (if you let the user enter find criteria during a script, the Perform Script step gets this error if they don't enter anything).
• Error 401: No records match this request (this is the actual error that happens when no records are found; most people choose to check Get ( FoundCount ) instead since it's easier to understand).
• Errors 500 -507: Assorted field validation errors (you get these errors when you try to modify a field in a way that violates its validation setting and it is set to "always" validate).
• Errors 718 and 719: XML processing errors (see Chapter 17).
• Errors 1200 -1219: Calculation-related errors (you see these errors in conjunction with the EvaluationError and Evaulate functions).
• Errors 1400 - 1408: Assorted ODBC errors (see Chapter 17).

---

Tip: If you're seeing an error when you run a script, and you want to capture it instead, but you're unsure which error number it is, try this: Turn on error capture before the step that's producing the error. Then add a Show Custom Dialog step right after the offending step. Set the dialog box to show Get ( LastError ). When you run the script, instead of the error message you've been seeing, you'll see a custom dialog box with the real error number. You can then modify the script to handle this particular number.

---

15.4.3. The Allow User Abort Script Step

One more script step has ramifications when dealing with errors: Allow User Abort. This step lets you turn off a user's ability to cancel the script. Allow User Abort only has two options: on and off. Its normal state is to be turned on, unless you specifically turn it off with the script step. Like Set Error Capture, when you turn user abort off or back on within a script, the setting carries through any subscripts called by the main script. Allow User Abort always turns back on again when the script finishes running.

If you turn user abort off, but leave error capture on, the Cancel button in error messages is removed, so the user is forced to continue the script. Turning off user abort also prevents the user from pressing Escape (Windows) or -period (Mac OS X) to cancel a running script. Finally, if the script pauses, the user doesn't get a Cancel button in the status area. Instead, the only choice is to continue.

---

Note: When a script turns off user abort and pauses, the user also can't switch to a different window, close the window, or quit FileMaker.

---