Error Handling in LotusScript Agents

1. Error Handling inLotusScript 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, 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

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 • www.chc-3.com/talks.htm

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 www.chc-3.com