On Error statement (LotusScript® Language)

Determines how an error will be handled in the current procedure.

Syntax

On Error [ errNumber ] { GoTo label | Resume Next | GoTo 0 }

Elements

errNumber

Optional. An expression whose value is an Integer error number. If this is omitted, this statement refers to all errors in the current procedure. This value can be any error number that is defined in LotusScript® at the time the On Error statement is encountered.

GoTo label

Specifies that when the error occurs, execution continues with an error-handling routine that begins at label. The error is considered handled.

Resume Next

Specifies that when the error occurs, execution continues with the statement following the statement which caused the error. No error-handling routine is executed. The values of the Err, Erl, and Error functions are not reset. (Note that a Resume statement does reset these values.) The error is considered handled.

GoTo 0

If errNumber is specified, specifies that when the error occurs, the error should be handled by the most recent general On Error statement that specifies no error number.

If errNumber is omitted, no errors are handled in the current procedure.

Usage

The On Error statement is an executable statement. It allows the procedure containing it to change the way LotusScript® responds to particular errors. If no On Error statement is used, an error ordinarily causes execution to end. On Error allows a procedure to handle the error and continue execution appropriately.

How does On Error work?

An On Error statement is in effect from the time the statement runs until superseded by another On Error statement or until control returns to the calling procedure:

  • An On Error statement that specifies an error number affects only that error. An On Error statement that specifies no error number affects all errors. For a given error, the effective On Error statement is the most recently executed that either specifies the error number or specifies no error number.
  • An On Error statement is not in effect for an error in the following cases:
    • No On Error statement that affects the error has run.
    • The most recently executed On Error statement that affects the error is On Error GoTo 0.
  • If the current procedure does not handle an error, the On Error statements in the calling procedure process the error. If no procedure handles the error, processing terminates with output of the error message.

For example, the following code sends error 11 to the DivBy0 label and all other errors to the General label:

On Error Goto General
On Error 11 Goto DivBy0

If you reverse the statements, however, all errors go to the General label:

On Error 11 Goto DivBy0
On Error Goto General

The following statements send error 11 to the General label:

On Error Goto General
On Error 11 Goto 0

How does the error-handling routine work?

An error-handling routine begins with a labeled statement. The routine ends when LotusScript® encounters a Resume, Exit Sub, Exit Property, or Exit Function statement. If an error occurs in the error-handling routine, execution ends.

While the error-handling routine is running, the Err, Erl, and Error functions describe the error being handled. A Resume statement will reset these values.

Where are error numbers and messages defined?

LotusScript® specifies a standard set of errors, and corresponding error numbers (as constants), in the file lserr.lss. To define these errors and their numbers, include this file (using %Include) in a script that you compile or load before running any other script. Then these error numbers can be used in On Error statements to control error handling in the session.

Use the Error statement to define new error numbers and messages.

Example