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.
This was first published in July 2004