Overview of the HCL C API for Notes Domino

Chapter 1-1

Overview of the HCL C API for Notes/Domino

What is the HCL C API for Notes/Domino?

The HCL C API for Notes/Domino is a set of subroutines and data structures that allows you to write programs that access Domino databases. The C API subroutines are written in C and you call them from C programs.

With the HCL C API for Notes/Domino, you can write programs that perform a significant subset of the operations available through the Notes user interface and some operations that are not available through the user interface.

Operating Environments

The HCL C API for Notes/Domino supports the same operating environments supported by Notes and Domino.

Likewise, development of IBM i applications requires the HCL C API Toolkit for Notes/Domino for IBM i.

Except where noted in the Reference , you can use each C API function under all operating environments.

Capabilities of the HCL C API for Notes/Domino

Before using the HCL C API for Notes/Domino, it is important to understand what it is designed to do. The C API is a powerful tool, but like any tool it has a few restrictions.

What the HCL C API for Notes/Domino Can Do

The HCL C API for Notes/Domino gives you access to many features of the Notes user interface and a few features that are not found in the user interface. For example, you can:

Create new Domino databases and delete unneeded databases.
Read, write, and modify any document in a database.
Read, write, and modify any of the fields in a document.
Create and use database indexes (views).
Control database access, both with user access lists and roles.
Query and manipulate busy times in the free time database (busytime.nsf).
Gather and report HCL Domino Server performance statistics.
Write custom tasks and add them to the HCL Domino server software.

The C API allows you to treat databases at a high level by creating and deleting entire databases. You can also copy database elements (macros, forms, views, icons, and so on) intact between databases.

You can use the C API to perform any operation on documents and fields in documents. You can create new documents, delete existing documents, and copy documents from one database to another. You can add fields to documents, delete fields from documents, copy fields between documents, read fields, and write into fields.

The C API gives you powerful access to Domino database design features. You can create new views, build indexes using these views, and read the list of documents in a view. You can create new forms and lay out the forms any way you want. You can create or modify agents and run them from a C API program or from Domino or Notes.

The C API also gives you access to some of the Domino system administration features. You can set the user access list on a database, control database privileges, examine the performance statistics gathered by a server, generate server "software events," and consume events that you have generated.

You can query and manipulate busy-time information in the free time database (busytime.nsf) by using the Scheduling APIs.

Finally, the C API lets you extend the software with user-written "add-ins." An add-in can be on the Notes workstation and present the user with your own pull-down menu choices, or it can be on the HCL Domino server, where it forms a new server task that runs alongside the standard HCL Domino server tasks.

What the HCL C API for Notes/Domino Cannot Do

The C API does not let you modify the existing software. You cannot use the C API to remove features that Domino or Notes already has or to change the way a Domino or Notes feature works. For example, you cannot use the C API to modify how the Notes editor operates or to remove the Help pull-down menus.

You cannot use the C API to directly change database user activity logs, or database icons.

You cannot use the C API to access Workstation Security options or the user's Execution Control List (ECL).

You cannot use the C API to manipulate the shared mail database.

Summary

The chart below summarizes the capabilities of the HCL C API for Notes/Domino.

	Read	Write	Use
DB Title	YES	YES	n/a
DB Access Control	YES	YES	automatic
DB Replication Settings	YES	YES	n/a
DB Replication History	YES	YES (Clear the replication history only)	n/a
DB Activity Log	YES	NO	n/a
DB Policy Document	YES	YES	n/a
DB Help Document	YES	YES	n/a
Document	YES	YES	n/a
Form	YES	YES	n/a
View	YES	YES	YES
Macro	YES	YES	YES
Icon	NO	NO	n/a
Formula	YES	YES	YES
Field (all data types)	YES	YES	n/a
Encrypted Field	YES	YES	n/a

Applying the HCL C API for Notes/Domino

You can use the C API to create a wide variety of applications.

One common use of the C API is to create file import/export programs for Notes. A file export program might read a database, extract some of the documents, and put them into a format compatible with a certain typesetter. You might also write a file import program that reads a non-Domino MIS database and creates documents based on the information in the MIS database.

Another application for the C API is periodic maintenance of databases. For example, you can write a program that scans a phone-message database and deletes every message that is more than six months old.

Still another use for the C API is to create databases that combine data from existing databases. You might write a program that reads the databases maintained by each department in your company and then creates a new database containing company-wide information culled from the departments.

You can also use the C API to design databases based on criteria available to the program at run time. For example, a program can receive a mail message with a set of data and a list of user names. The C API can create a new database, design a form and view for displaying the data, and add the user names to the access list for the database.

Any program using the C API can work with other software products using the other software product's API. For example, a program might use an API to read data from a relational database, and then use the C API to write that data to a Domino database.

Formats for HCL C API Programs for Notes/Domino

Programs written using the C API may take a variety of formats. Specifically, you can package C API code into:

Stand-alone applications
HCL Domino server add-in tasks
Notes workstation menu add-ins
Notes workstation import and export libraries
Database hook drivers
Extension manager hook libraries
Drivers for external (non-Domino) databases

In all of these program formats, the "core" C API code is essentially the same: you use the same C API routines to operate on a database. However, depending on the format, there are variations in the entry and exit code and the program start-up method.

Stand-Alone Applications

Stand-alone C API applications are main programs that make C API calls into the Domino or Notes software. Domino server or Notes workstation software does not need to be running before you run these programs.

HCL Domino Server Add-In Tasks

HCL Domino server add-in tasks are custom tasks that you write and add to the set of tasks in the HCL Domino server software.

The HCL Domino server software is composed of approximately eight standard tasks that carry out the server's functions. An add-in task is added to this set and can include any of the C API operations described above. In addition, you can specify the schedule under which the custom task executes. For example, you can run a job each night at 2:00 A.M., every hour, or once per week.

Notes Workstation Menu Add-Ins

Notes workstation add-ins are custom libraries that you write and add to the Notes pull-down menu structure.

A workstation menu add-in can include any of the C API operations. The add-in can create new options in the Notes pull-down menu structure and receive control when the user selects one of these choices. Workstation menu add-ins also have the ability to place text at the cursor location when the user is composing a document.

Currently, you can create workstation menu add-ins with the Windows version of Notes, where they are built as dynamic link libraries (DLLs).

Notes Workstation Import and Export Libraries

Notes workstation import/export libraries are custom libraries that you write and add to the set of Notes import or export choices.

The list of import and export choices available through the Notes user interface is controlled by a matching set of libraries. You can create your own import or export library containing the C API code that imports or exports a new type of file or text. After creating the library, you add it to the set of import/export libraries that is supplied with Notes. The new option appears in the Notes user interface in the import or export dialog box.

Currently, you can add import/export libraries to Notes workstations that run under Windows. You build these libraries as DLLs.

Database Hook Drivers

Database hook drivers are programs that gain control each time a document is opened, updated, or categorized.

Extension manager hook libraries

The Extension Manager loads a shared executable library (for example, a Windows DLL) which can then specify a callback routine to be called before or after Domino or Notes performs internal processing. You can use this feature to track the internal activity of Domino or Notes, perform processing in addition to the standard Domino or Notes processing, or extend the operation of Domino or Notes.

Drivers for External (Non-Domino) Databases

External database drivers are custom libraries you write that let you use the @DbLookup and @DbColumn functions to access data in your own non-Domino databases.

Initializing C API Structures

The C API Toolkit contains definitions for many data structures that are passed into Domino and Notes. When setting C API data structures, first initialize the values of structure members to 0. This will ensure optional structure members are initialized properly.

Return Values of Type STATUS

Many C API functions return a value of type STATUS. A special STATUS value, NOERROR, is defined as zero in the C API. Therefore, C API programs can detect error conditions by checking to see if the STATUS value is logically TRUE. If such a C API function returns a STATUS value other than NOERROR, any output parameter passed into the function may be returned with an undefined value. Do not try to access these output parameters when a C API function returns a STATUS other than NOERROR.

The 16-bit value of a STATUS error code consists of the following fields:

STATUS values are associated with error strings. Error strings are categorized by package (subsystem) code. Package codes are defined in globerr.h. The error strings are defined in the corresponding package's err.h file. For example, suppose you get a return STATUS code of 18867 in decimal:

Decimal	Hex	Binary	Flag Bit	Package Code plus Status Value (hex)	Status Value (hex)	Status Value (decimal)
18867	49B3	0100 1001 1011 0011	01	09B3	B3	179

The first two bits in this example, 01, indicate that the status message came from a remote machine. Clearing this bit leaves us with the package code plus the status value, 09B3, which are used to identify the error string. The package codes are defined in the C API header file, globerr.h. Look for the closest package code that is less than or equal to 09B3.

#define PKG_SERVER 0x0900

In our example, the package code is 0x0900 which is PKG_SERVER. That leaves B3 as the status value which equals 179 decimal. The error strings for the PKG_SERVER package are in srverr.h.

#define ERR_SERVER_NO_RESPONSE PKG_SERVER+179

errortext(ERR_SERVER_NO_RESPONSE,"No response from server for this command")

The C API function OSLoadString translates a C API error code of type STATUS into a character string.

Debug Options

"Just In Time" (JIT) Debugger

Windows only: Beginning with the Notes/Domino 6 release, the method by which Notes/Domino software functions following a crash has been modified.

In the past Notes/Domino would, in the event of a crash, invoke the system's "Just In Time" (JIT) debugger (e.g. Dr. Watson, QNC, MSDEV), but with Notes/Domino 6 this is no longer the case. To aid C API developers, the notes.ini variable, APIDevloper = 1, has been implemented.

When the APIDeveloper = 1 variable is added to the notes.ini file, C API developers can again capture and debug a crashing application using the JIT, much like they could in pre Notes/Domino 6 releases.

In the event of a crash, all Notes/Domino related processes must be terminated before any of them can be restarted.
---