By Rick Gansler, Consultant, Lotus Notes C API Group

Lotus Notes and the Apple Newton have much in common. Notes is an information entry/retrieval system, but more importantly it is used to electronically distribute data. The Newton is also used to enter and retrieve data, but more importantly it is used to physically transport data. Notes information distribution comes under the "groupware" umbrella, in that information is shared among users in different locations. The Newton's data is portable, in that it travels with the user. By implementing connectivity between Notes and Newton, the Newton gains the additional electronic distribution of data, and Notes gains additional physical mobility of data. This article discusses the possibilities for connectivity, and the preliminary work in this area that has already been done at Lotus.

Notes/Newton integration work is being done within the Notes C API group at Lotus. The Charter of the C API group is to develop and support toolkits for programmers to use in creating C applications that view Notes as a database engine, rather than an end user application. Using the C API, a programmer can access Notes databases and network services. Within the C API Toolkit are sample programs (with source code and documentation), including one that demonstrates Notes/Newton integration.

To understand why the Newton is so complimentary to Notes, it is first necessary to understand what Notes is, its functional architecture, and its programmability.

To the casual observer, Notes appears to be a client&endash;server database. A Notes server stores any number of databases, which the Notes client application accesses over a network. (Databases may also be stored locally on the client machine, or on an ordinary file serevr) A database contains a view (the result of selection criteria) of the database, and a list of documents (sometimes called notes). Opening a document displays a form through which the document's fields (or items) are presented.

Databases can be designed using templates and custom defined 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 (which are a scheduled and event driven form of macros), HotSpots (which are a form of buttons), DocLinks (which refer to any Notes document in any Notes database), and URLs (which refer to a Web page via the InterNotes server).

In addition to database design, Notes is programmable using LotusScript and a number of Application Programming Interfaces (APIs). LotusScript is a cross platform, object oriented, event driven, interpreted language, which can be used in Notes as well as in other Lotus products. Developers can also write programs in C (and soon in C++) that interact with Notes. Options include the Notes C API and the HiTest C API (an object layer on top of the C API), as well as using Visual Basic Extensions (VBX) and OLE 2 Extensions (OCX). LotusScript and the Notes C API are available for both MacOS and Windows platforms.

In addition to Notes programmability, replication is an area that sets Notes apart from other databases and client/server tools.

Replication resembles synchronization of files, or mirroring of web and ftp sites, but is far more powerful. Replication is bi&endash;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. Lastly, Notes maintains a replication history, uses of which include speeding future replications by keeping track of when data was updated, as well as what the source of that data was.

Using Data Access hooks into Notes, a Notes database can be synchronized with a legacy database. This feature enables an IS department to keep their data and some applications on a mainframe, for example, yet still allow Notes users to access and modify that data from a desktop computer.

Any connection between Notes and Newton will likely require the programmer to implement synchronization. Replication at the field and document level is not accessible using the API. One way around this limitation is if data from the Newton were exported to the desktop computer, built into a true Notes database, and then have replication invoked. The only API control over replication is to specify the source and target databases, and to invoke replication.

For some time it has been the Lotus strategy has been to implement a Notes browser for many platforms, but that is not necessarily the optimal solution for the Newton. The complexity of a Notes browser might push the limits of what the Newton hardware and operating system could support. In addition, all of the functionality of a full browser for Newton might not be needed. For example, a user would probably not need to design a database on the Newton, but would instead design and initialize the database using a desktop machine. The Newton would be used for entering, viewing, and modifying data.

Instead of writing a lot of Newton software to mimic a Notes browser, it is a better strategy to leverage the Newton's built&endash;in applications, and to provide off&endash;the&endash;shelf and custom software only where necessary. Implementing the Notes architecture and user interface on the Newton is not as important as implementing Notes data interoperability.

Many of the reasons for using Notes data on a Newton are the same as the reasons for using a Newton in the first place &emdash; portability, low cost, long battery life, palm&endash;top operation, and instant on/off. A Newton is less than half the price and a fraction of the weight of a laptop having enough RAM, disk space, and processing power to run Notes.

Depending on the application, using a Newton may be the obvious choice. Forms entry, especially if the form is mostly made of checkboxes and radio buttons, may be much easier to use on a Newton than on a laptop. The design of the form may need to be somewhat different on the Newton as compared to the form in Notes, since its platform and usage is also different. This is in contrast to the traditional way of thinking about Notes, which is to make forms identical regardless of the platform.

Usage of a Newton in addition to using Notes can be considered from two perspectives. First, the data may originate on the Newton, and is transferred to Notes where it is processed and used. A second scenario has data being entered using Notes, and then shared with the Newton where it is viewed and potentially modified.

The hardware communications link between the Newton and Notes can be accomplished using a serial cable, a network (currently only Apple LocalTalk), a modem, or advanced technologies such as two&endash;way wireless pagers. Since the software link is most likely a custom Notes API application, the method chosen to implement the connection is up to the individual developer, and is based on what is appropriate for the given task. In addition to sending editable data, both Notes and Newton have the capability to send and receive faxes.

What is the C API?

The Notes C API is used to build standalone applications that run independently of the Notes application, yet have access to Notes services. The C API is implemented as a library of over 1000 C language functions, data structures, symbolic constants, network services, and administration services. The C API is supported on every platform that supports a Notes client or Notes server.

In addition to building standalone applications, the C API can be used to build code that is executed by Notes. Import/export filters can be built using the C API, and are called by the Notes client. The functionality of a Notes server can be extended by building a "server add&endash;in" task that is loaded and executed on the Notes server.

Overview of the C API Toolkit

The C API is implemented as a shared library on MacOS and UNIX, and as a number of DLLs on Windows and OS/2. The API Toolkit includes the API header files, libraries, a large number of sample programs, and documentation.

The purpose of the sample programs is to provide examples of how to use the API functions. A representative selection of the functions are used in the samples. The sample programs are sorted into a number of directories by functionality &emdash; such as Views, RichText, Database, Mail, and Newton.

The Toolkit includes documentation in the form of two Notes databases. The first is a User's Guide, which introduces the concepts and functionality of the C API, as well as specific details on application development for each of the various supported platforms. The second is a Reference Guide, which explains every function, data structure, and symbolic constant used in the C API.

Lastly, a number of databases are included that are specific to the API sample programs.

Development Environments

The current release of the API Toolkit for MacOS recommends the use of MPW with the Symantec C compilers for 68k and PowerPC. The C API Toolkit includes a MPW UserStartup file and a number of script files and makefiles to ease development of the sample applications, and to provide a foundation for developing new projects. The C API User's Guide that is included with the Toolkit provides extensive documentation on setting up the development environments for each platform that the Notes API supports.

Notes C API PowerPC applications can also be built using the Symantec Project Manager version 8, and PowePC and 68k applications using the Metrowerks version 7 IDE. (As of March 1996, Metrowerks version 8 has not been tested with the Notes C API, but no problems are anticipated.) Information on using the Symantec Project Manager and Metrowerks IDE for Notes C API development can be found at http://www.Lotus.com/devtools/21da.htm.

Notes applications for Windows 16 bit and 32 bit can be built using Microsoft Visual C++, and for OS/2 using IBM C Set++.

Since the level of cross platform compatibility discussed in this article is at the "data" level rather than at the "application" level, understanding how the Notes API represents data is central to understanding the Notes/Newton connection. All of the data types discussed here are logical structures, and do not necessarily represent the physical storage format. All data i/o in Notes is accomplished through Notes API calls, and database files must never be accessed via a platform's file system API.

A Notes server or client can support any number of databases. Each database file contains a header followed by any number of documents.

A document (sometimes called a note) contains its own header followed by any number of items (sometimes called fields).

An item contains the actual data, which is categorized into two groups &emdash; simple data types and composite (complex) data types.

Simple data types include:

• Text and Text List
• Number and Number List
• Time/Date and Time/Date Range or List

Composite data types include:

• Rich Text: Lotus Notes Rich Text is a functional superset of the industry standard Rich Text (Microsoft RTF). However, the data structures used in Lotus Rich Text are different than those used in Microsoft Rich Text. Lotus Notes Rich Text may contain bitmaps and hyperlinks (also called doclinks) to other documents.
• Object: e.g. embedded OLE object, file attachment
• Tables: e.g. spreadsheet&endash;like grid
• User Data: Stored as binary data, and not interpreted by Notes.

The Vendor&endash;Independent Messaging (VIM) Interface began as an industry&endash;standard and platform independent application programming interface specification for messaging systems. It has evolved into the Lotus email standard interface for Notes and ccMail. The VIM API enables programmers to write applications that link the functionality of messaging systems to the functions provided by end&endash;user applications. The Lotus VIM Developer's Toolkit provides header files, libraries, documentation, and sample programs, and is compatible with Notes&endash;based electronic mail.

Some of the features of VIM include: (1) Send messages with file attachments. (2) Search and modify address books. (3) Receive and process delivered messages.

Enabling a link between NotesMail and the Newton would be most easily accomplished using VIM, although the C API could also be used. The C API contains, some, but not all of the functionality of VIM.

The applications that are built into the Newton have a remarkable amount of similarity to the interface functionality of Notes. At the most obvious level, both Newton and Notes have email and a name and address book. While Lotus Organizer is currently a standalone product, future plans include ways to tightly integrate it into Notes, adding yet another similarity with the Newton date book.

Although these programs are not similar enough to say that they provide functional equivalence, they are similar enough to provide adequate representation of each other's data.

For example, to represent a Notes address book within a Newton address book, a number of folders would first need to be setup to represent the Notes views, which are presented as named items within a Notes folder. Since the set of data fields in a Notes address book is richer than the standard Newton fields, a number of custom fields would be set up. The capabilities of the Newton to view, sort, display, and manipulate the contents of the address book is obviously more limited than what can be done in Notes, but the point here is that all data can be represented.

Data can go in the other direction too. The Newton notepad can be represented as a Notes database. The notepad on the Newton is represented as a series of tabbed folders. The list of all folders on the Newton would correspond to the Notes workspace, which uses an icons in a window to represent each database. Each Newton notepad folder would correspond to a Notes database. On the Newton, a folder is made up of a number of notes. In Notes, the same is true. Each Newton note would be saved into a Notes database as a document. The Newton can display an "overview" with the title of each note in the folder. Notes uses a "view" to display the title of each document in the database. Each Newton note is displayed using stationary, which may be one of the three bundled stationaries or one supplied by a third party vendor. Within Notes, the stationary would be represented as a form. Just as with the Newton, Notes permits the creation of custom forms.

It is not enough to be able to import and export data. It must be possible to use that data productively. Notes and the Newton each have their own efficiencies and drawbacks.

One problem with the Newton notepad is that it can not efficiently handle huge notes or huge numbers of notes. A Notes database with five thousand documents could not be represented in the Newton notepad. Notes would prove inefficient with one or two databases each containig one or two documents that contain a quarter k each. The problem with Notes in this case is that opening one small document after another would require so many network hits that it would not be responsive enough to the user.

An approach for notepad/database exchange could be to import Newton notepad data into large Notes databases and documents, and export single Notes documents into the Newton notepad. It is not appropriate to try to mirror the functionality of the other platform.

If huge amounts of Notes data is needed on the Newton, bringing it over as a Newton Book is an excellent option. At Lotus a sample program was developed by the Notes C API group to export the Notes C API User's Guide as a Notes database. In Notes database format, the User's Guide requires just under one megabyte of disk space. As a Newton Book, it requires just over one megabyte of data soup space, and more than 1300 pages. The performance of the Newton Book in switching from one document to another is actually faster than Notes! Unfortunately, Newton Books are not editable, but in this case, people would not need to edit this data. Just because it is possible to edit the User's Guide does not mean that it is necessary to edit the User's Guide.

The program used to create the User's Guide Newton Book is a Notes C API application called MakeBook. The Notes C API Toolkit contains full source code for MakeBook. This program requires the use of the Newton Book Maker application, as well as the Newton Toolkit. MakeBook was demonstrated at the LotusSphere '96 conference in Orlando.

Another method of creating Newton Books from Notes would be to use the Newton Press application. A prototype application that uses Press, a simple Notes C API application, and AppleScript to integrate them has been developed at Lotus, but has not yet been included into the C API Toolkit.

Lastly, integration between Notes and custom or off&endash;the&endash;shelf Newton application is a possible solution for data sharing. There are a few Newton forms programs that support import and export between the MacOS and Windows. The import/export capability could be enhanced to use the Notes C API to read and write Notes data.

The similarities between, as well as the complementary nature of the Apple Newton and Lotus Notes makes Notes/Newton connectivity an area with exciting business opportunities. The functional similarities and capabilities of Notes and the Newton operating system and bundled applications, together with the Notes C API Toolkit and the Newton Toolkit gives developers a robust platform for building both vertical and horizontal products that enable sharing of data.