Permanent NotesLog and Java log come in handy

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.

Download this free guide

Download: IT Certifications 101

Inside this exclusive essential guide, our independent experts break down which IT certifications are worth your time and effort, and how to get started obtaining them to further your career— including specific certifications that any cloud or desktop pro should seriously consider.

Start Download

• Corporate E-mail Address:

  You forgot to provide an Email Address.

  This email address doesn’t appear to be valid.

  This email address is already registered. Please login.

  You have exceeded the maximum character limit.

  Please provide a Corporate E-mail Address.

• • I agree to TechTarget’s Terms of Use, Privacy Policy, and the transfer of my information to the United States for processing to provide me with relevant information as described in our Privacy Policy.

  Please check the box if you want to proceed.

• • I agree to my information being processed by TechTarget and its Partners to contact me via phone, email, or other means regarding information relevant to my professional interests. I may unsubscribe at any time.

  Please check the box if you want to proceed.

By submitting my Email address I confirm that I have read and accepted the Terms of Use and Declaration of Consent.

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.