9 73 DOM_SEARCH_DOCUMENTS

9.73 DOM_SEARCH_DOCUMENTS

Þ Note: Built-In Function Rules.

Searches a database for documents/data notes matching selection criteria or using a previously created view. If no selection criteria or view is specified then all documents/data notes in the database will match.

The result of this Built-In Function is a Note ID table which can be used to read documents sequentially using the DOM_GET_NXT_DOCUMENT Built-In Function. When selection criteria is specified, the selection formula is compiled and a Note ID table built for all documents matching the criteria. When a view is specified, a collection will be built for the view and all Note Ids for the collection will be added to the Note ID table.

Note that if selection criteria is specified, it must conform to the same syntax as view selection formulas which consist of Notes @functions, field names and logical operators. Selection criteria must be quoted correctly. The syntax of the selection criteria will not be validated.

When the processing of all documents is complete the DOM_END_SEARCH_DOCS Built-In Function must be used.

Some general guidelines for using a view versus using selection criteria are:

• Use selection criteria to select documents from a database when the selection criteria is not known until run time, if the performance of the program is not important or the program will be run only a few times.

• Use a view to select documents from a database when you want to process the documents in a certain order or the performance of the program is important. You will usually find the document selection using a view to be faster than the equivalent selection using selection criteria.

For use with

LANSA for i YES Visual LANSA for Windows YES Visual LANSA for Linux NO

 

Arguments

No Type Req/ Opt Description Min Len Max Len Min Dec Max Dec 1 A Req Database handle 4 4     2 A Req Search Type: V = View C = Selection Criteria N = None i.e. all documents will be selected. 1 1     3 A Opt View Name - required if Search Type = V 1 128     4 A Opt Selection Criteria - required if Search Type is C - required if Search Type is V and search is done via the Find By Name method. The value entered is a case insensitive match of the primary sort key. 1 255

 

Return Values

No Type Req/ Opt Description Min Len Max Len Min Dec Max Dec 1 A Req Return code OK = Search completed successfully. ER = Search did not complete successfully. 2 2     2 A Req Note ID Table Handle 4 4     3 N Opt No. Note Ids in the Note ID Table i.e. the number of documents selected. 1 15 0 0

 

Examples

Refer to these Domino Built-In Function Examples:

Example 2: Selecting documents from a Database using a view

Example 4: Updating Documents selected from a Browselist

Technical Notes

This Built-In Function uses the standard Lotus Notes APIs IDCreateTable, NSFFormulaCompile, NSFSearch, IDEntries, IDInsert, NIFFindView, NIFOpenCollection, IDCreateTable, NIFReadEntries and NIFCloseCollection. All security and integrity issues related to the use of this Built-In Function are according to normal Lotus Notes API use for the current platform.