|
|
||||
|
|||||
|
|||||
|
|
|||||
|
|
|
|
||||||||||||||||
|
||||||||||||||||||
 | ||
 |  Error Trapping in LotusScript Back to Main Menu 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 Introduction Introduction to Error Trapping LotusScript recognizes two types of 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. 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. Back to Table of Contents 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. Back to Table of Contents 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 Back to Table of Contents 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 Back to Table of Contents 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$) ... Back to Table of Contents 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. Click here for a list of the error constant files and a description of their contents. 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" Back to Table of Contents 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. Back to Table of Contents 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 Back to Table of Contents 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: ... Back to Table of Contents 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: ... Back to Table of Contents Detecting ODBC Errors Using ODBC Object Methods LotusScript contains three methods designed to retrieve ODBC errors for the ODBCConnection, ODBCQuery, and ODBCResultSet classes. 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)) ... Back to Table of Contents 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: Error Trapping Exercise: 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:
Back to Table of Contents 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 Back to Table of Contents | |
 |
|||||
|
