VISUAL QUICKPRO GUIDE FileMaker Pro 7 Advanced FOR WINDOWS AND MACINTOSH [Electronic resources] نسخه متنی

Creating an Error Trap Script

FileMaker doesn't always tell you that a scripting error has occurred, or what the error is. For example, if a script has a sort that uses a field that is no longer in the database or a Go to Layout step that calls for a deleted or renamed layout, the script will behave unpredictably. Not having a clue to what's wrong with the script, you can waste precious time just narrowing down the nature of the error. To avoid this exasperating experience, create a script that reacts when it finds an error, looks up the error number, and uses the information to give you feedback on what happened.

This script relies on Get functions for its effectiveness. A Get function takes the pulse of what's happening on your computer at any given time. The Get(LastError) function specifically identifies any error code FileMaker generates. FileMaker offers a complete list of Get(LastError) numbers in its Help file. We'll use this to create a database of error numbers and descriptions that the error trap script displays.

Once we've created the error number database, we'll create a connection between it and the file whose scripts you want to check, create a layout to display error codes, and write the script you add to existing scripts to test them. Although this process is specific to capturing error codes, parts or all of it can be adapted to create online help for new users or supply read-only information from a Rolodex or customer database in another file.

To create an error trap database from tabular text

1 .

Choose Help > FileMaker Pro Help (F1/ Command+?).

2 .

When the Help dialog box appears, scroll down to the Reference section. In Windows, click Functions reference. When the Functions reference page appears, click Functions reference (alphabetical list). On the Mac, click Alphabetical list from the Functions reference text line (Figure 10.17).

Figure 10.17. The Help references pages are slightly different on the Mac and in Windows.

3 .

In the Alphabetical list, scroll down to Get(LastError) function and click to select it.

4 .When the Get(LastError) function page appears, scroll down to the Runtime errors table (Figure 10.18). Select all the error codes in the list.

Figure 10.18. Scroll to the Runtime error section to see the list of error numbers and descriptions.

5 .Copy the list, then close the Help window and launch a word processing program.

6 .Create a blank document in the word processor, and paste the list into it. You will need to clean up the file by hand to eliminate returns between the error codes and the text, and replace them with tab characters. This will take a few minutes in Microsoft Word, but the end result is worth it.

7 .

Save the file with Text Only as the file type (Figure 10.19) to create a file with no formatting in it, just text and numbers, that can be imported into FileMaker as data for fields.

Figure 10.19. Save the file as Text Only so that you can import it into FileMaker.

8 .In FileMaker, choose File > New Database. If the template dialog box appears, choose the "create a new empty file" radio button. Give the file a name and click Save.

9 .When the Define Fields dialog box appears, name the field you'll use for the error code (we use Error Number). Select Number as the field type and click Create (Figure 10.20).

Figure 10.20. Create the field for the error codes and make it a Number type.

10 .Name the field you'll use for the error description (we use Error Text) for the next field name. Select Text as the field type and click Create. Click OK to finish.

11 .

FileMaker will add these two fields to your layout.

12 .Choose File > Import Records > File.

13 .In the Open File dialog box, navigate to the text file that holds your error codes and click to select it. Choose Tab-Separated Text Files in the drop-down menu (Figure 10.21). Click Open.

Figure 10.21. Choose Tab-Separated Text Files to keep the error numbers separate from their explanations.

14 .When the Import Field Mapping dialog box appears, click Import (Figure 10.22).

Figure 10.22. Click Import to bring the text file into the database file.

The Errors database now contains a record for each Get(LastError) code, along with the text description of each error (Figure 10.23).

Figure 10.23. The error codes and their matching descriptions will appear in each record.

To relate the data of one file to another file

1 .In the database whose scripts you want to check for errors, create a new File Reference to the error code file (see the section "To create a file reference," in Chapter 6, page 115).

2 .Follow steps 12 in the section "To create a match field in a current table," in Chapter 6, page 117. When you create the field in step 2, use gErrorNumber as its name.

3 .

Click the Options button and select the Storage tab (Figure 10.24). Check the "Use global storage" check box in the Global Storage section. Click OK.

Figure 10.24. To always display the same information in the error number field, you must set it to the Global Storage option.

4 .

Follow steps 48 in the section "To create a match field in a current table," in Chapter 6, page 117.

5 .To display the script errors, you need a layout. Choose View > Layout Mode (Control+L/Command+L).

6 .Choose Layouts > New Layout/Report (Control+N/Command+N).

7 .

In the New Layout/Report dialog box, type a layout name (we use Error Description). Click "Blank layout" in the "Select a layout type" list. Click Finish.

8 .Click the Header and Footer tabs and delete each one, leaving Body as the only part in your layout.

9 .Drag the Field tool into the layout. When the Specify Field dialog box appears, double-click the global field (Figure 10.25).

Figure 10.25. Add the gError Number field to the Errors layout to see the error number.

10 .In the layout, Control/Option drag the global field to duplicate it. In the Specify Field dialog box, click the Current Table drop-down menu and choose Errors (Figure 10.26).

Figure 10.26. Choose the Errors table to add the Error Text field to the layout.

11 .

In the Specify Field dialog box, double-click the Error Text field (Figure 10.27).

Figure 10.27. The Error Text field will display the error description for the code in the global field.

You can resize the Error Text field to allow enough room to read the error description. Use the Text tool to add instructions for anyone else who might need to check scripts (Figure 10.28).

Figure 10.28. Allow enough room for the Error Text field to display the longest error description.

To create an error trap script

1 .To create the actual error trap script, choose Scripts > ScriptMaker (Control+Shift+S/Command+Shift+S).

2 .

In the Define Scripts dialog box, click New. When the Edit Script dialog box appears, give the script a name (we use Error Trap).

3 .In the step list on the left, double- click If.

An If step allows you to test whether or not an error exists.

4 .Under Script Step Options, click Specify to bring up the Specify Calculation dialog box.

5 .In the field list on the left, scroll to gError Number and double-click to insert it between the parentheses.

6 .In the operators list, click ¤. Type 0 in the formula box (Figure 10.29). Click OK.

Figure 10.29. If the gError Number field equals 0, then no error occurred and none of the subsequent steps will be executed.

This step tells FileMaker to follow certain instructions if the error code number is anything otherthan zero. (An error code of zero means that there is no error.)

7 .In the step list on the left, double-click Go to Layout. Under Script Step Options, choose the layout you just created (ours is Error Description) from the drop-down menu (Figure 10.30).

Figure 10.30. If an error has occurred, the script will go to the Error Description layout.

8 .In the step list on the left, double-click Pause/Resume Script (Figure 10.31).

Figure 10.31. The Pause/Resume step waits to let you read the description.

This step pauses the script to allow you to read the description of the error.

9 .In the step list on the left, scroll down to Fields and double-click Set Field (Figure 10.32).

Figure 10.32. After the script displays the error description, you'll use a Set Field step to reset gError Number to 0.

10 .

Under Script Step Options, check the "Specify target field" check box to bring up the Specify Field dialog box; then choose your global field (Figure 10.33).

Figure 10.33. Choose gError Number as the field to reset.

11 .

Under Script Step Options, click the Calculated result: Specify button to bring up the Specify Calculation window. In the formula box, type 0. Click OK (Figure 10.34).

Figure 10.34. gError Number is the name of the field, and 0 is the value that clears the field.

This Set Field step resets the global field so the old error will disappear when it's no longer relevant.

12 .

In the step list on the left, scroll up to Navigation and double-click Go to Layout. From the Specify drop-down menu, choose a layout that you want to switch to after the script finds an error.

13 .In the step list on the left, double-click Halt Script to stop all scripts from running (Figure 10.35). Click OK twice to finish.

Figure 10.35. The Halt Script step stops both the error trap script and the script that called it.

Now that you've created a script to explain errors, you need another script that captures the errors and runs the error trap script when they occur.

To use an error trap script in another script

1 .Choose Scripts > ScriptMaker (Control+Shift+S/Command+Shift+S).

2 .

In the Define Scripts dialog box, double-click a script that you want to test.

3 .

When the Edit Script dialog box appears, click the first step in the script-assembly list. In the step list on the left, double-click Set Error Capture and move it up until it's the first line of the script (Figure 10.36).

Figure 10.36. In the original script, Set Error Capture must be set to On for the Error Trap script to work.

4 .Select the step in the script-assembly list that may be causing an error. For this example, we use the Sort step.

5 .Scroll down to the Fields section of the step list on the left and double-click Set Field.

6 .Under Script Step Options, check the "Specify target field" check box (Figure 10.37). When the Specify Field dialog box appears, choose the global storage field created in the section "To relate the data of one file to another file" earlier in this chapter, then click OK.

Figure 10.37. Specify the field to set by clicking Field or checking the Specify target field check box.

7 .

Under Script Step Options, click the Calculated result: Specify button to bring up the Specify Calculation dialog box.

8 .In the View drop-down menu on the right, scroll down to "Get functions" and click to select it.

9 .Double-click the Get(LastError) function (Figure 10.38). Click OK.

Figure 10.38. The field gError Number is set to Get(LastError) before the Error Trap script is run.

[View full size image]

This Set Field step replaces whatever is in the global storage field with the error number FileMaker finds.

10 .

In the step list on the left, double-click Perform Script.

11 .

Under Script Step Options, click Specify. When the "Specify Script" Options dialog box appears, double-click to choose the Error Trap script (Figure 10.39). Click OK.

Figure 10.39. The Error Trap script can be run after any step that might generate an error.

12 .In the Define Scripts dialog box, highlight the script you just added the Error Trap to, and click Perform to run it.

Chapter 9). This step allows you to offer the option of manually locating the missing file in the Open File dialog box if the script doesn't initially find it.