Object

RuntimeException Class

Properties
ErrorNumber
Message
Stack

# Notes

Use runtime exceptions to trap errors so they can be handled. For example, reading from or writing to an array element that does not exist will generate an OutOfBoundsException. Exceptions have no methods or events.

Name | Description
--- | ---
FunctionNotFound Exception | A function declared using the Declare statement's "Soft" keyword could not be loaded.
IllegalCastException | You cast an object to a different class 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 | An attempt was made to access a Dictionary item with a key that the dictionary does not contain.
NilObjectException | An attempt was made to access an object that does not exist.
OLEException | An OLE-related runtime exception occurred. Handle errors in Office Automation code via the OLEException class.
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.
OutOfMemoryException | Raised in certain cases when an operation cannot be completed due to insufficient memory.
RbScriptAlreadyRunningException | The user tried to modify an RBScript that is already executing or tried to modify the context of the script while it is running.
RegExException | The RegEx engine issued a runtime exception. Currently this means that you used an invalid search pattern in a Regular Expression. In the future, other types of regular expression exceptions may be added.
RegistryAccessErrorException | You tried to use the RegistryItem class without proper access privileges or tried to use it under any Macintosh OS or Linux. It is a Windows-only feature.
ShellNotRunningException | You tried to access an asynchronous or interactive shell session, but the shell was not running.
SOAPException | SOAPExceptions can be raised when using a WSDL to define your SOAP function. If the method name does not exist or the parameters passed do not match the WSDL specifications, a SOAPException runtime error will be raised.
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. You should be able to test your application thoroughly enough to prevent this error from occurring.
ThreadAlreadyRunningException | You tried to change the stack size of a Thread while it was running.
TypeMismatchException | You tried to assign to an object the wrong data type.
UnsupportedFormatException | You used a string expression that does not evaluate to a number or tried to open or save an unsupported picture format.
XMLDOMException | This exception may occur during the creation of a DOM document.
XMLException | There was an error in parsing XML.
XMLReaderException | There was an error in parsing XML using XMLReader.

If you fail to trap a runtime error in an exception block, it will trigger the UnhandledException event of the Application class. You can then handle all runtime exceptions generically within that event handler.

When using the Office Automation plug-ins, you can include an exception block that references these classes. For example:

Exception err as OLEException
MsgBox err.message+" Error No.: "+ Str(err.code)

Third-party plug-ins may also incorporate their own types of runtime exceptions.

When you are testing your application in the IDE, execution will stop at the offending line and you will see an error message in your Code Editor. When the error occurs in a built application, the user will see a generic error message (as shown in the Notes section below) and quit -- unless you include an exception handler.

Runtime Exceptions are used to trap errors in programming. Without an exception handler, the user will see a generic message box from REALbasic that a particular type of exception has occured.

The application will quit when the user accepts this message box.

Including exception handlers in your code allows you to display information that will help you determine the cause of the problem and prevents your application from quitting automatically.

Say, for example, you are getting an OutOfBoundsException when trying to access an element of an array. You could put in an exception handler to display the number of items in the array and the item number you were attempting to change along with any other useful information that would help you to track down the source of the bug. See the section on OutOfBoundsException for an example of this.

There is another example of exception handling in the section on IllegalCastException.

# Examples

This example includes an If statement that checks for the type of exception and displays a message box indicating the type of exception that has occurred. The Exception block goes after the last line in the method. Note that its indentation is at the same level as the Sub statement.

Sub Action
Dim a(3) as String
a(4)="geoff"
Exception err
If err IsA NilObjectException then
MsgBox "Nil Object Exception"
elseif err IsA OutOfBoundsException then
MsgBox "Out of Bounds"
elseif err IsA TypeMismatchException then
MsgBox "Type Mismatch"
End if

Instead of the If statement, you can use several Exception blocks, each of which handles a specific type of runtime exception

Dim f as FolderItem
f.delete
Exception err as NilObjectException
MsgBox "Nilobjectexception"
Exception err as OutOfBoundsException
MsgBox "Out of Bounds"
Exception err as TypeMismatchException
MsgBox "typemismatch"

.

The following example checks for the type of exception and handles the exception if it is a NilObjectException. If the exception is not a NilObjectException, it lets execution continue through the calling chain by calling Raise

Dim f as FolderItem
f.Delete
Exception err
If err IsA NilObjectException then
err.message="Drat!"
MsgBox err.message
else
Raise err
end if

.

# See Also

Function, Raise, Sub statements; FunctionNotFoundException, IllegalCastException, InvalidParentException, KeyChainException, KeyNotFoundException, NilObjectException, OLEException, OutOfBoundsException, OutOfMemoryException, RbScriptAlreadyRunningException, RegExException, RegExSearchPatternException, ShellNotRunningException, SOAPException, StackOverFlowException, TypeMismatchException, XMLDOMException, XMLException, XMLReaderException errors; Exception, Try blocks; Nil keyword.