How to correctly use the GetDocumentByUnid method in LotusScript

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

MEMBER FEEDBACK TO THIS TIP

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.