Click here to Skip to main content
Click here to Skip to main content

Searching a Notes Database using MFC/NotesAPI

, 27 May 2003
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 -->

Introduction

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.

Coding

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.

main()

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().

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().

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.

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

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.

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

OSMemFree(hFormula);

SearchProc

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

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.

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.

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.

License

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

Share

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 www.Tingzabraham.com

Comments and Discussions

 
QuestionListing all mailboxes from mail folder in Domnio Server. PinmemberPreeeti0815-Jul-09 19:51 
QuestionDifferentiate between two forms with same name Pinmembersppradip17-Feb-09 17:51 
QuestionHow to get the remaining value fileds PinmemberNanjuSw6-Jan-09 20:49 
Generalproblem in searching documnets by documnetid in views and foldernames PinmemberMember 462746919-Feb-08 23:02 
Generalget seletect document Pinmemberjavierjack1-Nov-07 5:13 
GeneralRe: get seletect document PinmemberImed Hachicha25-May-08 10:38 
GeneralLotus Notes question PinmemberEllen Chou8-Mar-07 7:19 
QuestionHow can I get Letter head for particular recevied mail. ? PinmemberJagdish Vasani25-Nov-06 1:44 
QuestionHow to use the function NSFItemAppend in MFC Pinmemberqqz29-Sep-06 4:21 
GeneralAbout the name of calendar database. PinmemberAmogh12325-Jun-06 20: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. PinmemberAmogh12316-Jun-06 2:20 
GeneralAbout displaying the added contacts in "names.nsf" database. PinmemberAmogh12315-Jun-06 4:17 
GeneralAbout adding contacts to the Lotus Notes. PinmemberAmogh1238-Jun-06 20:19 
GeneralRgarding retrieving Email and Phone number of a particular contact. PinmemberAmogh12331-May-06 20:09 
GeneralRe: Rgarding retrieving Email and Phone number of a particular contact. PinmemberNanjuSw6-Jan-09 20:55 
GeneralImporting VC++ dlls into C#.net application PinmemberSmithasondur22-May-06 19:37 
GeneralInserting data into Lotus Notes PinmemberSmithasondur18-May-06 0:29 
GeneralRe: Inserting data into Lotus Notes PinmemberTiNgZ aBrAhAm18-May-06 0:46 
QuestionHow to send automatically mail via Lotus Notes? PinmemberModjo_jojo9-May-06 1:05 
GeneralProblem Opening a Notes Database! :( Pinmembertee_jay18-Jan-06 20:46 
GeneralRe: Problem Opening a Notes Database! :( Pinmember-e28-Jan-06 7:22 
QuestionRe: Problem Opening a Notes Database! :( PinmemberRobert Yuan25-Mar-08 22:55 
GeneralRe: Problem Opening a Notes Database! :( Pinmember-e26-Mar-08 7:08 
GeneralRe: Problem Opening a Notes Database! :( PinmemberRobert Yuan30-Mar-08 18:52 
GeneralLotus mail, problem in sending rtf file into mail body Pinmemberzeeshan_azmi17-Jan-06 0:03 

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

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

| Advertise | Privacy | Mobile
Web04 | 2.8.140827.1 | Last Updated 28 May 2003
Article Copyright 2003 by Tingz Abraham
Everything else Copyright © CodeProject, 1999-2014
Terms of Service
Layout: fixed | fluid