Given selection criteria for a document, returns documents in a database that:

• The current agent considers to be unprocessed
• Meet the criteria
• Were created or modified since the cutoff date

Defined in

NotesDatabase

Syntax

Set notesDocumentCollection = notesDatabase.UnprocessedSearch( formula$, notesDateTime, maxDocs% )

Parameters

formula$

String. A Notes @function formula that defines the selection criteria.

A cutoff date. The method searches only documents created or modified since the cutoff date.

Integer. The maximum number of documents you want returned. Set this parameter to 0 to receive all matching documents.

notesDocumentCollection

NotesDocumentCollection. A collection of documents that are unprocessed, match the selection criteria, and were created or modified after the cutoff date. The collection is sorted by relevance, with highest relevance first.

This method is valid only for agent or view action scripts, and may be invoked only on NotesDatabase objects obtained from the CurrentDatabase property in NotesSession. In scripts that are not a part of an agent or view action, this method returns a NotesDocumentCollection with zero documents. When invoked on a NotesDatabase object that was not obtained from the CurrentDatabase property, this method raises an error.

How does it work?

This method works in two parts:

• First, it finds a collection of documents that the agent or view action considers to be "unprocessed." The type of agent or view action determines which documents are considered to be unprocessed. This document collection is identical to that returned by the UnprocessedDocuments property.
• Next, it conducts a search on the unprocessed documents, and returns a collection of those documents that match the selection criteria and were created or modified since the cutoff date.

What documents are returned?

The following table describes the documents that are returned by the UnprocessedSearch method. Document selection occurs once, before the agent runs.

Agent runs on	UnprocessedSearch returns documents that meet all of these requirements
All documents in database	Meet the search criteria specified in Agent Properties box Meet the @function search criteria specified in this method
All new & modified documents	Not processed by this agent with UpdateProcessedDoc Created or modified since the agent last ran Meet the search criteria specified in Agent Properties box Meet the @function search criteria specified in this method
All unread documents in view	Are unread and in the view Meet the search criteria specified in Agent Properties box Meet the @function search criteria specified in this method
All documents in view	Are in the view Meet the search criteria specified in Agent Properties box Meet the @function search criteria specified in this method
All selected documents or View action	Are selected in the view Meet the search criteria specified in Agent Properties box Meet the @function search criteria specified in this method
None	Is the current document only
Newly received mail documents	Mailed to the database since the agent last ran Meet the search criteria specified in Agent Properties box Meet the @function search criteria specified in this method
Newly modified documents	Modified since the agent last ran Meet the search criteria specified in Agent Properties box Meet the @function search criteria specified in this method
Pasted documents	Pasted into the database since the agent last ran Meet the search criteria specified in Agent Properties box Meet the @function search criteria specified in this method

Using UpdateProcessedDoc

For agents that run on new and modified documents, newly received mail documents, pasted documents, or newly modified documents, you must use the UpdateProcessedDoc method in NotesSession to mark each document as "processed," which ensures that a document gets processed by the agent only once (unless it's modified, mailed, or pasted again). If you do not call this method for each document, the agent processes the same documents the next time it runs.

UpdateProcessedDoc marks a document as processed only for the particular agent from which it is called. Using UpdateProcessedDoc in one agent has no effect on the documents that another agent processes.

In all other agents and view actions, UpdateProcessedDoc has no effect.

View actions

When used in a view action, UnprocessedSearch returns the same documents as an agent that runs on selected documents.

Language cross-reference

unprocessedSearch method in Java AgentContext class

EditSelectByDate @command function in formula language

Example
See Also

Collecting documents by searching in LotusScript classes

Glossary