by Michael Smith, via <editor@iso-ezine.com>
Using FileMaker Pro Error Codes
Customize Your Solutions with Status(CurrentError)
BONUS: ERRORS.FP3, ERRLIST.FP3
PLATFORM: Mac/Win
Nearly every solution out there contains a find script. That's really the point after all--finding or allowing your customers to find the data they want. This article focuses on find scripts as a means to demonstrate some of the ways that Status(CurrentError) can be used. Be sure to take a look at the accompanying bonus file ERRORS.FP3 to see the scripts in action. Three versions of the find script are presented. In the find tradition of the Apple Company Store: Good, Better, and Best.
Things Start Out Good
We begin with a basic script which demonstrates how Status(CurrentError) works and lets us get our feet wet with the concept.
Set Error Capture [On]
Go to Layout ["Find View"]
Enter Find Mode [Pause]
Perform Find []
Set Field ["CurrentError","Status(CurrentError)"]
If ["CurrentError <> 0"]
Beep
Show Message ["Sorry, no records found. Please try again."]
Go to Layout ["Main"]
Exit Script
End If
Go to Layout ["List View"]
The script begins with the statement "Set Error Capture [On]." To understand this, we must first take a look at why we would use error capturing in the first place. Sometimes our customers do strange and unexpected things in our databases. The things they do sometimes have strange and unexpected results -- or at least it appears so to the customer.
Set Error Capture [On] tells FileMaker not to report errors to the user anymore. It should capture them in case you ask for them but don't show anyone else. You ask FileMaker to show you its cards via the function Status(CurrentError). You might be wondering if there is a corresponding Set Error Capture [Off] command and there is. In general, you don't need to use it. When a script finished running, error capture is automagically turned off for us. The only time you would want to enable it using Set Error Capture [Off] is if you wanted errors to begin reporting normally after a certain point within a script.
And This Too Shall Pass
If you've taken a good look at the script but haven't worked with Status(CurrentError) before, you are probably wondering why the Set Field is in there. It looks like you could just rewrite the If script step as...
If ["Status(CurrentError) <> 0"]
In fact, you could. But, its a bad habit to get into. The value returned by Status(CurrentError) is transitory. It only exists for a moment and you'd better grab it while you have the opportunity. After each and every script step, Status(CurrentError) reports on whether the previous script step was successful or generated an error. So, in our script above, Go to Layout executes and Status(CurrentError)=0. Zero means that there was no error; the step completed successfully. So, if there's a step that you suspect may produce an error and you want to check, you need to do it right after the step executes or store the error away for future use. Storing the error is a good habit. If you develop it now, one day you'll thank me. So, you've got the error that was returned, what do you do with it?
This is where we start to unlock the power of Status(CurrentError). Its fairly common for users to issue a find request that doesn't generate any results. It is even more common for them to be mystified by FileMaker's error message. Using Status(CurrentError), you can detect if this happens and try to give your users a little help along the way. In our Good Find script which is shown above, we simply check to see if an error occurred. Remember that Status(CurrentError)=0 when the previous script step was successful. If it <>0, then something went wrong. Here we make the assumption that if something went wrong, it was that they didn't enter good find criteria and should try their find again. In general, a reasonably assumption. But, it can be done better.
Things Get Better
The Better Find script has several improvements:
Set Error Capture [On]
Go to Layout ["Find View"]
Enter Find Mode [Pause]
Perform Find []
Set Field ["CurrentError","Status(CurrentError)"]
If ["CurrentError = 401"]
Beep
Show Message ["Sorry, no records match your request..."]
Go to Layout ["Main"]
Exit Script
End If
If ["Status(CurrentFoundCount)>1"]
Go to Layout ["List View"]
Else
Go to Layout ["Form View"]
End If
The first thing you'll notice is that CurrentError <> 0 has been replaced with CurrentError=401. Now we are honing in on a specific circumstance and its associated error. We no longer risk displaying a message inappropriate for the circumstances. Error 401 is "No records match the request". And how did I know that?
It's unfortunate but many people have trouble locating the FileMaker Pro error codes. They are in the online help system. Look for status functions... then Status(CurrentError) function... and then look for the long list of numbers. I know the online help system has improved drastically over the years. I even know that I often find really useful information in there. But, I find it frustrating to have to launch another application to find a trivial piece of information like that -- especially when I've used up every scrap of RAM available on my machine. But, I found myself a solution which I offer to you as well, ERRLIST.FP3. Its a simple database which lists the error numbers and their associated meaning.
The other innovation in the Better Find script is how it handles the found set. It uses another status function, Status(CurrentFoundCount), to see how many records were found. If more than one was found, you probably want to see a list of them and so are shuffled off to the List View layout. If you just found one, then you go to Form View. If you don't find any... well, we dealt with that before with Error 401.
Its Not Just Better, Its The Best!
Ok, that is overstating things a little. Its better than Better Find but its far from the "best" find script out there. Let's take a look at it anyway since it does have some useful tips in there.
Set Error Capture [On]
Go to Layout ["Find View"]
Loop
Enter Find Mode [Pause]
Perform Find []
Set Field ["CurrentError","Status(CurrentError)"]
Exist Loop If ["CurrentError <> 400"]
Beep
Show Message ["No find criteria were found..."]
End Loop
If ["CurrentError = 401"]
Beep
Show Message ["Sorry, no records match your request..."]
Find All
Go To Layout["List View"]
Exit Script
End If
If ["Status(CurrentFoundCount)>1"]
Go to Layout ["List View"]
Else
Go to Layout ["Form View"]
End If
Now we've got a Loop at the beginning of the script. This loop puts us in find mode and performs the find just like we did in the other scripts. The difference here is that before we are let out of the loop, we must have entered some find criteria. Error 400 tells us "Find criteria is empty."
We are still looking for Error 401 to tell us that no records were found. In this script, we changed what happens to the user after that error is detected. In my experience with customers, they often turn up a no records found error when they are just too unfamiliar with the data to provide good find criteria. So, I like to send my users to a List View layout where they can browse records and get an idea of what they are looking for. If records are found, again, we check to see how many and send them to an appropriate layout for viewing.
Its Not Just for Finds Anymore
This article may have given the impression that Status(CurrentError) is only good for find scripts but it can do so much more! A quick browse through the list of error codes does give you big ideas about what you can do. Be sure to check if the error codes are actually captured before you spend too much time developing your killer script. Some are really FileMaker internal error codes and aren't meant for your use. One example is Error 2 "Memory Error." If FileMaker runs into a bad memory error, you don't get to capture it, it just goes down.
There are still plenty of intriguing errors left though that you can capture. Consider errors 200 "record access is denied", error 201 "field cannot be modified", and error 202 "field access is denied." Using these errors in a script, you can determine the group or password of a user and act accordingly. Another intriguing error is 301 "record is in use by another user." You can reroute a script if it requires full access to a record -- something you wouldn't have if another person was using the record.
Finally, I offer one more tidbit that may get you thinking about Status(CurrentError). There is one more script in the bonus file. It is triggered on the List View layout. I haven't bothered to particularly lock up the database. Anyone can enter find mode on any layout. If you are on the List View layout, clicking the field label, Name, triggers a script which sorts the database. If you are in find mode, sorting doesn't work. Rather than allowing my users to be confused by this buttons silence while in find mode, I added error capturing to the script. After the Sort script step executes in find mode, the error 3 "command is unavailable" is captured. A more informative dialog is displayed which explains that sorting is not available while in find mode. The possibilities are boundless.
## END ##