Keywords: Notes, Domino, LotusScript, Java, error, log, NotesLog
Technical Level: Advanced
I have written before about proper error handling within LotusScript code (part 1: "Check those LotusScript errors!" and part 2: "LotusScript error handling"). I am even speaking on this topic at the upcoming Admin2005 conference in Boston.
A particularly useful feature of LotusScript error handling, which I have not addressed, until now, is the NotesLog class. The NotesLog object allows you to create robust permanent error logs from LotusScript programs. And, there is a matching Java class named Log.
So why is this of interest to administrators, as well as programmers? When you run Notes code interactively at a workstation, as a rule you are not concerned about a permanent log of the session. If you get an error report on the screen, you just fix the problem and then run the code again. But suppose you are administering a Domino server with nightly agents. When you arrive at the office in the morning, the first thing you want to do (after you get your hazelnut mochaccino) is find out whether your nightly agents ran correctly.
If your LotusScript code contains simple print statements to report errors, you have to search the Domino server log looking for these messages. The NotesLog class provides a much better way of recording error and status messages from agents. You can designate that each agent writes to its own log file, or that several agents share the same log.
Below is a sample LotusScript program that uses the NotesLog class, followed by some detailed comments about the code.
1) Sub Initialize
2)
3) Const NAME_VIEW = "AllByName"
4) Const INFO_FIELD = "Info"
5) Const SEARCH_STRING =
"Tim Lewis"
6) Const LOG_ID = "Log Test"
' the name of this log stream
7) Const LOG_SERVER = ""
'local machine for now
8) Const LOG_FILE = "
C:\Notes6\Logs\
MyErrors.nsf" 'from
ALOG4.NTF, must use full path
9) Const GENERAL_ERROR = 1001
10)
11) Dim Sess As NotesSession
12) Dim ThisDb As NotesDatabase
13) Dim NameView As NotesView
14) Dim Doc As NotesDocument
15) Dim ErrorLog As NotesLog
16) Dim Information As String
17)
18) On Error Goto ErrorReturn
19)
20) Set Sess = New NotesSession
21) Set ThisDb = Sess.CurrentDatabase
22)
23) Set ErrorLog = New NotesLog
(LOG_ID)
24) Call ErrorLog.OpenNotesLog
(LOG_SERVER, LOG_FILE)
25) Call ErrorLog.LogAction ("Successfully
opened log database.")
26)
27) Set NameView = ThisDb.GetView (NAME_VIEW)
28) If NameView Is Nothing Then Error
GENERAL_ERROR, "Unable to open view " +
NAME_VIEW + "."
29)
30) Set Doc = NameView.GetDocumentByKey
(SEARCH_STRING)
31) If Doc Is Nothing Then Error
GENERAL_ERROR, "Cannot find " +
SEARCH_STRING
+ "."
32)
33) Information = Doc.GetItemValue
(INFO_FIELD)(0)
34) Information = Trim$(Information)
35) If Information = ""
Then Error GENERAL_ERROR, "Info for " +
SEARCH_STRING
+ " was empty."
36)
37) Call ErrorLog.LogAction
("The information field is " + Information + ".")
38)
39) NormalReturn:
40) Call ErrorLog.LogAction
("Program finished with no errors.")
41) Call ErrorLog.Close
43) Exit Sub
43)
44) ErrorReturn:
45) Call ErrorLog.LogError(Err, "Err Msg: "
+ Error$ + ". Near line: " + Cstr
(Erl) + ".")
46) Call ErrorLog.Close
47) Resume ErrorReturn2
48) ErrorReturn2:
49) Exit Sub
50)
51) End Sub
Line 23 creates the NotesLog object, giving it a name taken from line 6. This name is not the filename of the log, but a separate convenient identifier.
Line 24 associates the NotesLog object with a Notes database that will receive the log messages. The database must exist first and should normally be created from the ALOG4.NTF template.
Line 25 makes the first use of the newly opened log database, calling the LogAction method to write a simple status message to the log.
Line 28 invokes an error handling routine if the designated view cannot be opened. The error handler, lines 44 to 49, shows two other methods from the NotesLog class. LogError writes an error message to the log. The first argument to LogError is the error code for the error, and the second argument is any string you want. The error code is included because it is displayed conveniently in the views of the ALOG4 template. The Close method completes the NotesLog stream before the subroutine exits.
Lines 31 and 35 show additional calls to the error handling routine, and lines 40 and 41 show how the log is used during successful program termination.
Bonus question for readers: Why have I included a Resume statement at line 47, which simply transfers control to line 48? One hour of free consulting to the first person with the right answer. (Answers to bonus@chc-3.com.)
For more information, see Domino Designer 6 Help / Index / NotesLog.
Chuck Connell is president of CHC-3 Consulting, which helps organizations with all aspects of Lotus Domino and Notes, including software development, security and system management.
Do you have comments on this tip? Let us know.
Please let others know how useful it is via the rating scale below. Do you have a useful Notes/Domino tip or code to share? Submit it to our monthly tip contest and you could win a prize and a spot in our Hall of Fame.
