[Advanced]...by Bob Cusick / Clickware
Just the Status, Ma'am...
The power of the new 3.0 status functions.
With 3.0, Claris added a LOT of new scripting capabilities along with many more calculated functions. I'm going to be talking about the exciting new Status functions that are now available in any calculation dialog. I'm also going to show you how to create a script that uses the new conditional scripting to avoid the infamous “No records match this request” dialog of FileMaker Pro 2.1!
We'll start with understanding what functions are, what they do, and some practical examples of how to use them. Next, we'll take a look at putting them to work in a “Find” script. Roll up you sleeves, and let's dig in!
Calculated Functions
Status functions are built-in methods for things that FileMaker can calculate. For example the “Upper” function will return a calculation of all uppercase letters for the given field (for example Upper[MyField] will return the field “MyField” in all uppercase). These built-in functions have been expanded a great deal, but today we're only going to focus on the new Status Functions.
Status Functions
There are 32 new Status Functions that allow you to check the environment that your file is running in. How would you like to completely avoid the “Today” function forever? You can, with “Status(CurrentDate)”. Did you ever want to figure out how many users were using the current file (“Status(CurrentUserCount)”), what version of FileMaker the person was using (“Status(CurrentAppVersion)”), or what layout the user is on (“Status(CurrentLayoutName)”, “Status(CurrentLayoutNumber)”)? Now you can do all those things and MANY MORE! Here's a listing of the available status functions:
Status (CurrentAppVersion) returns the current version of FileMaker being used
Status (CurrentDate) returns the current date in (mm/dd/yy) format
Status (CurrentError)* this is used with “Error Capture” and will be explained later
Status (CurrentFieldName) returns the name of the currently active field
Status (CurrentFileName) returns the name of the current file
Status (CurrentFileSize) returns the size of the file in bytes (a 30K file would be 30720)
Status (CurrentFoundCount) returns the number of records in the current found set
Status (CurrentHostName) returns the name of the machine that's currently being used
Status (CurrentLanguage) returns the name of the language used (i.e. “English”)
Status (CurrentLayoutCount) returns the number of layouts in the current file
Status (CurrentLayoutName) returns the name of the current layout
Status (CurrentLayoutNumber) returns the number of the current layout
Status (CurrentMessageChoice)* returns the number of the button pressed with the “Show Message” script command
Status (CurrentMode) returns a “0” for browse and a “1” for find mode
Status (CurrentMultiUserStatus) returns a “0” for single user, a “1” for multi-user and the computer is host, and a "2" for multi-user and the computer is guest
Status (CurrentPageNumber) returns the current page number
Status (CurrentPlatform) returns “0” for Windows and “1” for Macintosh
Status (CurrentPortalRow) returns the number of the active portal row (if any)
Status (CurrentPrinterName) returns the name of the printer (i.e. “LaserWriter IIgx”), the print driver (i.e. “LaserWriter”), and the name of the network zone (i.e. “Sales” or “<unknown>” if there is no zone)
Status (CurrentRecordCount) returns the number of records in the entire database
Status (CurrentRepetitionNumber) returns the number of the active repetition in a repeating field (if any)
Status (CurrentRequestCount)* returns the number of current find requests
Status (CurrentScreenDepth) returns the color depth of the current monitor (i.e. “1” for black and white, “8” for 256 colors, etc.)
Status (CurrentScreenHeight) returns the height of the current monitor (i.e. “480” for a standard 14 inch monitor)
Status (CurrentScreenWidth) returns the width of the current monitor (i.e. “640” for a standard 14 inch monitor)
Status (CurrentScriptName) returns the name of the currently executing script (if any)
Status (CurrentSortStatus) returns “0” for unsorted, “1” for sorted and “2” for semi-sorted
Status (CurrentSystemVersion) returns the number of the currently running system
Status (CurrentTime) returns the current time in the time format
Status (CurrentUserCount) returns the number of users currently using the current file (i.e. “1” when set to single user, “2” or more when shared across the network and people actually have the file open)
Status (CurrentUserName) returns the current machine name (TIP: You can change this by choosing “Preferences” from the “Edit” menu and enter your name instead of the machine name. This will show up in any “Created By” or “Modified By” fields you have specified in your file).
*The asterisk represents status functions that don't return a value unless you include extra script steps. For example, Status (CurrentRequestCount) will return “0” if you're not in the find mode.
Putting Status Functions To Work
For our example, we're going to look at a common task that has been frustrating to FileMaker scripters in the past; getting around the “No records match this request” dialog box. You know the scenario - you've written this great script that automates some long, tedious task but you've assumed that there would be certain information in the file, and if it's not there, the user gets the “No records match this request” dialog with the “Cancel”, “Continue” or “Modify Find” buttons! Depending on the button the user presses (most will click “Continue”), the script might not work right or even might accidentally delete all the data in the file by mistake.
There are lots of work-arounds for this, including making a “dummy” record with the correct data before doing the find, then deleting it later, etc. With the “Status (CurrentError)” and the “Status (CurrentMessageChoice)” status functions, I'll show you how you NEVER have to go through that again. Plus, you can even word your own “No records match this request” dialog, put your own buttons (up to 3) on the dialog as well, and branch your script according to the button that was pushed! COOL!
Scripting a Find
(Skill Level: Intermediate to Advanced)
Let's assume we want to find all of the people in our Contacts database who live in the state of California, then print mail labels to them. Using the new status functions, if there are no people in the state of California, then we want to show a dialog with the words “There are no contacts in the state of California!” and a single button “Cancel”. The first script “Find Contacts In California” assumes that you've already performed the find for “CA” in the state field and restores the find request. The second example “Find Contacts In California (METHOD 2)” will set up the find request so that you DON'T HAVE TO preset the find request. Below each script listing, I'll examine each script step to help you decipher what's going on:
Script “Find Contacts In California”
Set Error Capture [On]
Go to Layout [“Layout #1”]
Perform Find [Restore]
If [“Status(CurrentError) = 0”]
Perform Script [Sub-scripts, “Print Mail Labels”]
Else
Show Message [“There are no contacts in the st...”]
Find All
End If
Step #1 “Set Error Capture [On]” IS EXTREMELY CRITICAL! This is the command that tells FileMaker to “capture” the error codes and keep track of them. If you don't use this command - your script will NOT WORK!
Step #2 - “Go to Layout [“Layout #1”]” - Since we are setting up and restoring the find, we need to be on a layout that CONTAINS THE FIELD WE ARE PERFORMING THE FIND ON. Otherwise, the script will ALWAYS return our error message.
Step #3 - “Perform Find [Restore]” - Don't forget to actually perform the find (even if there aren't any records that match “CA” in the “State” field. If there are no records, just click “Cancel” when you get the FileMaker Error Message.
Step #4 - “If [“Status(CurrentError) = 0”]” - Here's where our new, trusty status function comes in, along with the COOL new “If” feature of ScriptMaker. The conditional scripting issue is enough for another whole article - so just click the “Specify” button and you'll see the “Calculation” dialog box come up. [You will now be looking at a calculation dialog box] From the upper right pop-up menu, choose “Status Functions” (last one on the list), then double click “Status (CurrentError)”, type an equal sign (=), type the number zero (0), and click “OK”. An “If” statement can only return “true” or “false” so we're saying that if there was not any error (the number 0 is returned if everything went OK), then continue.
Step #5 - “Perform Script [Sub-scripts, “Print Mail Labels”]” - Put the script or other action you want to perform if THERE ARE RECORDS THAT MATCH THE FIND REQUEST.
Step #6 - “Else” - You must include this step if you want to do anything if there WAS an error on the find request (for example there were no records that matched). If you DO NOT want to do anything if no records match, then just put the “End If” statement here.
Step #7 - “Show Message [“There are no contacts in the st...”]” - This is the command that will put up a dialog box. While making the script you will find the script step is at the bottom of the “Available Steps” on the left hand side. Double click it, then click “Specify” and type in the message you want (up to 254 characters including spaces), and type in the text you want for each button (or just “Cancel” in the button #1, and nothing in buttons #2 and #3). We could use another “If” and the “Status (CurrentMessageChoice)” to see what button was pushed and branch accordingly if we wanted to.
Step #8 - “Find All” - This step is OPTIONAL, but if no records are found, then your user will be looking at a “null found set”, which is simply a found set with no records in it. If they try to type, they'll get a FileMaker Error saying to make a new record before trying to type. Worse yet, you'll probably get a phone call from some who as “lost all their data”, when in fact, all they have to do is choose “Find All” and it will “magically” reappear!
Step #9 - “End If” - This step is put in automatically when you choose the “If”, but it needs to be at the end, and FileMaker will not let you exit the script definition if it is missing.
Script “Find Contacts In California (METHOD 2)”
Set Error Capture [On]
Enter Find Mode [ ]
Set Field [“State”, “CA”]
Perform Find [ ]
If [“Status(CurrentError) = 0”]
Perform Script [Sub-scripts, “Print Mail Labels”]
Else
Show Message [“There are no contacts in the st...”]
Find All
End If
Step #1 “Set Error Capture [On]” IS EXTREMELY CRITICAL! This is the command that tells FileMaker to “capture” the error codes and keep track of them. If you don't use this command - your script will NOT WORK!
Step #2 - “Enter Find Mode [ ]” - This works just like it did in 2.1. Note: DO NOT choose the “Restore” or “Pause” options!
Step #3 - “Set Field [“State”, “CA”]” - I think this “Set Field” command is one of the HOTTEST new commands in ScriptMaker! In 2.1, when you wanted to set a field to contain certain data, you had to go to a layout that contained that field (Go to Layout [“Layout #1”]), have another step to make that field active (Go to Field [“State”]), do a “Paste Literal [“CA”]”, then perform the find. You can now do it all with the “Set Field” command—you don't have to be on the layout that contains the field! A truly cool and useful command that I'm sure you'll find to be VERY helpful!
Step #4 - “Perform Find [ ]” - Note: DO NOT choose the “Restore” option!
Steps 5 thru 10 are the same as above.
In Closing
We'll, I've exceeded the editorial limits, but that's a quick look at the new status functions in FileMaker Pro 3.0. Feel free to explore on your own, and don't forget that each of status functions is explained in the FileMaker Pro User's Guide and in the Online Help. To help you get started with the Status Functions, take a look at the “Stats.FP3” bonus file. With the single click of a button, it will show 30 of the 32 new status functions, I hope you enjoy it! Happy scripting...
- END -