Getting Started

Error handling in general can be separated into two parts: signaling errors, also called throwing errors, and handling errors, also called catching errors. Both parts are built-in functionalities in Lotus Script, but with limited functionality. The following sections describes all usage patterns of LS-ERROR that extend the built-in functionality dramatically.

Throwing an error

Throwing a new error with Lotus Script can be done with the built-in Error statement and LS-ERROR is not needed for this simple case.

Error 1000, "my error message"

Asserting a condition

To reduce the amount of code for checking variables for correct values, the assert function can be used to check a condition and throw an error in a single line:

assert divisor <> 0, "divisor is zero"

Re-throwing an error

Re-throwing an error means (1) to catch an error and (2) to throw the error up to the caller. If there is no error handler at all, Lotus Script automatically delegates all errors unchanged up to the calling function, but re-throwing errors with LS-ERROR adds the stack trace to the error with a minimal amount of code.

Sub doSomething On Error Goto catch ' do something else that might produce an error catch: rethrow End Sub

This pattern adds information about the current method to the error. The resulting error message might e.g. look like this:

Object variable not set at MyTestAgent.MYFUNCTION2:15 at MyTestAgent.MYFUNCTION1:9 at MyTestAgent.INITIALIZE:15

The first line is the original error message. Each following line represents one call of the stack-trace with the name of the agent, the name of the method and the line numer.

Throwing with nested error

Throwing an error in an error handler with LS-ERROR can aggregate information of errors being caught. The result is cascade of errors, each causing the previous, up to the root cause. Each error has its own message and stack-trace:

Function doSomething On Error Goto catch ' do something else that might produce an error catch: throw 1000, "Cannot do something" End Function

This pattern adds information about the current method and the previous error to the new error. The resulting error message might e.g. look like this:

Connot compute model at MyTestAgent.MYFUNCTION2:15 at MyTestAgent.MYFUNCTION1:9 at MyTestAgent.INITIALIZE:15 Caused by error 11: Division by zero at MyTestAgent.GAUSS:9 at MyTestAgent.INVERSE:9 at MyTestAgent.DET:15

Notifying an error

LS-ERROR generates multi-line error messages containing the stack-trace and nested errors. These additional lines might be ignored by Lotus Notes or appended to the first line, depending on where the error is logged to. The notify function solves this problem and reports the current error in a readable way to both, the user and the log database.

Sub Initialize On Error Goto catch ' do something else that might produce an error catch: notify Exit Sub End Sub

Note that after notifying an error, the error must still be handled somehow. This might be done by simply ignoring the error as in the example (Exit Sub), or again by one of the other functions throw or rethrow.

Classes

When handling errors in classes, it is very usefull to know in which class an error occured. Thus it is helpfull to use the current class instance in the error handler (Me). Unfortunalely Lotus Script doesn't allow optional parameters. Alternatively LS-ERROR offers versions of all above functions with a c suffix and an additional first variant argument that should be filled with the current class instance:

catch: throwc Me, 1000, "Cannot do something"

or

catch: rethrowc Me

or

catch: notifyc Me

or

assertc Me, condition, "condition is false"

Comments

A common problem when writing error handlers in Lotus Script is to forget the Exit Sub statement right before the label of the error handler. This results in a "No Resume" error, if no error occured. When using LS-ERROR, this is mostly not needed anymore, because the functions throw, throwc rethrow and rethrowc terminate immediatly without error, if there is no current error available.