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 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.
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:
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.
This pattern adds information about the current method to the error. The resulting error message might e.g. look like this:
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 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:
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:
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.
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
.
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:
or
or
or
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.