Exception Statement

Used to handle RuntimeException errors.


Syntax

Exception [ErrorParameter] [As ErrorType]

PartDescription
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.


Notes

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.

ErrorTypeDescription
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.