© 2005 Wellesley Information Services. All rights reserved. Error Handling in LotusScript Agents Chuck Connell CHC-3 Consulting

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

3 Why This Matters Topics covered apply to all scripting situations  Pull-down actions, 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

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

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

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

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

8 Compile Time, Option Declare (cont.) Declare Agent Demo

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

10 Compile Time, Explicit Data Types (cont.) True Type Agent Demo

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

12 Compile Time, Constants (cont.) Code Sample: Constants

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”

14 Compile Time, Soft Field Names (cont.) Code Sample: Soft Fields

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

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

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

18 Compile Time, Check Notes Objects (cont.) Any missing object is reported immediately Code Sample: Check Objects Good

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

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

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

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

23 Error Handlers – Sample (cont.) Code Sample: Error Handler

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

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

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

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

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?

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

30 Resources Domino Designer 6 Help / Contents / LotusScript / Error Processing Full scripts for all samples are on conference CD On my Web site 

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

32 Your Turn! How to Contact Me: Chuck Connell