How to correctly use the GetDocumentByUnid method in LotusScript
Developers often use the LotusScript GetDocumentByUnid method incorrectly and get ghost Lotus Notes documents or errors. Learn the right way to use it.
Domino developers typically try to retrieve Lotus Notes documents by using the GetDocumentByUnid method in LotusScript like this:
set doc = db.Getdocumentbyunid(unid$) if doc is nothing then ' Do something else ' Do something end if
This is actually an incorrect way of implementing the GetDocumentByUnid in LotusScript. When the GetDocumentByUnid method doesn't find a Lotus Notes document, it gives an error message. Also, if used improperly, it may return an irrelevant "ghost" Lotus Notes document, also known as a deletion stub.
Use this LotusScript function instead to correctly and safely return a relevant Lotus Notes document (or nothing, if there isn't one):
set doc = DatabaseGetDocumentByUnid (db, unid$) if doc is nothing then ' Do something else ' Do something end if
Here is the LotusScript function:
Function DatabaseGetDocumentByUnid (db As NotesDatabase, unid$) As NotesDocument On Error 4091 Resume Next Set DatabaseGetDocumentByUnid = Nothing Set DatabaseGetDocumentByUnid = db.GetDocumentByUnid(unid$) If Err = 4091 And ( DatabaseGetDocumentByUnid Is Nothing ) Then Err = 0 Set DatabaseGetDocumentByUnid = Nothing Exit Function End If If DatabaseGetDocumentByUnid Is Nothing Then Set DatabaseGetDocumentByUnid = Nothing Exit Function End If If DatabaseGetDocumentByUnid.Size = 0 Or DatabaseGetDocumentByUnid.UniversalID = "" Or DatabaseGetDocumentByUnid.IsDeleted Then Set DatabaseGetDocumentByUnid = Nothing Exit Function End If End Function
I would add one additional check to the bottom of this method, which I think is an excellent example of code reuse and data abstraction in LotusScript.
I would modify the following block of code:
If DatabaseGetDocumentByUnid.Size = 0 Or DatabaseGetDocumentByUnid.UniversalID = "" Or DatabaseGetDocumentByUnid.IsDeleted Then Set DatabaseGetDocumentByUnid = Nothing Exit Function End If
I would include an additional check for .IsValid. The .IsValid command will tell you if the document is initially in existence (not a deletion stub). Because deletion stubs are visible from the indexer, any Lotus Notes documents that are deleted before the indexer runs will not be valid -- but they won't appear as deleted either. You must check for .IsValid as well. Try the following:
If DatabaseGetDocumentByUnid.Size = 0 Or _ DatabaseGetDocumentByUnid.UniversalID = "" Or _ DatabaseGetDocumentByUnid.IsDeleted Or _ (Not DatabaseGetDocumentByUnid.IsValid) Then Set DatabaseGetDocumentByUnid = Nothing Exit Function End If
Todd F.
******************************************
To accomplish this, I simply use GetDocumentByUnid and code similar to:
If not (doc is nothing) then If doc.IsValid And Not doc.IsDeleted Then…
Larry D.
******************************************
This is how this function should have been written:
Function DatabaseGetDocumentByUnid (db As NotesDatabase, unid$) As NotesDocument On Error Goto ErrorHandler Set DatabaseGetDocumentByUnid = Nothing Set DatabaseGetDocumentByUnid = db.GetDocumentByUnid(unid$) If DatabaseGetDocumentByUnid Is Nothing Then Set DatabaseGetDocumentByUnid = Nothing Else If DatabaseGetDocumentByUnid.Size = 0 Or _ DatabaseGetDocumentByUnid.UniversalID = "" Or _ DatabaseGetDocumentByUnid.IsDeleted Then Set DatabaseGetDocumentByUnid = Nothing End If End If Exit Function ErrorHandler: If Err = 4091 Then If DatabaseGetDocumentByUnid Is Nothing Then Set DatabaseGetDocumentByUnid = Nothing End If Resume Next Else Resume ExitWithError End If ExitWithError: End Function
David D.
Do you have comments on this tip? Let us know.
This tip was submitted to the SearchDomino.com tip library by member Fabrice Proudhon. Please let others know how useful it is via the rating scale below. Do you have a useful Lotus Notes, Domino, Workplace or WebSphere tip or code snippet to share? Submit it to our monthly tip contest and you could win a prize.