Home > Domino Tips > Developer > LotusScript > How to correctly use the GetDocumentByUnid method in LotusScript
Domino Tips:
EMAIL THIS
 TIPS & NEWSLETTERS TOPICS 

LOTUSSCRIPT

How to correctly use the GetDocumentByUnid method in LotusScript


Marcel Dupont
02.05.2008
Rating: -3.20- (out of 5)


Lotus Notes and Domino tips, tutorials and how-to articles
Digg This!    StumbleUpon Toolbar StumbleUpon    Bookmark with Delicious Del.icio.us    Add to Google


VIEW MEMBER FEEDACK TO THIS TIP
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

Related resources from SearchDomino.com:
Tutorial: 30 LotusScript tips

LotusScript Learning Guide

LotusScript Reference Center

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.

Rate this Tip
To rate tips, you must be a member of SearchDomino.com.
Register now to start rating these tips. Log in if you are already a member.


Submit a Tip




Digg This!    StumbleUpon Toolbar StumbleUpon    Bookmark with Delicious Del.icio.us    Add to Google



RELATED CONTENT
LotusScript
LotusScript finds the first occurrence of a string from the right
Clear Recent Contacts view and prevent repopulation in Lotus Notes 8.x
Search Microsoft Active Directory with LotusScript
Three steps to trap and handle save conflicts with LotusScript
Troubleshoot agents by displaying LotusScript variables online
LotusScript sorts lists alphabetically
LotusScript code rebuilds corrupted busytime.nsf file
Soft-code item names to facilitate LotusScript management
LotusScript agent automates selective mail file replication
LotusScript filters and attaches files to a Notes form

LotusScript
LotusScript finds the first occurrence of a string from the right
Clear Recent Contacts view and prevent repopulation in Lotus Notes 8.x
Search Microsoft Active Directory with LotusScript
Three steps to trap and handle save conflicts with LotusScript
Troubleshoot agents by displaying LotusScript variables online
LotusScript sorts lists alphabetically
Run or restart Notes/Domino agents via text messages
LotusScript code rebuilds corrupted busytime.nsf file
Soft-code item names to facilitate LotusScript management
LotusScript agent automates selective mail file replication

RELATED RESOURCES
2020software.com, trial software downloads for accounting software, ERP software, CRM software and business software systems
Search Bitpipe.com for the latest white papers and business webcasts
Whatis.com, the online computer dictionary

DISCLAIMER: Our Tips Exchange is a forum for you to share technical advice and expertise with your peers and to learn from other enterprise IT professionals. TechTarget provides the infrastructure to facilitate this sharing of information. However, we cannot guarantee the accuracy or validity of the material submitted. You agree that your use of the Ask The Expert services and your reliance on any questions, answers, information or other materials received through this Web site is at your own risk.



Domino & Lotus Notes Security Solutions: Authentication, Antispam, Encryption and Antivirus
HomeTopicsITKnowledge ExchangeTipsAsk the ExpertsMultimediaWhite PapersDomino IT Downloads
About Us  |  Contact Us  |  For Advertisers  |  For Business Partners  |  Site Index  |  RSS
SEARCH 
TechTarget provides technology professionals with the information they need to perform their jobs - from developing strategy, to making cost-effective purchase decisions and managing their organizations' technology projects - with its network of technology-specific websites, events and online magazines.

TechTarget Corporate Web Site  |  Media Kits  |  Site Map




All Rights Reserved, Copyright 1999 - 2009, TechTarget | Read our Privacy Policy
  TechTarget - The IT Media ROI Experts