error
The error statement allows you to raise an error
based on certain script conditions. Why would you ever want to raise
an error? You may want to catch an error in a function but handle the
error in the part of the code that called the function, higher up in
the call chain. So you would use the error
statement to pass the error up to the calling function, such as in
the following example. This is similar to
“throwing” an exception in Java.
This example uses a getNumber method to get a number from the user, but it does not bother (for the sake of demonstration) to check the entry to ensure that the user has entered a valid number. If the user enters data that is not a number then the statement:
return (theNum as number)
causes an error, because AppleScript cannot coerce non-numeric
characters to a number. To be specific, this is
AppleScript error number -1700. The getNumber
method catches the error and uses an error
statement to pass the original error’s error message
and number back to the calling handler (in this case the
script’s run handler), which
then catches the “re-raised” error
and displays a message:
on run
try
display dialog "Your number is: " & (getNumber( ) as text)
on error errmesg number errn
display dialog errmesg & return & return & "error number: " &¬
(errn as text)
end try
end run
on getNumber( )
set theNum to (text returned of (display dialog¬
"Please enter a number:" default answer ""))
try
return (theNum as number)
on error errmesg number errnumber
error errmesg number errnumber
end try
end getNumberThe error statement also gives the scripter more
control on how program errors are handled. For example, you can catch
an error in a script with a try block (see
“try” later in this chapter),
examine the nature of the error, then re-raise the error with the
error statement providing a more lucid error
message to the user. This is best illustrated with the following
code, which catches an error caused by coercing a non-numeric string
to a real data type:
(* use the display-dialog scripting addition to ask the user to enter a number *) set aNum to the text returned of (display dialog "Enter a number"¬ default answer "") try set aNum to aNum as real (* non-numeric string like "10ab" will raise an error *) on error number errNumber set myErrText to "Can't coerce the supplied text to a real: " &¬ return & "The AS error number is " & errNumber error myErrText number 9000 -- add your own error number end try
The code first asks the user to enter a number, using the
display dialog scripting addition. This produces
a dialog box with a text-entry field. If the user enters some text
that cannot be coerced to a number, such as
10ab (the included letters ab
cause the coercion to fail), the expression:
set aNum to aNum as real
causes the script to raise an error. The try block
catches the error, and then processes the statements following the
on error code. These statements include:
error myErrText number 9000
which produces an AppleScript error-dialog box and adds the
scripter’s custom message (stored in the variable
myErrText). It also provides a custom error number
of 9000. You can create your own groups of error numbers or variables
for certain error conditions, which your script can then identify and
respond to with more accuracy and clarity than if the scripter only
relied on AppleScript’s error numbers.
The next two examples illustrate the setup and usage of custom error variables. The first example is a script that contains several user-defined error variables for some common errors that occur in AppleScripts. This script is loaded into the current script using the load script scripting addition (Appendix A, discusses scripting additions, or osaxen). The example only contains three constants, but it could define dozens of them to accommodate most or all of the possible script errors that could occur. The constants are set to the actual values that AppleScript assigns to the errors that represent, for example, the failure to coerce data from one type to another (i.e., error number -1700):
set FAILED_COERCION to -1700 set MISSING_PARAMETER to -1701 set TIMEDOUT_APPLEEVENT to -1712
You can then test for certain errors and, if you discover them,
display more informative messages or take some other appropriate
action. For example, the script in the following code sets the
variable objErrors to the script object defined in
the prior example. It then uses the
FAILED_COERCION and
TIMEDOUT_APPLEEVENT constants from that object to
test for these error conditions. In other words, the
TIMEDOUT_APPLEEVENT variable contains
AppleScript’s actual error number for Apple events
that time out (-1712), but it is easier to remember if it is stored
in a variable with a coherent name. If either of these errors is
detected, the error statement is used to produce a dialog box with
your own error message:
set objErrors to (load script file "HFSA2gig:nutshell book:demo¬
scripts:scr_0504")(* this script object contains the user-defined error
variables *)
set userReply to the text returned of (display dialog¬
"Please enter a number" default answer "")
try
set aNum to userReply as real (* if the user doesn't provide a number
this statement will fail and the try block will catch the error *)
on error errM number errNumber
if errNumber is equal to (objErrors's FAILED_COERCION) then
(* FAILED_COERCION is a property of the script object stored in objError *)
error "The number you provided was not a valid integer or real."
else if errNumber is equal to (objErrors's TIMEDOUT_APPLEEVENT) then
error "For some reason AppleScript timed out."
else -- default error message for all other errors
set defMessage to "Sorry, AppleScript error number: " & errNumber &¬
"occurred in the script. Here's AppleScript's error description: " & errM
error defMessage
end if
end tryThe error statement includes a number of optional
parameters. It is important to remember that you supply the values
for these parameters (if you want to use them). With
try blocks and on error
statements, AppleScript itself will fill these parameters with values
(see “try” later in this chapter):
A non-labeled parameter that contains the text describing the error,
as in error "The Apple event timed out".
A labeled parameter that identifies the error number, such as
error "The
Apple event timed out" number 9000. You use the keyword number
followed by the integer. If you do not include an
error number, AppleScript gives this parameter a default value of
-2700.
A labeled parameter that identifies the object that caused the error,
as in error "The Apple event timed out" number 9000 from userReply. You use the keyword from
followed by a reference to the object, in this case the variable that
caused the coercion error.
A labeled parameter that involves the reserved words partial result followed by a value of type list.
If the command that caused the error involved the receipt of return
values from multiple objects (e.g., a command sent to several
database files to get some data), then the list
value contains any of the values that were successfully received
before the error halted the operation. AppleScript gives this
parameter a default value of the empty list ({ }).
A to keyword or label followed by a word that
identifies a class type, such as boolean,
string, or integer. If the
command that caused the error received the wrong type of parameter
value, then the to labeled parameter will identify
the correct data type that the parameter expected.
The following example demonstrates how to pass the information about
an AppleScript error to an error statement. The
script intentionally raises an error by using a
string instead of a boolean
expression in an if statement. Then it passes the
error data as a long string to an
error statement:
try
if "not a boolean" then (* this causes an error, caught in the try block *)
beep 2
end if
on error errMessage number errNum from errSource partial result¬
errList to class_constant -- various variables store information about the error
set bigmessage to "The error is: " & errMessage & return &¬
"The number is: " & errNum & return & "The source is: " & errSource
error bigmessage -- error statement displays dialog box to user
end try