As discussed on Section 126.96.36.199, 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.
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:
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.
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:
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.
Part I: Introduction to FileMaker Pro
Your First Database
Organizing and Editing Records
Building a New Database
Part II: Layout Basics
Advanced Layouts and Reports
Part III: Multiple Tables and Relationships
Multiple Tables and Relationships
Advanced Relationship Techniques
Part IV: Calculations
Introduction to Calculations
Calculations and Data Types
Part V: Scripting
Part VI: Security and Integration
Exporting and Importing
Sharing Your Database
Part VII: Appendixes
Appendix A. Getting Help