Error Handling in LotusScript Agents
description
Transcript of Error Handling in LotusScript Agents
![Page 1: Error Handling in LotusScript Agents](https://reader035.fdocuments.in/reader035/viewer/2022062301/56815b1b550346895dc8ca06/html5/thumbnails/1.jpg)
© 2005 Wellesley Information Services. All rights reserved.
Error Handling inLotusScript Agents
Chuck ConnellCHC-3 Consulting
![Page 2: Error Handling in LotusScript Agents](https://reader035.fdocuments.in/reader035/viewer/2022062301/56815b1b550346895dc8ca06/html5/thumbnails/2.jpg)
2
What We’ll Cover …
• Looking at the general principles of good software error handling
• Identifying compile-time error detection in LotusScript (LS)
• Understanding runtime error detection and reporting in LS
• Setting up error handlers in LS• Dealing with special-case errors in LS• Using an error log file in LS for periodic agents
![Page 3: Error Handling in LotusScript Agents](https://reader035.fdocuments.in/reader035/viewer/2022062301/56815b1b550346895dc8ca06/html5/thumbnails/3.jpg)
3
Why This Matters
• Topics covered apply to all scripting situations Pull-down actions, email buttons, form/view buttons Form/view/database event triggers Periodic/nightly agents
• Admins need accurate and clear error reporting from server agents Often have a lot to review each morning Hard to diagnose cryptic errors in the server log Must know when something goes wrong, and just what
the problem is Worst thing is not knowing there is a problem
![Page 4: Error Handling in LotusScript Agents](https://reader035.fdocuments.in/reader035/viewer/2022062301/56815b1b550346895dc8ca06/html5/thumbnails/4.jpg)
4
What We’ll Cover …
• Looking at the general principles of good software error handling
• Identifying compile-time error detection in LotusScript
• Understanding runtime error detection and reporting in LS
• Setting up error handlers in LS• Dealing with special-case errors in LS• Using an error log file in LS for periodic agents
![Page 5: Error Handling in LotusScript Agents](https://reader035.fdocuments.in/reader035/viewer/2022062301/56815b1b550346895dc8ca06/html5/thumbnails/5.jpg)
5
Principles of Good Error Handling
• Catch errors as early as possible Design-time is better than code-time Compile-time is better than test-time Testing is better than production Catching errors earlier is cheaper and faster
• Report meaningful error messages Tell the user what is really wrong Suggest how to fix the problem
• Make full use of language’s error mechanisms LotusScript gives you many such tools We will show most during this talk
![Page 6: Error Handling in LotusScript Agents](https://reader035.fdocuments.in/reader035/viewer/2022062301/56815b1b550346895dc8ca06/html5/thumbnails/6.jpg)
6
What We’ll Cover …
• Looking at the general principles of good software error handling
• Identifying compile-time error detection in LotusScript
• Understanding runtime error detection and reporting in LS
• Setting up error handlers in LS• Dealing with special-case errors in LS• Using an error log file in LS for periodic agents
![Page 7: Error Handling in LotusScript Agents](https://reader035.fdocuments.in/reader035/viewer/2022062301/56815b1b550346895dc8ca06/html5/thumbnails/7.jpg)
7
Compile Time, Option Declare
• Option Declare is the single most important line in any LotusScript code Forces all variables to be declared Put it in the Options code section (object) Catches many errors immediately It is OFF by default, should be ON However, developers can change the default in the
Programmer’s Pane properties box
![Page 8: Error Handling in LotusScript Agents](https://reader035.fdocuments.in/reader035/viewer/2022062301/56815b1b550346895dc8ca06/html5/thumbnails/8.jpg)
8
Compile Time, Option Declare (cont.)
Declare Agent Demo
![Page 9: Error Handling in LotusScript Agents](https://reader035.fdocuments.in/reader035/viewer/2022062301/56815b1b550346895dc8ca06/html5/thumbnails/9.jpg)
9
Compile Time, Explicit Data Types
• Variables default to Variant type Convenient, since Variants can be almost anything Also dangerous, since Variants can be almost anything Solution is to put an explicit type on all Dim statements
• Notes: Only small number of situations where Variant is really needed Can use suffix chars for typing (@, #, %, !), but hard to read
and remember
![Page 10: Error Handling in LotusScript Agents](https://reader035.fdocuments.in/reader035/viewer/2022062301/56815b1b550346895dc8ca06/html5/thumbnails/10.jpg)
10
Compile Time, Explicit Data Types (cont.)
True Type Agent Demo
![Page 11: Error Handling in LotusScript Agents](https://reader035.fdocuments.in/reader035/viewer/2022062301/56815b1b550346895dc8ca06/html5/thumbnails/11.jpg)
11
Compile Time, Constants
• Use of constants for embedded text and numbers is SOP for all programming languages
• Somehow, LotusScript programmers often overlook this basic principle
• Why is it related to error handling? If you don’t do it, you will have hard-to-find errors
• Suppose there are 10,000 lines of code; you want to change the view name
![Page 12: Error Handling in LotusScript Agents](https://reader035.fdocuments.in/reader035/viewer/2022062301/56815b1b550346895dc8ca06/html5/thumbnails/12.jpg)
12
Compile Time, Constants (cont.)
Code Sample: Constants
![Page 13: Error Handling in LotusScript Agents](https://reader035.fdocuments.in/reader035/viewer/2022062301/56815b1b550346895dc8ca06/html5/thumbnails/13.jpg)
13
Compile Time, Soft Field Names
• This topic is similar to using constants, except the constants are Notes field names Even programmers who use regular constants often
overlook this application
• Benefit is the same as string/number constants When you want to change a field name (very common),
it is much easier this way
• Suppose there are 100 references to many different field names, and you want to change them
• Code sample, named “Soft Fields”
![Page 14: Error Handling in LotusScript Agents](https://reader035.fdocuments.in/reader035/viewer/2022062301/56815b1b550346895dc8ca06/html5/thumbnails/14.jpg)
14
Compile Time, Soft Field Names (cont.)
Code Sample: Soft Fields
![Page 15: Error Handling in LotusScript Agents](https://reader035.fdocuments.in/reader035/viewer/2022062301/56815b1b550346895dc8ca06/html5/thumbnails/15.jpg)
15
What We’ll Cover …
• Looking at the general principles of good software error handling
• Identifying compile-time error detection in LotusScript
• Understanding runtime error detection and reporting in LS
• Setting up error handlers in LS• Dealing with special-case errors in LS• Using an error log file in LS for periodic agents
![Page 16: Error Handling in LotusScript Agents](https://reader035.fdocuments.in/reader035/viewer/2022062301/56815b1b550346895dc8ca06/html5/thumbnails/16.jpg)
16
Runtime, Check Notes Objects
• Whenever you work with a Notes object, make sure it really exists
• This coding mistake leads to errors that are tough to find The line with the runtime error is often far from the line
with the coding error
![Page 17: Error Handling in LotusScript Agents](https://reader035.fdocuments.in/reader035/viewer/2022062301/56815b1b550346895dc8ca06/html5/thumbnails/17.jpg)
17
Compile Time, Check Notes Objects (cont.)
• We cause runtime error by changing Tim’s name• What line trips the runtime error reporting?
Code Sample: Check Objects
Bad
![Page 18: Error Handling in LotusScript Agents](https://reader035.fdocuments.in/reader035/viewer/2022062301/56815b1b550346895dc8ca06/html5/thumbnails/18.jpg)
18
Compile Time, Check Notes Objects (cont.)
• Any missing object is reported immediately
Code Sample: Check Objects
Good
![Page 19: Error Handling in LotusScript Agents](https://reader035.fdocuments.in/reader035/viewer/2022062301/56815b1b550346895dc8ca06/html5/thumbnails/19.jpg)
19
What We’ll Cover …
• Looking at the general principles of good software error handling
• Identifying compile-time error detection in LotusScript
• Understanding runtime error detection and reporting in LS
• Setting up error handlers in LS• Dealing with special-case errors in LS• Using an error log file in LS for periodic agents
![Page 20: Error Handling in LotusScript Agents](https://reader035.fdocuments.in/reader035/viewer/2022062301/56815b1b550346895dc8ca06/html5/thumbnails/20.jpg)
20
LS Error Handlers, Theory
• When LS encounters a runtime error, it looks for a local user-defined error handler for that error code
• If no local handler is found, LS looks for one in the calling procedure, then the next up calling procedure, etc.
• If none are found, LS calls a simple built-in handler, then exits
• So how do you create an error handler…? Tell LS what error handler to use for each error code Create the error handler routines
![Page 21: Error Handling in LotusScript Agents](https://reader035.fdocuments.in/reader035/viewer/2022062301/56815b1b550346895dc8ca06/html5/thumbnails/21.jpg)
21
Error Handlers – Sample
• Tells LS what to do with an error On Error Goto ErrorReturn Which errors?
All of them What to do?
Go to ErrorReturn label
![Page 22: Error Handling in LotusScript Agents](https://reader035.fdocuments.in/reader035/viewer/2022062301/56815b1b550346895dc8ca06/html5/thumbnails/22.jpg)
22
Error Handlers – Sample (cont.)
• Set up error handler Block of code from ErrorReturn to Exit Sub Notice the Err, Error$, and Erl variables – defined within
error handlers Notice the Resume statement – means that error
handling is done
• You don’t need an error handler in every routine Can allow LS to “fail up” to a higher-level routine This is often good software design
![Page 23: Error Handling in LotusScript Agents](https://reader035.fdocuments.in/reader035/viewer/2022062301/56815b1b550346895dc8ca06/html5/thumbnails/23.jpg)
23
Error Handlers – Sample (cont.)
Code Sample: Error Handler
![Page 24: Error Handling in LotusScript Agents](https://reader035.fdocuments.in/reader035/viewer/2022062301/56815b1b550346895dc8ca06/html5/thumbnails/24.jpg)
24
What We’ll Cover …
• Looking at the general principles of good software error handling
• Identifying compile-time error detection in LotusScript
• Understanding runtime error detection and reporting in LS
• Setting up error handlers in LS• Dealing with special-case errors in LS• Using an error log file in LS for periodic agents
![Page 25: Error Handling in LotusScript Agents](https://reader035.fdocuments.in/reader035/viewer/2022062301/56815b1b550346895dc8ca06/html5/thumbnails/25.jpg)
25
Special Error Handlers
• Sometimes, an LS runtime error is not really an error You don’t want to exit or fail
• Code sample, named Special Errors On Error DIR_ERROR Resume Next Means: “For just error code 76, keep processing”
Test by renaming the temp file
• Other points To get the relevant error code, you usually have to print it out Second general On Error erases the special instructions
![Page 26: Error Handling in LotusScript Agents](https://reader035.fdocuments.in/reader035/viewer/2022062301/56815b1b550346895dc8ca06/html5/thumbnails/26.jpg)
26
What We’ll Cover …
• Looking at the general principles of good software error handling
• Identifying compile-time error detection in LotusScript
• Understanding runtime error detection and reporting in LS
• Setting up error handlers in LS• Dealing with special-case errors in LS• Using an error log file in LS for periodic agents
![Page 27: Error Handling in LotusScript Agents](https://reader035.fdocuments.in/reader035/viewer/2022062301/56815b1b550346895dc8ca06/html5/thumbnails/27.jpg)
27
Notes Error Log
• So, all this looks nice interactively…• But what about nightly agents?
Print statements from periodic agents are written to server log file
These are tough to find in the morning
![Page 28: Error Handling in LotusScript Agents](https://reader035.fdocuments.in/reader035/viewer/2022062301/56815b1b550346895dc8ca06/html5/thumbnails/28.jpg)
28
Notes Error Log (cont.)
• How about a special log file for periodic agents?• Code sample, named Error Log
We will look at each line Log file uses ALOG4NTF template Code uses NotesLog class LogAction vs LogError Handles timestamps, error codes, and messages
• Can anyone see a problem with this code?
GOTCHA!
![Page 29: Error Handling in LotusScript Agents](https://reader035.fdocuments.in/reader035/viewer/2022062301/56815b1b550346895dc8ca06/html5/thumbnails/29.jpg)
29
Notes Error Log, Caution
• Suppose your code has a runtime error before the error log is set up
• For industrial-strength code Create a temporary “print” handler at the start Then switch to the log handler after it is created
![Page 30: Error Handling in LotusScript Agents](https://reader035.fdocuments.in/reader035/viewer/2022062301/56815b1b550346895dc8ca06/html5/thumbnails/30.jpg)
30
Resources
• Domino Designer 6 Help / Contents / LotusScript / Error Processing
• Full scripts for all samples are on conference CD
• On my Web site www.chc-3.com/talks.htm
![Page 31: Error Handling in LotusScript Agents](https://reader035.fdocuments.in/reader035/viewer/2022062301/56815b1b550346895dc8ca06/html5/thumbnails/31.jpg)
31
7 Key Points to Take Home
• Scan code for good LS error handling• Are database, view, and field names soft-coded at
the top?• Is there an On Error statement near the top?• Do early database and view opens have an
immediate validity check? • Do you see Option Declare?• If this is a periodic server agent, do you see the
NotesLog class? • Insist on error handling for all server-based Agents
![Page 32: Error Handling in LotusScript Agents](https://reader035.fdocuments.in/reader035/viewer/2022062301/56815b1b550346895dc8ca06/html5/thumbnails/32.jpg)
32
Your Turn!
Questions?
How to Contact Me:Chuck Connellwww.chc-3.com