Exception Statement

Used to handle RuntimeException errors.

# Notes

# Syntax

Exception [[ErrorParameter] [As ErrorType]]

Part | Description
--- | ---
ErrorParameter | Optional, used to determine the type of runtime exception.
ErrorType | Optional, if used, it must be used with ErrorParameter. Used to 'catch' a particular type of runtime error. If used, the Exception block will handle only that type of runtime error.

One or more Exception blocks can be inserted after the last "regular" line of code to catch and handle runtime exceptions that may occur anywhere within the method. Local variables that are declared inside an Exception block exist only within the block's scope rather than inside the entire method's scope. This means that multiple Exception blocks at the same level can use the same exception variable name.

If a runtime exception occurs in a built application and is not handled, REALbasic will display a generic runtime error message box and quit the application. Exception blocks provide a means of handling the error more gracefully.

Exception blocks always appear at the end of a method (not where you think the error might occur) because every line after the Exception line is considered part of the exception block. In the Code Editor, the Exception line has the same level of indentation as the Sub or Function line.

You can use Exception alone if you wish to handle any type of exception in the Exception block, as shown below:

Sub…
.
.
Exception
MsgBox "Something really bad happened, but I don't know what."

The example shown above is sufficient to prevent the application from quitting, but the message is not very informative because you don't have a clue what type of exception occurred.

The way to determine which type of runtime error occurred is to use ErrorParameter and, in some way, test its type. ErrorParameter can be any of the following error types.

ErrorType | Description
--- | ---
FunctionNotFoundException | A function declared using the Declare statement's "Soft" keyword could not be loaded.
IllegalCastException | You attempted to recast an object and sent it a message its real class can't accept.
InvalidParentException | You tried to get the parent of a control using the Parent property of the Control class, but its parent is in a different window.
KeyChainException | A method of the KeyChain or KeyChainItem classes failed.
KeyNotFoundException | You tried to access an item in a Dictionary using a key that is not in the Dictionary.
NilObjectException | An attempt was made to access an object that does not exist.
NoOpenTransportException | Open Transport is not installed on the computer.
OLException | An OLE-related runtime error occurred.
OutOfBoundsException | An attempt was made to read from or write to a value, character, or element outside the bounds of the object or data type, i.e., you tried to access an array element that doesn't exist.
OutOfMemoryException | Raised in certain cases when you run out of memory, for example when there isn't enough memory to complete an operation.
RegExException | You used an incorrect syntax in a regular expression.
RegExSearchPatternException | You specified an incorrect search pattern in a regular expression.
RegistryAccessErrorException | Occurs if you try to use the RegistryItem class without proper access privileges or try to use it under any Macintosh OS or Linux. Registry items is a Windows-only feature.
ServiceNotAvailableException | Occurs when a requested service is not available.
ShellNotRunningException | You tried to pass a string to a Shell that is not running.
ShellNotRunningException | You tried to access an interactive shell when it wasn't running. or tried to change the context of the script while it was running.
SpotlightException | An error related to a SpotlightQuery was encountered, such as an invalid query.
StackOverflowException | When one routine (method/event handler/menu handler) calls another, memory is used to keep track of the place in each routine where it was called along with the values of its local variables. The purpose of this is to return (when the routine being called finishes) to the previous routine with all local variables as they were before. The memory set aside for tracking this is called the Stack (because you are "stacking" one routine on top of another). If your application runs out of stack space, a StackOverflowException will occur.
ThreadAlreadyRunningException | You tried to set the stack size of a thread that is already running or tried to call the Run method for a thread that is already running.
TypeMismatchException | You tried to assign to an object the wrong data type. Occurs only when using an object that REALbasic cannot type at compile-time.
UnsupportedFormatException | You used an incorrect syntax in an expression, for example for column widths in a ListBox, or tried to use an unsupported format in saving and opening picture.s

One way to test ErrorParameter is with an If statement in the Exception block:

Sub…
.
.
Exception err
If err IsA TypeMismatchException then
MsgBox "Tried to retype an object!"
elseif err IsA NilObjectException then
MsgBox "Tried to access a Nil object!"
.
.
End if

Instead of using multiple If statements, you can use multiple Exception blocks, each of which handles a different runtime exception type:

Sub…
.
.
Exception err as TypeMismatchException
MsgBox "Tried to retype an object!"
Exception err as NilObjectException
MsgBox "Tried to access a Nil object!"

The Try block is an alternative to the Exception block. Unlike Exception, you can have nested Try blocks. If the innermost Try block does not handle the exception, it will be passed to the next block, and so forth. If both Try and Exception blocks are used together, the Try block will catch errors prior to the Exception block.

# Examples

See the examples for the NilObjectException, IllegalCastException, TypeMismatchException, OutOfBoundsException, and StackOverFlowException errors.

# See Also

Function, Raise, Sub statements; IllegalCastException, KeyNotFoundException, NilObjectException, NoOpenTransportException, OLEException, OutOfBoundsException, OutOfMemoryException, RegExException, RegExSearchPatternException, RuntimeException, ShellNotRunningException, StackOverFlowException, TypeMismatchException, UnsupportedFormatException classes; Nil keyword; Try block.