Keyword
# Exception
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
## Description
Used to handle `RuntimeException` errors.
## Usage
``` xojo
Exception [ [ ErrorParameter As ] ErrorType ]
' User code
Finally
' Code that executes even if runtime exceptions were raised
```
| Part | Description |
|----------------|------------------------------------------------------------------------------------------------------------------------------|
| ErrorParameter | Optional: Used to determine the type of runtime exception. |
| ErrorType | Optional: Used to 'catch' a particular type of runtime error. This can only be used in conjunction with an *ErrorParameter*. |
## Notes
The Exception statement catches runtime exceptions that occur anywhere within the method or event. In most cases using a `Try` is better since it allows you to catch exceptions in specific parts of your code.
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, a generic runtime error message box is displayed and the app is quits. 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:
``` xojo
Sub MyMethod()
Exception
MessageBox("Something really bad happened, but I don't know what.")
End Sub
```
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 `RuntimeException` subclasses.
One way to test *ErrorParameter* is with an `If` statement in the Exception block:
``` xojo
Sub MyMethod()
Exception err
If err IsA TypeMismatchException Then
MessageBox("Tried to retype an object!")
ElseIf err IsA NilObjectException Then
MessageBox("Tried to access a Nil object!")
End If
End Sub
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
### The preferred way
Instead of using multiple `If` statements, you can use multiple Exception statements, each of which handles a different runtime Exception type. This is the preferred way to manage exceptions. Note that you can use the same variable name several times, like *err* in the following example. An Exception will be caught only once. As a consequence, a `NilObjectException` would be caught only by the *\`Exception\` err as NilObjectException* block and not by the last *\`Exception\` err as RuntimeException* (which is not recommended, anyway. See `EndException` and `ThreadEndException`).
``` xojo
Sub MyMethod()
Exception err As TypeMismatchException
MessageBox("Tried to retype an object!")
Exception err As NilObjectException
MessageBox("Tried to access a Nil object!")
Exception err As RuntimeException ' NOT RECOMMENDED
MessageBox("Another exception")
End Sub
```
You should not use `Return` in an Exception block as it would prevent the `Finally` block to execute, if any.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
### EndException and ThreadEndException
Under some circumstances, an Exception block can catch an `EndException` or a `ThreadEndException`. This happens when you use a *catch-all* Exception statement, i.e. "Exception err as RuntimeException" instead of giving a more specific runtime Exception class. In such a case, you MUST re-raise the Exception to avoid messing up the runtime environment and create some unpredictable problems.
``` xojo
Exception err As RuntimeException ' Will catch any exception without discrimination
If err IsA EndException Or err IsA ThreadEndException Then
Raise err ' Re-raise the exception
End If
' Continue your code here
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
### Alternative
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.
## Compatibility
| | |
|-----------------------|-----|
| **Project Types** | All |
| **Operating Systems** | All |
`Function`, `Raise`, `Sub`, `Try` statements.