It's sometimes helpful to create a collection of documents "ad hoc," adding documents to it as you go along processing some other set of documents. For instance, you might like to keep a list of documents whose Status field needs to be updated, but you don't actually want to do the updates until you're all done with the rest of your processing.
This document discusses how to do this efficiently.
Method NotesDatabase.CreateDocumentCollection
If you explore the design of the Notes mail file, you may discover that there's a method NotesDatabase.CreateDocumentCollection which does exactly what we're after. It was added in version 8.0. The function is undocumented, but a documentation update has been submitted and should appear in some future version. There is a known issue (crash, SPR AGUD7LPRDW) if you call this method on a database that has not been opened yet.
If you prefer, or for versions previous to 8.0, read on for alternate techniques.
Use NotesDatabase.Search
You can create an empty collection fairly quickly using NotesDatabase.Search. The Search method is slow in general, but there's an efficient way to use it if all you need is an empty collection.
Dim coll As NotesDocumentCollection
Dim tomorrow As New NotesDateTime("")
tomorrow.SetNow
tomorrow.AdjustDay 1
Set coll = db.Search("@False", tomorrow, 1)
The date/time argument limits the documents searched to those modified after the specified date/time. Since the database generally will not contain any documents modified in the future, this search will actually not have to look at any documents; it just looks at the table of document modification times to notice that there are no documents that meet the criteria. This is pretty fast even in databases with many documents.
Some developers have used other methods that involve creating an empty hidden view (or folder), so that they can request all documents in the view. However, adding views has performance implications for the server generally, and should not be done just for programming convenience. In addition, such code is not as easy to port to another application since it doesn't work if you forget to grab the view also.
Alternate Techniques
The NotesDocumentCollection class is not the only way to maintain a collection of documents. For instance, the List datatype can also be used for this purpose:
Dim docsList List As NotesDocument
...
Set docsList(doc.NoteID) = doc
...
Forall docInLoop In docsList
There are several advantages to using the List datatype; for one, you can create a collection of documents that don't all come from the same database.
Also, the ability to search for documents by their list tag is occasionally useful in conjunction with a list tag other than the UNID or note ID. For instance, you might want the collection to contain documents with a unique set of customer IDs, but only the latest document for each customer. Use the customer ID as your list key, then the IsElement function lets you quickly determine whether a given document would be a duplicate if you added it to the list.
Otherwise, LotusScript also lets you create your own collection classes to handle customized sorting or other functions that NotesDocumentCollection does not support.
Note, however, that there's a limit to the number of NotesDocument objects you can have active in memory simultaneously, so this may not be appropriate for very large collections.