Searching a Notes Database using MFC/NotesAPI

• Download demo project - 3 Kb

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

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.