From Xojo Documentation

Revision as of 19:05, 19 November 2009 by (talk) (Notes)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
You are currently browsing the old Xojo documentation site. Please visit the new Xojo documentation site!


Used to handle RuntimeException errors.


Exception [[ErrorParameter] [As ErrorType]]

Part Description
ErrorParameter Optional, used to determine the type of runtime exception.
ErrorType Used to 'catch' a particular type of runtime error.

Optional, if used, it must be used with ErrorParameter. If used, the Exception block will handle only that type of runtime error.


One or more Exception statements 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 statements 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 statements provide a means of handling the error more gracefully.

Exception statements 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:

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. This is scheduled to be deprecated.
OLEException 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, 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 If your application runs out of stack space, a StackOverflowException will occur.

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

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:

Exception err
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 statements, each of which handles a different runtime exception type:

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 statements. 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 statements are used together, the Try block will catch errors prior to the Exception block.


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 datatype; Try block.