<!-- Add the rest of your HTML here -->
.exe searches through a Lotus Notes database and locates notes in the database using the
NSFSearch() in Lotus Notes C API 5.03. The code is in MFC.
This code navigates through the 'Contacts View' in your Notes Address book (
names.nsf) and retrieves the document values based on a Notes formula.
Create New Workspace
- Run the VC New Projects wizard. Select Win32 Console Application and specify a project name as DbSearch (for example). Cick on OK to proceed to the other dialogs and select the 'Empty Project' option in the wizard.
- Workspace Settings
- Go to Project Settings (ALT+F7). In the C/C++ tab in preprocessor definitions, add 'NT' or 'W32' at the end of the preprocessor list.
- In the Link tab. In General, in Output file name, specify
[NOTESPATH] is the path in which Notes executable resides your system. For example it would be Drive:\Lotus\Notes.
- For Object/Library modules, enter
notes.lib in the field.
- Go to Tools->Options Menu. In the Directories Tab, select Include files and specify the path of the Notes API Include Directory. For example in my case it was
D:\Notes 5.03 C API\INCLUDE.
- Select Library files and specify the path for the Lib files for your OS. For example in my case it was
D:\Notes 5.03 C API\LIB\MSWIN32.
There are a few notes related header files that need to be included for this exe to compile.
contains the global information.
is needed for opening and closing Notes Databases.
contains methods for searching through the documents in the Database.
is needed for opening and closing documents, and
is needed for freeing the handle memory.
.exe should have a
main() method. Before any Notes related operation is done, some initializations need to be done. This is done by calling the
NotesTerm(). <PRE lang=c++>int main()
// Any other code has to come between these two lines
NotesInit() locates the Notes program and Notes data directories and reads the
notes.ini file. At the end of the program a call to
NotesTerm routine will shut down the Domino or Notes runtime system. Any other code has to come between these two lines.
Now we need to open the address book, namely
names.nsf. This is done using
NSFDbOpen(). <PRE lang=c++>STATUS ret = NSFDbOpen("names.nsf", &hdb);
Since the database will always be found in the Data Directory in your Notes folder, we have not specified the path to the datbase. The second parameter,
hdb, is the handle to the database that is returned. It is of type
DBHANDLE. Many Lotus C API functions for Domino and Notes return a value of type
STATUS. If the call is a success, then the return value of the method will be a
NSFDbOpen must return a '0' for the code to continue. Else we have to exit.
Next we need to do the actual search to scan through the documents of the database. This is the code for the search. <PRE lang=c++>ret = NSFSearch(hdb, // Handle to the Database
hFormula, // Formula Handle
NULL, // View title
0, // Search Flags
NOTE_CLASS_DOCUMENT, // NoteClassMask
NULL, // Since
(NSFSEARCHPROC) SearchProc,// EnumRoutine
NULL, // EnumRoutine parameter
NULL // RetUntil
hdb is the handle to the database that is returned by the
hFormula is of type
FORMULAHANDLE and is obtained by compiling the Notes formula that is needed as the search criteria. Setting this parameter to
NULLHANDLE is equivalent to the selection formula
The third parameter is a pointer to the name of the view to be searched. Since the view title is indicated in the selection formula, this parameter is set to NULL. The fourth parameter contains the search flags which indicate what gets searched, a directory or a database. The fifth parameter is the class of the items to be included in the search. We are searching through documents in a database, so the value of this parameter is passed as
NOTE_CLASS_DOCUMENT. The sixth parameter helps you to filter the search criteria by date. We have set this to
NULL as we do not wish to specify a modification date criterion.
SearchProc is the action routine to be executed for each note found by
NSFSearch. The syntax of the action routine is <PRE lang=c++>STATUS NOTESAPI ActionRoutine(
ActionParam is the optional parameter to be passed to the action routine.
pSM is a pointer to a structure containing information on each note found.
SummaryBuffer is a pointer to the summary buffer that contains an
ITEM_TABLE structure and an array of
ITEM structures. For more information on these please check out the Notes API reference.
The eighth parameter to the
NSFSearch function is the parameter that can be passed to the
SearchProc (corresponding to
ActionParam above) and it is passed as
NULL in our case. The last parameter is the time/date the search was executed. This is also set to
Before we have a look at the
SearchProc let us see how a formula is compiled to be passed to the
SearchProc method. The Notes formula I have used in the example is
SELECT Form = "Person" & @Left(LastName;1) = "S\"
This selects documents that have the 'Form' value as "Person" and LastName starts with "S". Before anything can be done with the formula we need to compile it. <PRE lang=c++>ret = NSFFormulaCompile(NULL,
(TCHAR *) (LPCSTR) strFormula,
&wd, &wd, &wd, &wd, &wd);
strFormula contains the formula that needs to be compiled. Compiling the formula returns a handle to the compiled formula
hFormula. This handle can then be passed on to
NSFSearch. Make sure to free the handle once the
NSFSearch is called by calling <PRE lang=c++>OSMemFree(hFormula);
SearchProc is called once for each note that matches the search criteria. All action routines for
NSFSearch must use this calling sequence. The
SearchProc is called by passing it to
NSFSearch as the seventh parameter.
info that is passed to the function by
based on the current record being processed. The
is the pointer to the
structure. The information in
consists of an
structure, followed by an array of
structures, followed by a packed sequence of item names followed by a packed sequence of item values. This will be
flag has been set in the fourth parameter to
<P>The code that follows simply opens each note using the <CODE>NoteID
and retrieves the
items in the document. (Please do change the Item Names to suit your requirements). The
takes in the
as the parameter and returns the handle to the opened note,
. <PRE lang=c++>NOTEHANDLE hNote;
NSFNoteOpen(hdb, pSM->ID.NoteID, 0, &hNote);
Now we retrieve the Item values from the opened note using
NSFItemGetText. This function takes a handle to an open note
hNote and the name of a text item whose value you wish to get. The function copies the text item into a buffer provided by you, and returns the length of the text that was retrieved. <PRE lang=c++>TCHAR str;
NSFItemGetText(hNote, "FirstName", str, 560);
NSItemGetNumber to get the value of a
TYPE_NUMBER item. Also check out the methods to get values of other data types.
Make sure you call the
NSFNoteClose after the note processing is done.
Compile the code and put the
.exe file in your Notes folder. The output lists out the Names in your address book that start with 'S'.
You can use the same code to Navigate through any database and any view. Please ensure that you make the appropriate changes in the code.