Manage Learn to apply best practices and optimize your operations.

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.

Dig Deeper on LotusScript



  • Favorite iSeries cheat sheets

    Here you'll find a collection of valuable cheat sheets gathered from across the iSeries/ community. These cheat ...

  • HTML cheat sheet

    This is a really cool cheat sheet if you're looking to learn more about HTML. You'll find just about everything you every wanted ...

  • Carol Woodbury: Security

    Carol Woodbury