Lotus Notes
Volume Number: 12
Issue Number: 9
Column Tag: Communication And Collaboration
Driving Lotus Notes From an Application 
Find API-ness in the land of the Lotus-Eaters
By Rick Gansler
Note: Source code files accompanying article are located on MacTech CD-ROM orsource code disks.
Lotus Notes is much more than a groupware or email program; it is a client/server
document-oriented groupware database with a powerful API library that can be used to
create standalone platform-independent C programs. With the introduction of Notes
Release 4 for Mac OS 68K and PowerPC, Lotus has created a Mac client application that
improves on Release 3 in innumerable ways. One such improvement is the inclusion of
the Notes C API for Mac OS.
This article discusses the Notes C API and its implementation for the Mac OS. A
sample API program is listed and explained. The sample program demonstrates how to
export a Notes database in a form that can be compiled as a Newton Book for the Apple
Newton PDA. Also discussed are the Notes C++ API and Vendor Independent Messaging
(VIM) SDK, which will soon be available for the Mac OS.
Introducing Lotus Notes
Lotus Notes enables teams of people to communicate with each other, collaborate on
shared documents, and generate custom workflow applications. The teams may all be
connected to the same local area network, or may be connected via modem or remote
access bridges.
Information is generally stored on a scaleable Notes server in the form of an
encrypted relational database, in which various types of data can be stored. Users can
create their own forms, providing a customized view of the data. Fax, voice mail, and
pager gateways enhance the portability of the data. Interfaces to the Internet and
legacy databases on mainframes further increase the scope of data portability.
The end user sees Notes as a window called the workspace (Figure 1) containing
icons that represent databases. These databases may be stored on a Notes server or on a
local disk or file server. Opening a database presents the user with a view (Figure 2)
of the database, and a list of documents (Figure 3). A view may be thought of as the
sorted result of a search. Each database may have one or more views, and always has a
default view. Opening a document displays a form through which the document’s fields
(or items) are presented.
Figure 1. Notes client application workspace
Figure 2. Notes client application database view
What’s So Special About Notes?
Notes shows its uniqueness in four areas: database replication, database design,
cross-platform support, and application development.
Replication resembles synchronization of files, or mirroring of Web and FTP
sites, only more powerful. Replication is bi-directional, and supports update,
insertion, and deletion. It enables the same database to be stored on multiple servers
and then updated so that all databases have the same contents, structure, and access
controls. Databases can optionally be selectively replicated; this can be applied at the
document or even at the field level. Field-level replication is especially useful when
replicating over a modem, since less data needs to be transferred than when doing
document-level replication. Having databases replicated across multiple servers is
useful, since those servers can be distributed across organizations or time zones,
which distributes the load of user activity among the different servers. Notes
maintains a replication history, keeping track of when data was updated, as well as
what the source of that data was, thus speeding future replications.
Figure 3. Notes client application document
Using data access hooks into Notes, a Notes database can be synchronized with a
legacy database. This feature enables an IS department to keep data and some
applications on a mainframe (for example), yet still allow Notes users to access and
modify that data from a desktop computer.
Databases can be designed using templates and custom forms, a number of
runtime views, @functions (which take arguments, perform logical actions on data,
and return a result), Navigators (which add a GUI with buttons and links on top of the
database), Agents (scheduled and event-driven macros), HotSpots (like buttons),
DocLinks (referring to any Notes document in any Notes database), and URLs
(referring to a Web page via the InterNotes server).
Lotus Notes is truly cross-plaform, and is supported on Mac OS (client only),
Windows 16-bit (client only), Windows 32-bit, OS/2 Warp, NetWare (server only),
and many UNIX platforms including Solaris, HP/UX, and AIX. The Dec Alpha platform
running Windows NT and Dec UNIX will soon be added to this list. A Notes client can
access any Notes server, regardless of platform, using a variety of network protocols.
For the most part, Notes for all platforms have identical functionality and an identical
user interface.
Notes Application Development
There are two ways to accomplish Notes application development. The first is to use
LotusScript, a cross-platform object-oriented event-driven interpreted language,
which can be used in Notes as well as in other Lotus products. LotusScript is
interpreted and cannot be run standalone. The second method is to create standalone
programs using the Notes C API (or any of the other APIs, such as Notes C++ API, that
are built on top of the C API); such standalones run independently of the Notes
application, yet have access to Notes services. Just as different programming
languages exist, each designed for a particular niche, Notes has multiple development
options for programmers having different levels of experience and different
development needs. Since the C API for Mac OS has only very recently been released,
not all of the Notes API Toolkit development environments are available for Macintosh.
Figure 4 shows the different environments, their level of object orientation, and their
target audience.
Visual Basic Extensions (VBX) and OLE2 Extensions (OCX) are not available for
Mac OS, so their Notes implementations cannot be made available either. The HiTest C
API is an object-based (but not C++) layer built on top of the C API. Lotus has not yet
determined if HiTest will be ported to Mac OS. Without HiTest on Mac, there can be no
HiTest Glue, which is implemented as a VBX to provide Visual Basic programmers with
controls that interact with Notes.
(Note that the C API can also be used to build code that is executed by Notes, for
example to make import/export filters, menu add-in modules, and server add-in
tasks. The subject, however, is beyond the scope of this article.)
Figure 4. Notes programming methods
Notes Architecture
The Notes C API is Notes. The API is a large set of Notes functions that have been
exposed for third-party developers to use. This means that the API is as important to
Lotus as it is to developers; Lotus Notes is itself written using many of the same API
calls that are available in the Notes API.
Admittedly, some parts of the Notes client and server applications use functions
that are not available in the API; so an API programmer cannot write a program that
does everything that the Notes client does. Recall, for example, the workspace window
(Figure 1). This window’s list of user databases and their icons is stored in a database
called desktop.nsf; but Notes API calls cannot access this list.
Just the other way, though, some tasks available through the API cannot be
accomplished through the Notes client application’s user interface. For example, if a
user has a document but doesn’t have the form with which the document was created, it
may not be possible to view all fields in that document using the Notes client. (A form
defines what fields can be displayed. Without a form that contains the fields, those
fields are invisible. In this respect, a Notes form is comparable to a Claris FileMaker
layout.) However, an API application can read fields regardless of what form was used
to create the document.
C API applications can generally be as efficient as the client and server itself -
although, since the HiTest C and Notes C++ APIs are built on top of the C API, HiTest C
and Notes C++ applications have an extra layer between them and the Notes Core, and
do therefore incur some performance penalty. Figure 5 shows the layering of
functionality in the Notes architecture.
Figure 5. Notes architecture and the APIs
Notes C API
The API is implemented as a library of over 1000 C language functions, data
structures, and symbolic constants to access Notes databases, network services, and
administration services. The number of exposed functions from Notes Release 3 to
Release 4 has increased by more than 50%, while maintaining compatibility with
source code written for Release 3 API programs. The API is supported on every
platform that supports a Notes client or Notes server.
Why use the Notes C API?
Given that both LotusScript and Agents can be used to automate the Notes client,
and that a GUI interface can be built on top of a database, why should it be necessary to
write a standalone Notes application in C? Notes API applications give the programmer
flexibility and options that are not available in any other way.
There are many situations where it is appropriate to use the API, rather than
developing internally in Notes.
• You may wish to create a customized user interface for a target environment.
• API programs do not require the Notes client application to be running. In
contrast, to run applications using LotusScript or Notes database tools requires
that the Notes client be running, which increases RAM overhead.
• The task may not be achievable using only the tools available within the Notes
client.
• The application may need to integrate tightly with an in-house development
environment other than Notes, or may need to integrate with off-the-shelf code
libraries.
API capabilities
Among other things, the Notes C API can:
• create, delete, and copy Notes databases
• read, write, and modify Notes documents
• search, sort, and index documents in Notes databases
• send mail messages and documents
• read, write, and modify the design of a Notes database
• read, write, and evaluate formulas
• perform system Administration (invoke replication, modify the ACL, log user
access)
API limitations
The Notes C API cannot:
• interact with the Notes user interface (e.g., it can’t force Notes to open a
window)
• access the Notes Desktop database
• run an API program if Notes is not installed
The C API toolkit
The API Toolkit includes the API header files and libraries, a large number of
sample programs, and documentation. The sample programs show how to use the API
functions, using a representative selection of the functions. The Toolkit documentation
comes as two Notes databases, a User’s Guide which introduces the concepts and
functionality of the C API, and gives details on application development for each of the
various supported platforms, and a Reference Guide, which explains every function,
data structure, and symbolic constant used in the C API.
C API application development
C API applications for Mac OS are developed natively on a Macintosh. The official
development environment is MPW using the Symantec C compilers for 68K and
PowerPC. All development tools are included on the Essential Tools and Objects (ETO)
CD-ROM, published by APDA. Makefiles are included for all samples, as are MPW
build scripts that automate the use of the makefiles. In addition to the Symantec
compilers for MPW, the Metrowerks PowerPC compiler for MPW can be used, as can
the Symantec Project Manager for PowerPC and the Metrowerks IDE for PowerPC. The
Mac OS development environments are discussed in detail below.
Data Types
When talking about Notes standalone programmability, it may be useful to forget that
the client application even exists, and think of Notes as an API to a database engine. In
this paradigm, everything is a database. Even email can be accessed via database calls.
All API data structures are logical structures, and not necessarily physical
structures. Programmers should not assume that any data structures in the API
correspond to actual file formats. Notes database file formats are not publicly
available.
Database header
Every database has a header which contains the database title, categories, access
control list, replication history, and the user activity log.
Note (Document)
A note, more commonly called a document, contains its own header followed by
any number of items, which are the actual data fields or items. (The terms item and
field are sometimes used interchangeably.)
Notes canonical format
All Notes internal data is stored in Intel byte ordering with no pad bytes.
Generally, Notes insulates API programs from the details of conversion. For certain
data types, the programmer is responsible for the conversion. The Notes C API User’s
Guide documents this, and the sample programs in the C API Toolkit demonstrate how
and when to do the conversion. In the future, the Notes C++ API will do all the
conversion automatically, and byte ordering and alignment will cease to be an issue.
Each Notes server can support one or more databases. Each database can contain
one or more documents. Each document can contain one or more items. Each item has a