Check those LotusScript errors!

A lesson in proper LotusScript coding.

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"
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
11. Set Sess = New NotesSession
12. Set ThisDb = Sess.CurrentDatabase
13. Set NameView = ThisDb.GetView 
14. Set Doc = NameView.GetDocumentByKey 
15. Summary = Doc.GetItemValue
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
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
12. On Error Goto ErrorReturn
14. Set Sess = New NotesSession
15. Set ThisDb = Sess.CurrentDatabase
17. Set NameView = ThisDb.GetView 
18. If NameView Is Nothing Then Error 
GENERAL_ERROR, "Unable to open view " +
20. Set Doc = NameView.GetDocumentByKey 
21. If Doc Is Nothing Then Error GENERAL_
ERROR, "Cannot find the name " + 
23. Summary = Doc.GetItemValue
24. Summary = Trim$(Summary)
25. If Summary = "" Then Error GENERAL_
ERROR, "Summary for " + SEARCH_STRING 
+ " empty."
27. Msgbox Summary
29. NormalReturn:
30. Exit Sub
32. ErrorReturn:
33. Msgbox "Problem running this code: "
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.

This was first published in July 2004

Dig deeper on LotusScript



Forgot Password?

No problem! Submit your e-mail address below. We'll send you an email containing your password.

Your password has been sent to:



  • iSeries tutorials's tutorials provide in-depth information on the iSeries. Our iSeries tutorials address areas you need to know about...

  • V6R1 upgrade planning checklist

    When upgrading to V6R1, make sure your software will be supported, your programs will function and the correct PTFs have been ...

  • Connecting multiple iSeries systems through DDM

    Working with databases over multiple iSeries systems can be simple when remotely connecting logical partitions with distributed ...