Click here to Skip to main content
12,821,084 members (33,121 online)
Click here to Skip to main content
Add your own
alternative version


23 bookmarked
Posted 27 May 2003

Searching a Notes Database using MFC/NotesAPI

, 27 May 2003 CPOL
Rate this:
Please Sign up or sign in to vote.
Searching a Lotus Notes Database and locating notes in the database using Lotus C APIs and MFC.
<!-- Add the rest of your HTML here -->


This .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.

The Code

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]\DbSearch.exe. [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.
#include <global.h>
#include <nsfdb.h>
#include <nsfsearc.h>
#include <nsfnote.h>
#include <osmem.h>
global.h contains the global information. nsfdb.h is needed for opening and closing Notes Databases. nsfsearc.h contains methods for searching through the documents in the Database. nsfnote.h is needed for opening and closing documents, and osmem.h is needed for freeing the handle memory.


The .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 NotesInit() and NotesTerm(). <PRE lang=c++>int main() { NotesInit(); // Any other code has to come between these two lines NotesTerm(); }

The 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 NOERROR. 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 NSFDbOpen. 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 @All.

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.

The 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( void* ActionParam, SEARCH_MATCH* pSM, ITEM_TABLE* SummaryBuffer)

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 NULL.

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, 0, (TCHAR *) (LPCSTR) strFormula, len, &hFormula, &wLen, &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);


The 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.

pSM is the SEARCH_MATCH info that is passed to the function by NFSSearch based on the current record being processed. The SummaryBuffer is the pointer to the ITEM_TABLE structure. The information in SummaryBuffer consists of an ITEM_TABLE structure, followed by an array of ITEM structures, followed by a packed sequence of item names followed by a packed sequence of item values. This will be NULL unless the SEARCH_SUMMARY flag has been set in the fourth parameter to NSFSearch<CODE>. <P>The code that follows simply opens each note using the <CODE>NoteID and retrieves the FirstName and LastName items in the document. (Please do change the Item Names to suit your requirements). The NSFNoteOpen takes in the NoteID as the parameter and returns the handle to the opened note, hNote. <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[560]; NSFItemGetText(hNote, "FirstName", str, 560);

Note:Use the 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.

The Output

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.


This article, along with any associated source code and files, is licensed under The Code Project Open License (CPOL)


About the Author

Tingz Abraham
United States United States
When Tingz Abraham was old enough to realize that computers were going to invade the world, he decided to pursue a career that would keep him close to computers. That landed him a job as an IT Solutions Consultant in Seattle, USA where he currently works. He believes he can program in many languages, including English. Ctrl+C and Ctrl+V are his favorite keys on the keyboard.

After he found he sucked real bad at playing the violin, he just stuck to the guitar and piano. He has a ravishing need for speed and takes a fancy to anything with wheels, including his black Mustang which he's aptly named 'Tingzmobile'.

At work you can constantly hear him say - "Oh! The things I learn after I know it all!" He keeps himself very busy, and in his spare time he keeps wondering why '24 hours a day is just not enough'.

He exists at

You may also be interested in...


Comments and Discussions

QuestionListing all mailboxes from mail folder in Domnio Server. Pin
Preeeti0815-Jul-09 20:51
memberPreeeti0815-Jul-09 20:51 
QuestionDifferentiate between two forms with same name Pin
sppradip17-Feb-09 18:51
membersppradip17-Feb-09 18:51 
QuestionHow to get the remaining value fileds Pin
NanjuSw6-Jan-09 21:49
memberNanjuSw6-Jan-09 21:49 
Generalproblem in searching documnets by documnetid in views and foldernames Pin
Member 462746920-Feb-08 0:02
memberMember 462746920-Feb-08 0:02 
Generalget seletect document Pin
javierjack1-Nov-07 6:13
memberjavierjack1-Nov-07 6:13 
GeneralRe: get seletect document Pin
Imed Hachicha25-May-08 11:38
memberImed Hachicha25-May-08 11:38 
GeneralLotus Notes question Pin
Ellen Chou8-Mar-07 8:19
memberEllen Chou8-Mar-07 8:19 
QuestionHow can I get Letter head for particular recevied mail. ? Pin
Jagdish Vasani25-Nov-06 2:44
memberJagdish Vasani25-Nov-06 2:44 
QuestionHow to use the function NSFItemAppend in MFC Pin
qqz29-Sep-06 5:21
memberqqz29-Sep-06 5:21 
GeneralAbout the name of calendar database. Pin
Amogh12325-Jun-06 21:53
memberAmogh12325-Jun-06 21:53 
GeneralAbout displaying the added contacts in "names.nsf" database, please check my code and tell me the mistake or if some code needs to be added. Pin
Amogh12316-Jun-06 3:20
memberAmogh12316-Jun-06 3:20 
GeneralAbout displaying the added contacts in "names.nsf" database. Pin
Amogh12315-Jun-06 5:17
memberAmogh12315-Jun-06 5:17 
GeneralAbout adding contacts to the Lotus Notes. Pin
Amogh1238-Jun-06 21:19
memberAmogh1238-Jun-06 21:19 
GeneralRgarding retrieving Email and Phone number of a particular contact. Pin
Amogh12331-May-06 21:09
memberAmogh12331-May-06 21:09 
GeneralRe: Rgarding retrieving Email and Phone number of a particular contact. Pin
NanjuSw6-Jan-09 21:55
memberNanjuSw6-Jan-09 21:55 
GeneralImporting VC++ dlls into application Pin
Smithasondur22-May-06 20:37
memberSmithasondur22-May-06 20:37 
GeneralInserting data into Lotus Notes Pin
Smithasondur18-May-06 1:29
memberSmithasondur18-May-06 1:29 
GeneralRe: Inserting data into Lotus Notes Pin
TiNgZ aBrAhAm18-May-06 1:46
memberTiNgZ aBrAhAm18-May-06 1:46 
QuestionHow to send automatically mail via Lotus Notes? Pin
Modjo_jojo9-May-06 2:05
memberModjo_jojo9-May-06 2:05 
GeneralProblem Opening a Notes Database! :( Pin
tee_jay18-Jan-06 21:46
membertee_jay18-Jan-06 21:46 
GeneralRe: Problem Opening a Notes Database! :( Pin
-e28-Jan-06 8:22
member-e28-Jan-06 8:22 
QuestionRe: Problem Opening a Notes Database! :( Pin
Robert Yuan25-Mar-08 23:55
memberRobert Yuan25-Mar-08 23:55 
GeneralRe: Problem Opening a Notes Database! :( Pin
-e26-Mar-08 8:08
member-e26-Mar-08 8:08 
GeneralRe: Problem Opening a Notes Database! :( Pin
Robert Yuan30-Mar-08 19:52
memberRobert Yuan30-Mar-08 19:52 
GeneralLotus mail, problem in sending rtf file into mail body Pin
zeeshan_azmi17-Jan-06 1:03
memberzeeshan_azmi17-Jan-06 1:03 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Praise Praise    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.

Permalink | Advertise | Privacy | Terms of Use | Mobile
Web02 | 2.8.170308.1 | Last Updated 28 May 2003
Article Copyright 2003 by Tingz Abraham
Everything else Copyright © CodeProject, 1999-2017
Layout: fixed | fluid