Support & downloads
Search result
Feedback

Support & downloads >

Lotus Education On Demand: Notes Error Trapping in LotusScript

Education

Abstract

Introduction
Introduction to Error Trapping
Processing Runtime Errors

Handling Runtime Errors
Detecting Errors with the On Error Statement
Defining an Error Handler
Using Error Identification Functions

Additional Methods for Trapping Errors
Using Error Constants
Trapping Pre-Defined Runtime Errors
Defining Your Own Errors
Using Return Values of Methods to Detect Errors
Using Object Properties to Detect Errors

Detecting ODBC Errors
Using ODBC Object Methods

Exercises
Exercise: Error Trapping
Exercise Solutions

Content

Please note that these Notes/Domino tutorials are no longer being updated, and are presented here as an archive of information.

Introduction

Introduction to Error Trapping
LotusScript recognizes two types of errors:

Compiler errors
These types of errors are found and reported when the compiler attempts to compile a script. They must be corrected before the script can be run. For example, incorrect syntax of a statement is a compiler error.
Runtime errors
These types of errors are found when a script is executed. These errors cannot be predicted at compile time and prevent the script from running to completion. Trying to open a file that does not exist is an example of a runtime error.

This Learning Byte concentrates on how to process or handle runtime errors.

Processing Runtime Errors
If a runtime error is encountered, LotusScript displays a message and the script terminates. You can override this default behavior.

To control the way the script reacts to a runtime error, do the following:

1. Detect, or trap, the error.
2. Execute the correct error handling routine.
3. Continue processing.

Handling Runtime Errors

Detecting Errors with the On Error Statement
The On Error statement intercepts runtime errors and passes control to an error handling routine.

Place the On Error statement in your code to trap runtime errors that might occur. These statements should be placed at the top of your script. If an error occurs later in the script, LotusScript will know how to handle it.

Syntax
The On Error statement has the following syntax:

On Error GoTo label

Example
To direct the program code to an error handling routine labeled ErrorHandler when any runtime error occurs, write the following:

On Error GoTo errorHandler
%Rem
'...other processing statements
%End Rem
Exit Sub
errorHandler:
'... general error handling code

Defining an Error Handler
An error handler, or error handling, routine is a block of code that performs an action designed to resolve a runtime error. It can be specific to a particular error or general to handle any runtime error.

There are three components to an error handler. The table shows a description of each component:

Example
The following is an example of an error handler that informs the user that an error has occurred and then returns to execute the statement following the one that caused the error:

...
On Error GoTo errorHandler
...
Exit Sub
%REM
errorHandler:
MessageBox "An Error Occurred"
Resume Next

Using Error Identification Functions
When a recognized error occurs during execution of a script, information about that error is recorded. This information can be retrieved and used in an error handler.

LotusScript functions shown in the table retrieve information about the last error that occurred:

Example
This error handler will display the string corresponding to the error that just occurred.

...
On Error GoTo errorHandler
...
...
errorHandler:
...
MessageBox("Error: " + ERROR$)
...

Additional Methods for Trapping Errors

Using Error Constants
Runtime errors are identified by error numbers. These error numbers are defined as constants in files provided by LotusScript. See below for a list of the error constant files and a description of their contents.

File Name Description
LSERR.LSS Error constants
LSXBEERR.LSS Back-end object error constants
LSXUIERR.LSS Front-end object error constants
LSCONST.LSS Non-error constants

To use the error constants defined in these files in your code, add the following line to the object's declarations event:

%INCLUDE "filename.LSS"

Trapping Pre-Defined Runtime Errors
You can trap specific runtime errors that are pre-defined in the error constant files.

Syntax
On Error [error constant] GoTo label

Example
When attempting to open a database, use the On Error statement and the error constant IsERR_NOTES_DBOPEN_FAILED to detect if the database was not opened successfully.

%INCLUDE "LSERR.LSS"
' other statements
On Error lsERR_NOTES_DBOPEN_FAILED GoTo openFailed
' other statements

If an attempt is made to open a database that does not exist, the openFailed function will be executed.

Defining Your Own Errors
LotusScript allows you to define your own errors to meet the specific needs of your script.

To define your own errors, do the following:

1. Define a constant to represent your error condition.
2. Use the Error statement to signal the occurrence of your error.
3. Use the On Error statement to invoke an error handling routine when your error occurs.

Example
The code sample below, illustrates how to define an error for an invalid input value. If the input is not within the specified range of values, the OutOfRange error is signaled and the invalidInput routine is triggered.

Const OutOfRange = 9999
...
On Error OutOfRange GoTo invalidInput
...
If input < MinValue & input > MaxValue Then Error OutOfRange
...
invalidInput:
'...display message to user asking for a new input value

Using Return Values of Methods to Detect Errors
Some methods return a value to indicate a condition resulting from its execution. Based on this return value you can invoke an error handler.

Example
The Open method of a database object will return a value indicating if the database was opened successfully or not. If the return value is False, the database was not opened and the openFailed error handler is invoked.
Dim status as Boolean

...
status = db.Open("",InputBox$("Filename"))
If status = FalseThen GoTo openFailed
...
openFailed:
...

Using Object Properties to Detect Errors
You can also test for errors using object properties.

Example
The IsOpen property of a database object indicates if the database is opened. If the value of the IsOpen property is False after a database is opened, you can invoke the openFailed error handler.

...
db.Open("";filename);
If db.IsOpen = False Then Goto openFailed
...
openFailed:
...

Detecting ODBC Errors

Using ODBC Object Methods
LotusScript contains three methods (see below) designed to retrieve ODBC errors for the ODBCConnection, ODBCQuery, and ODBCResultSet classes.

Method Description
GetError Returns the error code value
GetErrorMessage Returns a short text description of the error
GetExtendedErrorMessage Returns a long text description of the error

Example
The following example shows how to use GetError to locate and trap errors:

Dim con as New ODBCConnection
Dim datasource As String
datasource = "ZZZZ" ' assume this does not exit
call con.ConnectTo(datasource)
If con.GetError <> DBstsSuccess then
MessageBox("ODBC ERROR: " + con.GetErrorMessage(con.GetError))
...

Exercises

Exercise: Error Trapping

Introduction
The ETBike.nsf database contains information about different bicycle parts and the vendors that supply them. The Etex.nsf database contains a form that will retrieve a list of parts based on a specific vendor. Your job is to trap and handle possible errors in this operation.

Instructions

1. Download the following two databases to your notes\data directory:

Error Trapping - Bikeparts: ETBike.nsf (attached below)
Error Trapping Exercise: Etex.nsf (attached below)

2. Open the Vendor Parts form in the Error Trapping Exercise database.

3. Add code to trap the error LSERR_NOTES_DATABASE_NOTOPEN to prevent processing on the Bikeparts database if it was not opened successfully. This error constant is defined in the LotusScript back-end error constants file. Include it in the (Global) Options area.

If the error occurs, display a message and exit from the subroutine.

4. Create a user defined error constant to be trapped if the Vendor field is left blank.

If the error occurs, display a message informing the user that this field must be supplied and place the cursor in the Vendor field. Hint: Use the NotesUIDocument gotofield method.

5. Test your error trapping:

Click Query without specifying a vendor's name.
Change the open database statement so that it does not find the database (for example, use the wrong path or use a database name that does not exist).

Exercise Solutions
In the (Global) Options area:

Option Public
%INCLUDE "LSXBEERR.lss"
Const ERR_NOVENDOR = 9999

In the Click event of the Query button:

Sub Click(Source As Button)

On Error LSERR_NOTES_DATABASE_NOTOPEN Goto ErrorDbNotOpen
On Error ERR_NOVENDOR Goto ErrorNoVendor

'-- A vendor must be entered
If doc.Vendor(0) = "" Then Error ERR_NOVENDOR

'-- Instantiate a ETBIKE.NSF NotesDatabase object
Dim db As New NotesDatabase( "", "ETBIKE")

'-- Instantiate a NotesDateTime object
Dim datetime As New NotesDateTime( "1/1/90")

'-- Create search string for database search
searchformula$ = "Vendor = " & """" + doc.Vendor(0) + """"

'-- Perform Search
Set collection = db.search( searchformula$, datetime, 0 )

'-- Dont automatically reload front end fields
uidoc.AutoReload = False

'-- Populate the table via the backend
Call PopulateTable

'-- Reload the backend values to the front end
Call uidoc.reload

Dim RetCode As Integer

Goto alldone
'------------------------------------------------------------------
Error Processing '------------------------------------------------------------------

ErrorNoVendor :
'-- A vendor must be entered
RetCode% = Messagebox("Please Select a Vendor", MB_OK + MB_ICONSTOP, "Invalid Vendor")
uidoc.gotofield("Vendor")
Exit Sub

ErrorDbNotOpen :
'-- Database not open
RetCode% = Messagebox("Cannot Open " & db.filename, MB_OK + MB_ICONSTOP, "Database Error")
Exit Sub

'------------------------------------------------------------------
alldone:

End Sub

Cross Reference information

Segment	Product	Component	Platform	Version	Edition
Messaging Applications	Lotus Domino	Not Applicable

IBM, the IBM logo and ibm.com are trademarks of International Business Machines Corp., registered in many jurisdictions worldwide. Other product and service names might be trademarks of IBM or other companies. A current list of IBM trademarks is available on the Web at "Copyright and trademark information" at www.ibm.com/legal/copytrade.shtml.

Document information


Product categories:

	Software

	Messaging Applications

	E-Mail

	Lotus End of Support Products

	Lotus Notes


Operating system(s):
	Mac OS, Windows

Software version:
	4.5, 4.6, 5.0, 6.0

Reference #:
	7005908

IBM Group:
	Software Group

Modified date:
	2005-04-27

Translate My Page

Rate this page

Help us improve this page. Your response will be used to improve our document content. Requests for assistance, if applicable, should be submitted through your normal support channel as we cannot respond from this site.