Managing error number and message: Err and Error statements

The Err statement

The Err statement sets the error number. The Err statement corrresponds to the Err function, which returns the current error number.

The syntax is:

Err = errNumber

The error number can be set automatically by LotusScript®, when an error occurs, or explicitly by this statement in a script. Whenever the error number is set, LotusScript® automatically sets the value of the Error function to the error message associated with that error number. If the error number is set to 0, LotusScript® sets the value of the Error function to its initial value, the empty string ("").

The Err statement does not create an error as the Error statement does. It only resets the error number (and also the value of the Error function). So the error number Err may be nonzero while there is no current error.

The Error statement

The Error statement creates an error, and optionally specifies an error message associated with that error.

The syntax is:

Error errNumber [ , msgExpr ]

If you do not include the optional msgExpr string in the statement, it creates an error when the script runs. If errNumber is the number of an error that is already defined, then the effect of this statement is the same as if that error occurred when the script executed. For example, LotusScript® defines a division-by-zero error with the error number 11. So the following statement has the same effect as an actual error occurring when LotusScript® executes a statement that attempts to divide by zero:

Error = 11

If you include msgExpr in the Error statement, you specify the error message to be reported when the error occurs and no error handling for the error is in effect.

Handling errors: the On Error statement

Every error recognized at run time has its own error number that identifies it. When a recognized error happens during script execution, LotusScript® records the error number, and then proceeds as directed by an On Error statement that refers to that number.

For example, you can write either one of these On Error statements to tell LotusScript® how to respond to an occurrence of error number 357:

On Error 357 GoTo apoc600
On Error 357 Resume Next

When referring to a pre-defined error in an On Error statement, you can use the defined constant for the error instead of the error number.

For example, here are the statements in lserr.lss that define the error numbers and constants for two common errors:

Public Const ErrDivisionByZero      = 11 
' Division by zero
Public Const ErrIllegalFunctionCall = 5 
' Illegal function call

On Error statements then do not need to mention the numbers 11 and 5. Write the statements in this form instead, making the script easier to read:

On Error ErrDivisionByZero ...
On Error ErrIllegalFunctionCall ...

You can define constants for your own error numbers. (You should define your error numbers to be in the range 1000 through 1999.) Then the constant names can be used instead of numbers in any Error statements and On Error statements that refer to the error.

For example:

Const ooBounds = 677              
' A specific out-of-bounds error
' ...
Error ooBounds
' ...
On Error ooBounds ...

Using On Error Goto label

When the most recently executed On Error statement for the current error has the form On Error GoTo label, LotusScript® continues execution at the labeled statement. The statement begins anerror-handling routinefor the error. The error-handling routine may consist of any number of statements, beginning with the statement executed at the label and continuing through the next Resume, Exit Sub, Exit Function, Exit Property, or End statement encountered at run time. The error is considered handled when one of these statements executes.

When an On Error statement specifies the label where the error-handling routine begins, that labeled statement must be in the same procedure as the On Error statement. This is because a GoTo statement cannot transfer control to a labeled statement outside the procedure where it occurs. The compiler verifies that the labeled statement is present in the same procedure, and generates a compile-time error if it is not.

Error handling routines outside procedures

LotusScript® can handle an error in the procedure where it occurs or in the procedure that called the current procedure. If the current procedure doesn't handle the error, LotusScript® returns control to the calling procedure and seeks an error-handling routine there for the error. If the caller doesn't handle the error, LotusScript® looks at the caller's caller, and so on. If no applicable error-handling routine is found by this process, execution ends, and the error message for the error is generated.

For example:

' The sub TestHand generates a division-by-zero error.
' Since TestHand doesn't specify how to handle the error,
' control returns to the calling procedure SuperHand when
' the error occurs. SuperHand contains an error-handling
' routine for division by zero. Control passes to that
' routine, which prints a message and exits from SuperHand.
Sub TestHand 
   Dim num As Single 
   num! = 1
   Print num! / 0
End Sub
Sub SuperHand
   On Error GoTo DivZero 
   Call TestHand()
   Exit Sub
DivZero:
   Print "Continuing after calling sub TestHand."
   Exit Sub
End Sub
Call SuperHand()
' Output:
' Continuing after calling sub TestHand.

You can use a special form of the On Error statement to state explicitly that a specified error not receive specific handling.

The syntax is:

On Error errNumber GoTo 0

This says that the error numbered errNumber is handled by the general error processing procedure.

This example shows that the result of the preceding example is unchanged if the sub TestHand is modified as follows:

Sub TestHand 
   Dim num As Single
   On Error ErrDivisionByZero GoTo 0 
   num! = 1
   Print num! / 0
End Sub

You can also use a statement in the following form to specify that no error be handled in the current procedure. This statement makes it explicit that the procedure handles no errors, so your error-handling logic is clearer.

On Error GoTo 0

Like any On Error statement, the effect of this statement can be overridden, for any particular error, by a subsequent On Error statement that designates different handling for that error.

For example, this pair of On Error statements specifies that division-by-zero errors are handled by an error-handling routine at the label DivZero; and no other errors are handled in the current procedure (an error-handling routine for other errors is sought in the procedure's caller).

On Error GoTo 0 
On Error ErrDivisionByZero GoTo DivZero

An On Error statement of the special form On Error GoTo 0 does not handle any error that it refers to. It says explicitly that any error it refers to is not handled in the current procedure. When such an error occurs, LotusScript® searches upward through the chain of calling procedures for an On Error statement that specifies how to handle the error.

Ending the error handling routine

If the statement that ends the error-handling routine is a Resume statement, then the values of Err, Erl, and Error are reset to their initial values: 0, 0, and the empty string (""), respectively. If the statement is Exit Sub, Exit Function, or Exit Property, then LotusScript® does not reset the values.

Errors within error handling routines

If an error occurs during execution of an error-handling routine, that error becomes the current error. Execution ends and the associated error message is displayed.

Example 1

This extended example shows how a run-time error can arise in a script, and how you can modify a script to either avoid or handle the error. The straightforward error processing illustrated here uses the On Error and Resume statements, which you typically use to process errors.

The script includes a sub named GetLine to retrieve some values from the first line of a file whose name the user specifies. For example:

Sub GetLine
   Dim number1 As Integer, number2 As Integer, number3 _
     As Integer
   Dim fileName As String
   ' Prompt the user to enter a file name, and assign the
   ' result.
   fileName$ = InputBox$("Enter a file name: ")
   Open fileName$ For Input As #1      ' This is line 6.
   Input #1, number1%, number2%, number3%
   Print number1%, number2%, number3%    
   ' Print the input values.
   Close #1
End Sub

When the sub GetLine runs, an error occurs at the Open statement if the user enters the name of a nonexistent file when prompted by the InputBox$ function. Because the script does not contain statements to handle the error, LotusScript® ends execution of the script and prints an error message:

Call GetLine()
' Output:
' Fail: RunTime Error 101 Unable to open file at Line 6

Example 2

In this example, the script just shown is modified to include an On Error statement to handle a file-open error when it occurs. If the Open statement fails, LotusScript® prints some identifying information about the error, and requests a new file name from the user, rather than ending script execution and printing an error message.

Sub GetLine
   Dim number1 As Integer, number2 As Integer, number3 _
    As Integer
   Dim fileName As String
   ' Designate an error-handling routine to handle an error.
   On Error GoTo NoExist
GetName:
   fileName$ = InputBox$("Enter a file name: ")
   Open fileName$ For Input As #1    ' This is line 8.
   Input #1, number1%, number2%, number3%
   Print number1%, number2%, number3%
   Close #1
   ' Done. Exit from the sub GetLine. (Don't continue on
   ' to the error-handling routine at the label NoExist.)
   Exit Sub
NoExist:
   ' Come here when any error occurs.
   ' Print the values of built-in functions that give
   ' information about the error: an error message,
   ' the error number, and the line number in the script
   ' where the error occurred.
   Print Error(), Err(), Erl()
   ' Resume execution at the label GetName.
   Resume GetName
End Sub
Call GetLine()
' The user twice enters a file name that doesn't exist,
' and then a valid file name. The values read in from
' the file are 11, 22, and 0. 
' Output:
' Unable to open file         101           8 
' Unable to open file         101           8
' 11            22            0