error handling in lotusscript agents

© 2005 Wellesley Information Services. All rights reserved.

Error Handling inLotusScript Agents

Chuck ConnellCHC-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



• Identifying compile-time error detection in LotusScript



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






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






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






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






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






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?

GOTCHA!

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!

Questions?

How to Contact Me:Chuck Connellwww.chc-3.com

error handling in lotusscript agents

Documents

error handlers

error log file

clear error reporting

constantscompile time

remembercompile time

periodic agentscompile

view namecompile time

specialcase errors