Check those LotusScript errors!

One of my pet peeves is poor error checking in LotusScript code. Even though we often use it for quick-and-dirty tasks within Domino/Notes, LotusScript is a real programming language and deserves to be treated as such.

The best way to illustrate the problem is with an example:

1. Const NAME_VIEW = "AllByName"
2. Const SUMMARY_FIELD = "Summary"
3. Const SEARCH_STRING = "Tim Lewis"
4. 
5. Dim Sess As NotesSession
6. Dim ThisDb As NotesDatabase
7. Dim NameView As NotesView
8. Dim Doc As NotesDocument
9. Dim Summary As String
10.
11. Set Sess = New NotesSession
12. Set ThisDb = Sess.CurrentDatabase
13. Set NameView = ThisDb.GetView 
(NAME_VIEW)
14. Set Doc = NameView.GetDocumentByKey 
(SEARCH_STRING)
15. Summary = Doc.GetItemValue
(SUMMARY_FIELD)(0)        
16. 'We need the summary field later 
in the program, hope it was there.
17. Msgbox Summary

If you have spent a lot of time working with Domino/Notes, you have probably seen code like this. What's wrong with it? A lot. Let's suppose the view AllByName does not exist. Line 13 will fail and the view object NameView will be set to Nothing. Every other line in the program will fail as well, since the main view is missing. But, because there is no error checking, the LotusScript interpreter will try to continue processing, and will fail on line 14. (NameView is Nothing, so it does not have a method named GetDocumentByKey.) The user will receive the cryptic "object variable not set" error message, which does not really explain what the problem is.

What if view AllByName does exist? The code still has other problems. Line 14 assumes the view contains a document with the name "Tim Lewis." If there is no such document, line 14 will fail and set Doc to Nothing. Again, all lines that follow are invalid, and the user will see another mysterious "object variable not set" message. A similar problem is found at line 15, which assumes that a field named Summary is present in the document. If it is not, the variable Summary will be set to the empty string. This is technically correct, but the comment tells us that we need a non-empty value for this string.

Here is the same code sample, with better error handling included:

1. Const NAME_VIEW = "AllByName"
2. Const SUMMARY_FIELD = "Summary"
3. Const SEARCH_STRING = "Tim Lewis"
4. Const GENERAL_ERROR = 1001
5.
6. Dim Sess As NotesSession
7. Dim ThisDb As NotesDatabase
8. Dim NameView As NotesView
9. Dim Doc As NotesDocument
10. Dim Summary As String
11.
12. On Error Goto ErrorReturn
13.
14. Set Sess = New NotesSession
15. Set ThisDb = Sess.CurrentDatabase
16.
17. Set NameView = ThisDb.GetView 
(NAME_VIEW)
18. If NameView Is Nothing Then Error 
GENERAL_ERROR, "Unable to open view " +
NAME_VIEW
19.
20. Set Doc = NameView.GetDocumentByKey 
(SEARCH_STRING)
21. If Doc Is Nothing Then Error GENERAL_
ERROR, "Cannot find the name " + 
SEARCH_STRING
22.
23. Summary = Doc.GetItemValue
(SUMMARY_FIELD)(0)        
24. Summary = Trim$(Summary)
25. If Summary = "" Then Error GENERAL_
ERROR, "Summary for " + SEARCH_STRING 
+ " empty."
26. 
27. Msgbox Summary
28. 
29. NormalReturn:
30. Exit Sub
31. 
32. ErrorReturn:
33. Msgbox "Problem running this code: "
 + Error$, MB_OK + MB_ICONSTOP, "ERROR"
34. Exit Sub

Line 12 creates an error handling routine, which is found at line 32. The error handler is used in lines 18, 21 and 25. The three error conditions described above are checked for explicitly, with a meaningful error message displayed to the user in each case. Also, for each error, processing is halted so additional errors don't pile on top of each other.

In a follow-up tip next month, I will discuss the built-in LotusScript error handling mechanism (lines 12 and 32) in more detail and show how you can control it for your benefit.

More information can be found at Domino Designer Help / Contents / LotusScript / Error Processing.

About the author: Chuck Connell is president of CHC-3 Consulting, which helps organizations with all aspects of Domino and Notes.

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.