Syntax

error myErrText number 9000 -- myErrText contains the error description

Description

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.

Examples

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 getNumber

The 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 try

The 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