Sample Programs1

Chapter 2-3

Sample Programs

Overview

The HCL C API Toolkit for Domino and Notes contains many sample programs that show you how to use various aspects of the C API. The samples are divided into the following groups:

Administration

Advanced Server

Basic

Client

Database Design

DB2

Mail

Miscellaneous

Rich Text

Server

Views

HTML

CALAPI

OS

TIME

The sample descriptions below indicate the platforms each sample supports. Some samples do not support all platforms, but each sample contains valuable code relevant to all platforms. HCL C API functions for Domino and Notes are largely the same on every platform. Frequently, only the makefile varies from platform to platform.

Note that the sample programs use the minimum stack sizes necessary for execution. Other applications may require larger stack sizes.

Basic

These programs are in the basic samples directory.

ALLFLDS (Windows, AIX, Linux RedHat, IBM i)
Finds all the fields in all the documents in a database

CAPIERR (Windows)
Shows how to load an error message string given a Domino or Notes error code, from a Windows MFC C++ application.

COPYDB (Windows, AIX, Linux RedHat, IBM i)
Copies all the components of one database to another

CPNOTES (Windows, AIX, Linux RedHat, IBM i)
Selectively copies documents from one database to another based on various criteria, including modification time

DBPROPS (Windows, IBM i, Linux)
Shows how to get and set some of the database properties available to the HCL C API.

GETBUILD (Windows, AIX, Linux RedHat, IBM i)
Shows how to get the major build number identifying the version of Domino or Notes installed

INTRO (Windows, AIX, Linux RedHat, IBM i)
Shows the basic structure of a character-mode HCL C API program, as well as how to access a database that is on a remote HCL Domino Server. Uses main as the main entry point.

INTROWIN (Windows)
Shows the basic structure of a Windows application that makes HCL C API calls

MSIMPLE (Windows, AIX, Linux RedHat, IBM i)
Modifies fields with simple data types

NOTESMAIN (Windows, AIX, IBM i, Linux RedHat, )
Shows the basic structure of a character-mode HCL C API program, as well as how to access a database that is on a remote HCL Domino Server. Uses NotesMain as the main entry point.

NUMLIST (Windows, AIX, Linux RedHat, IBM i)
Writes a field of type number list

RSIMPLE (Windows, AIX, Linux RedHat, IBM i)
Reads fields with simple data types
(This sample demonstrates a basic sequential search of a database.)

SRCH_ALL (Windows, AIX, Linux RedHat, IBM i)
Search for and process all documents in a database
(This sample shows how to guarantee that each document is only processed once during a sequential search.)

SUMMARY (Windows, AIX, Linux RedHat, IBM i)
Finds and prints all summary data of all data notes in a database, without opening the data notes

WSIMPLE (Windows, AIX, Linux RedHat, IBM i)
Writes fields with simple data types: text, number, date/time, text list

sizeofHANDLE (Windows, IBM i)
Show length of some HANDLEs

Views

These programs are in the views samples directory.

NAMELOOK (Windows, IBM i, Linux)
Look up names in the Personal Address book and retrieve items

NAVIGATE (Windows, IBM i, Linux)
Performs complex navigation of a view index

ONECAT (Windows, IBM i, Linux)
Lists all the documents in one category in a view

TEXTKEY (Windows, IBM i, Linux)
Finds documents in a view based on a single text key

TWOKEY (Windows, AIX, IBM i, Linux RedHat)
Finds documents in a view based on two sort keys of different data types

VIEWIDS (Windows, AIX,Linux RedHat, IBM i)
Finds all the documents in a view and lists their note IDs

VIEWSUMM (Windows, AIX, Linux RedHat, IBM i)
Prints the summary information in a view
(This program essentially duplicates a view as you see it at the user interface. The view summary is useful because it allows you to extract fields from the documents in a view without opening the documents.)

Rich Text

These programs are in the richtext samples directory.

BIG_RICH (Windows, Linux)
Creates rich text fields from character text files up to five megabytes long using Compound Text functions

CDFILE (Windows, AIX, Linux RedHat, IBM i)
Two programs to read and write a rich text (CD) file: CDFWRITE writes text to a CD file, and CDFREAD reads a CD file and stores it in the rich text field of a document

DOCLINK (Windows, IBM i)
Adds a document link, a view link and a database link to a rich text field, using the low-level structures of a document, view and database link

DUMPFONT (Windows, AIX, Linux RedHat, IBM i)
Locates and prints out the font tables in all data notes

DYNAMIC (Windows, AIX, Linux RedHat, IBM i)
Same as WRICH, but uses dynamic allocation of the data structures
(This technique is useful if you do not know at compile time exactly what the rich text field will contain.)

EASYRICH (Windows, AIX, Linux RedHat, IBM i)
Creates a rich text field using the simplest HCL C API functions
(If you want to write a rich text field, read this sample first.)

FONTBL (Windows, AIX, IBM i, Linux RedHat)
Adds a font table to a document and writes some rich text to a rich text field, using fonts from the font table

HISTORY (Windows)
Collects all response documents into the rich text field of the corresponding main document

HOTSPOT (Windows, AIX, Linux RedHat, IBM i)
Creates a document with a popup, a button with formula, a bar, a URL, and a file attachment

IMPORTER (Windows)
Imports graphics objects or word-processing files into a rich text field by calling a Notes import library

JVAPPLET(Windows, Linux RedHat, IBM i)
Embed a Java applet in a rich text field in a document.

LGIMPORT(Windows)
Imports large (>64K) graphics objects or word-processing files into a rich text field
(This sample calls a Notes import library and breaks the result into multiple rich text fields with the same name.)

MKTABLE (Windows, AIX, Linux RedHat, IBM i)
Adds a table to a rich text field, using the low-level structures of a table

OLE2\ATTACH (Windows)
Embeds an OLE 2 object which has been streamed to a structured storage file into a rich text field of a document

OLE2\EXTRACT (Windows)
Extracts embedded OLE 2 objects to structured storage files

OLE2\OLEASSOC (Windows)
Associate file(s) with an embedded OLE 2 object.

OLE2\DISASSOC (Windows)
Disassociate file(s) from an embedded OLE 2 object.

OLE2\GETASSOC (Windows)
List file(s) associated with an embedded OLE 2 object.

RRICH (Windows, IBM i)
Reads a rich text field.

WRICH (Windows, IBM i)
Creates a rich text field using low-level data structures
(For advanced features of rich text fields, you will need to use these structures. The structures are statically allocated in this example, which is useful as a tutorial or if the rich text item you want to create will always be same.)

Database Design

These programs are in the dbdesign samples directory.

ADDMACRO (AIX, Linux RedHat, IBM i)
Adds several agents to a database - uses lower level functionality than the agents sample

ADDQUERYARGS (Windows, Linux)
Builds a various types of input values to a Domino Query Language (DQL)

AGENTS (Windows, AIX, Linux RedHat, IBM i)
Creates and executes several agent notes in a database

DBPOLICY (Windows)
Creates a database Policy Document (Help - About This Database document) and a database Help Document (Help - Using This Database document)

DES_COLL (Windows, AIX, Linux RedHat, IBM i)
Reads the design collection of any database and displays the type and name of each form, view, macro, and replication formula

FORMULA (Windows, AIX, Linux RedHat, IBM i)
Runs a formula against a note in a database, returning a value

MAKEFORM (Windows, AIX, Linux RedHat, IBM i)
Creates a new form in a database

MAKENAV (Windows, AIX , Linux RedHat, IBM i)
Creates a new navigator view and/or items in a database

MAKEVIEW (Windows, AIX, Linux RedHat, IBM i)
Creates a new view in a database

NSFQUERY (Windows, Linux)
Creates various types of queries and then uses them to query the database

READFORM (Windows, AIX, Linux RedHat, IBM i)
Reads the specified form note and displays a list of field names and data types

READVIEW (Windows, AIX, Linux RedHat, IBM i)
Reads the specified view note and displays information about the view

RUNMACRO (Windows , IBM i)
Runs an agent in a database - uses lower level functionality than the agents sample

Administration

These programs are in the admin samples directory.

ACLS (Windows, AIX, Linux RedHat, IBM i)
Reads in a database access control list, modifies it, and displays information contained in it

ACTIVITY (Windows, AIX, Linux RedHat, IBM i)
Illustrates usage of Activity Logging APIs.

AUTH_FLD (Windows, AIX, Linux RedHat, IBM i)
Shows how to create document-level security fields

BACKUP (Windows)
Shows how to backup and restore databases, as well as archive transactional system logs

DUSSPI (Windows)
Illustrates Domino Upgrade Services

FIND_DBS (Windows, IBM i, Linux)
Finds all the Domino databases in a given local or remote directory

LDAP_MSC (Windows, IBM i, Linux)
Adds, modifies, searches for and compares LDAP entries.

PERFORM (Windows, AIX, Linux RedHat, IBM i)
Tests the performance of transactions such as database I/O and indexing on a Domino Directory

PUTGET ( Windows, IBM i, Linux)
Data import and export tools
(The directory includes source code, sample files, and a user guide. The tools are particularly useful for importing third-party data to a Domino database.)

SECDOM (Windows, AIX,IBM i, Linux)
Creates a DSAPI filter library that will, from the web, authenticate a Domino user through his Operating System account.

SEL_REP (Windows,IBM i)
Creates a replication formula note to enable selective replication in a database

SERVLIST (Windows)
Finds all the available HCL Domino Servers listed in the user's home/mail server's Domino Directory.

SETPRIVS (Windows, IBM i, Linux)
Sets the read access privilege levels or read access name list of all documents in a database

TRACKER (Windows, IBM i)
Demonstrates capabilities of a Note Open/Note Update Hook Driver
(TRACKER logs all access to a database, writes a "Request Number" field to new documents when they are saved, and saves documents to a "trash can" database when they are deleted.)

USERREG (Windows, AIX, IBM i, Linux RedHat)
Illustrates how to register a new hierarchical certifier, server, and user

Server

These programs are in the server samples directory.

ADDIN (Windows, AIX, IBM i, Linux RedHat )
Shows the structure of a HCL C API add-in task for a HCL Domino Server
(This version uses "Text" functions instead of application resources.)

ADD_RES (Windows, IBM i, Linux)
Shows the structure of a HCL C API add-in task for a HCL Domino Server
(This version uses application resources.)

EVENTS (Windows, IBM i, Linux)
Demonstrates user-defined events

MGATE (Windows)
A sample mail gateway

MSG_Q (Windows, IBM i, Linux)
Demonstrates sending messages from the server console to an add-in task via a message queue
Includes an additional add-in task MSG_T that sends messages directly to the MSG_Q task

STATDEMO (Windows, IBM i, Linux)
Periodically updates a database with information from the statistics reporting routines

THREADS (Windows, AIX, Linux RedHat, IBM i)
Demonstrates multi-threaded API program support within the structure of an add-in task and uses message queues for thread communication

Mail

These programs are in the mail samples directory.

EXTMAIL (Windows)
Implements an extension manager that traps a user mail message, modifies the body of the message, and then sends the user mail information and a log file of C API processing.

NAMEBOOK (Windows, IBM i, Linux)
Lists all Address books identified by the NAMES variable in the notes.ini file.

READMAIL (Windows, AIX, IBM i, Linux RedHat)
Prints the contents of a message (mail) file using Mail Gateway C API functions.

SENDMAIL (Windows, IBM i, Linux)
Sends a mail memo using Mail Gateway C API functions.

SENDMEMO (Windows, IBM i, Linux)
Sends a memo using NSF C API functions.

MAILCERT (Windows, IBM i, Linux)
Demonstrate how to enumerate certificates in a S/MIME mail.

SENDEASYMM(Windows, IBM i, Linux)
Demonstrate how to create a easy MIME(Multipurpose Internet Mail Extensions) message.

SENDATTMM(Windows, IBM i, Linux)
Demonstrate how to create a MIME(Multipurpose Internet Mail Extensions) message with embedded attachment.

READMMTXT(Windows, IBM i, Linux)
Demonstrate how to get the text contents from the MIME messages without converting them to CD format.

PARSEMMMSG(Windows, IBM i, Linux)
Demonstrate how to parse the structure of the MIME messages

Miscellaneous

These programs are in the misc samples directory.

ALARM (Windows)
Demonstates the Alarm C API functionality

DBDRIVE (Windows, IBM i)
Implements a driver DLL that allows Domino or Notes to access data in non-Domino databases using the functions @DbLookup and @DbColumn

EDITFAX (Windows)
Demonstates the usage of the editfax APIs.

ENCRYPT (Windows,IBM i)
Demonstrates how to write encryption enabled fields as well as how to read and store encrypted documents in a database, using secret and public encryption keys.

EXTCONF (Windows, IBM i)
Implements an extension manager that handles replication conflicts

EXTMNGR (Windows, IBM i)
Implements an extension manager that transforms an existing non-Domino database into a Domino database at Domino database creation time

EXTPWD (Windows, AIX, Linux RedHat, IBM i)
Demonstrates using the Extension Manager to replace the password dialog

FILEATT (Windows, AIX, IBM i, Linux RedHat)
Creates a document with file attachments with no corresponding hotspots

FTSEARCH (Windows, IBM i, Linux)
Demonstrates full-text searching capabilities

GETMULTNOTEINFO (Windows, Windows 64-bit, AIX 32-bit, AIX 64-bit Linux Suse 32bit, IBM i, Linux)
Shows the basic usage of NSFDbGetMultNoteInfo & NSFDbGetMultNoteInfoByUNID.

IDBACKUP (Windows, IBM i)
Demonstrates Notes ID backup and recovery

IDTABLES ( Windows, IBM i, Linux)
Shows how to use ID Tables for various operations with note IDs. also demonstrates operations between the tables.
(ID tables are an efficient method for processing a large set of notes at once.)

ITEMMISC ( Windows, Linux)
This program changes an item value in a document and then copies the item to another document in the same view and renames it. It also checks that the documents in the view have a $Readers field

NIF (Windows, Linux)
Demonstrates the usage of Notes Indexing Facility (NIF) related API calls. Checks whether the view in a database is time-varying,adds a document and checks whetherthe collection is up-to-date, and the note ID is in the view,read view entries and data associated with them, gets the last modified time of the database. It alsogets view rebuild directorypath.

NOTECWF (Windows, IBM i, Linux)
Demonstrates NSFNoteComputeWithForm C API function and validation error callback function

NOTESFLO (Windows)
Demonstrates Notes Field Exchange (Notes/FX) and NotesFlow in a COM/OLE 2 program

NSF_DUMP (Windows, AIX, Linux RedHat, IBM i)
Displays the contents of a database file

RESPONSE (Windows, Linux)
Creates and reads the response documents. It also updates the change in unread documents to the remote server.

SCHEDULE(Windows,IBM i, Linux)
Demonstrates adding appointments and meeting invitations to a User's schedule as well as deleting the scheduled events and retrieving busy/free time information

UNREAD (Windows, AIX, Linux RedHat, IBM i)
Demonstrates obtaining and modifying a table of unread notes for a user in a database file

USER_DEF (Windows, AIX, Linux RedHat, IBM i)
Shows how to create and read fields with user-defined data types
(These fields are useful for storing special objects of your own creation, such as new kinds of graphics, data encrypted with your own scheme, and so on.)

XML\EXPORT (Windows, IBM i)
Illustrates the DXL Export functionality for exporting Domino/Notes data into XML format.

XML\IMPORT (Windows, IBM i, Linux)
Illustrates the DXL Import functionality for importing XML data into Domino/Notes data.

ARCHSVC\ARCHEXP (Windows, AIX, Linux RedHat, IBM i)
Illustrates the archive export functionality for export a data note from db into output file.

ARCHSVC\ARCHIMP (Windows, AIX, Linux RedHat, IBM i)
Illustrates the archive import functionality for import the archived file to the specified note and restore the note back to the db.

Advanced Server

These programs are in the advsrvr samples directory.

BILLING(Windows, AIX, IBM i)
Customized Billing add-in and Billing manager samples

CLUSTER(Windows, AIX,IBM i)
Illustrates features of Advanced Server Clusters
(The CLUMON sample supports the administrative tasks associated with viewing server clusters and clustered databases and with updating server restrictions, availability, and database mark options.)

Client

These programs are in the client samples directory.

IEDIT (Windows)
Creates a custom edit-level import library

UIADDIN\UIADDIN1 (Windows)
Illustrates how to implement the Notes menu add-in feature
(Menu add-ins are user-written DLLs that add menu items to the Actions menu in Notes and provide procedures to handle each menu item.)

UIADDIN\UIADDIN2 (Windows)
Demonstrates more complicated Notes menu add-in features
(This sample adds multiple menu items to the Actions menu in Notes and demonstrates how to import data into a field of an open document.)

XEDIT (Windows)
Creates a custom edit-level export library

XVIEW (Windows)
Creates a custom view-level export library

DB2

These programs are in the DB2 samples directory.

NSFDB2FCopy (Windows)
Copy the NSFDB2 database specified and reconnects the copy of the DB2 data as an NSFDB2 database.

NSFDB2FList (Windows)
Provides a list of all NSFDB2 databases.

NSFDB2ReCon (Windows)
Make sure that Domino can access NSFDB2 data for FullPath or rename the NSFDB2 database within the Domino server.

HTML

These programs are in the html samples directory.

ConvertAttach (Windows, IBM i)
Building a program which can be used to convert an attachment file which can be used in HTML format.

ConvertNormal (Windows, IBM i)
Example of convertting an attachment to be HTML format

ConvertPic (Windows, IBM i)
Example of convertting an attachment to be HTML format

Calapi

These programs are in the calapi samples directory.

entryManip (Windows, IBM i, Linux)
Example of create, update, read, delete entries on iCalendar format

entryAction (Windows, IBM i, Linux)
Example of entry actions on iCalendar format

TIME

These programs are in the time samples directory.

GMT (Windows, Linux)
Explains the usage ofextracting ticks and date fromTIMEDATE structure.Alsodescribesusageof GMTtolocal time andvicea versa.

TIMEDATEPAIR (Windows, Linux)
Thisprogramdemonstratesthe usage of,
ConvertTIMEDATEPAIRToText- Converts TIMEDATEPAIR to text format
ConvertTextToTIMEDATEPAIR- Converts Text to TIMEDATEPAIR
This program gets the current date and time and adds one day to itto form the text form of time date pair. It usesConvertTextToTIMEDATEPAIRAPI to convert text into time date pair object.
It uses the time date pair object, which populatedearlierto demonstrateon converting time date pair object to text usingConvertTIMEDATEPAIRToTextAPI.

TIMETEST (Windows, Linux)
Thisprogramdemonstratesthe usage of,
TimeDateCollate- Compares two binary TIMEDATE values.
TimeExtractJulianDate - Extracts the Julian date from a TIMEDATE value.
TimeDateDifferenceFloat - Gives the Floating-point difference between two TIMEDATE values.

OS

These programs are in the os samples directory.

ENVIRONMENT (Windows, Linux)
Demonstrates how toset atimedateinto an environment variableandgetatimedatefromthe environment variable and returns a sequence number that represents the number of times any environment variable has been changed.Here the sequence number changing means the notes.ini file has been changed.If our variable isdynamic,then we can also check if our variable has changed or not.

SHAREDIRECTORY (Windows, Linux)
Demonstrates how to print the path of the shared directory of a multi-user Notes client.