TweetFollow Us on Twitter

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 or source 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 distinct data type. Data types fall into two categories: simple and composite.

Simple data types

Simple data types include:

Text and Text List: e.g., subject field of a mail memo

Number and Number List: e.g., part number or order number

Time/Date and Time/Date Range or List: e.g., date field

Composite data types

Composite data types include:

Rich Text. The functionality provided by Lotus Notes Rich Text is actually a superset of the industry standard (Microsoft RTF). However, the data structures used in Lotus Rich Text are different than those used in Microsoft Rich Text. The C API Toolkit contains sample programs and source code to create and manipulate Rich Text, and to call the import and export libraries to convert between Microsoft Rich Text and Lotus Notes 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., tabulated data, spreadsheet-like grid

User Data: Programmers can define their own data types which are not interpreted by Notes, but are simply stored as a stream of binary data.

Searching a Database

Using the C API, there are four ways to search a Notes database.

Linear: Scans all documents in a database, applying search criteria. This type of search should be used when the search criteria are not known until runtime. The linear search is accomplished using a C API function that takes as an argument a pointer to a function that the programmer defines, called an “action routine”. The action routine is called for each document that matches the search criteria. Linear is an inefficient search method.

Indexed: Uses views to sort and categorize documents. This type of search should be used when the order of matched items is important. At runtime the programmer may create the view to specify the hierarchy.

Full Text: To be used if search keywords might be in Rich Text fields.

Direct Access: Not a search, but if the Note ID of the document or the name of an item within a document is known, it can be accessed directly. In other words, if the programmer knows where the data is, the programmer is not forced to use the search API in order to access it.

Notes Security

Users want to know that their workstations are secure, and IS departments want to know that their servers and networks are secure. With all the talk about the Internet and its being perceived as having low security, developers can take advantage of the fact that Notes is secure.

Notes provides user identification, access control lists, and password protection as well as encryption. It is important to know how this affects API applications, in order to take advantage of the features of Notes security.

User ID (Notes ID)

Every user is assigned a “User ID”, sometimes called a “Notes ID” (not to be confused with a “Note ID”; a User/Notes ID identifies a person, while a Note ID identifies a document or note). A User ID contains the user’s name, a Notes license number, a certificate which enables access to servers which are set up to recognize that certifier, and both a public and private encryption key. To access databases, a user would need a User ID file plus a password. This is far more secure than merely typing a username and a password, since a User ID can only be transmitted electronically (or physically). Notes Release 4 adds an additional level of security over Release 3 by offering encryption on the workstation. An API program can use only one User ID at a time.

Access control lists (ACL)

An Access Control List is a list of users, specifying what level of access each user has to a database. Each entry in the ACL contains a user name, access level, flags, and roles. Every database must contain an ACL.

Server-level security

The user of an API program must have access to the server. An API program cannot open a database that the user could not have opened through the Notes user interface.

Database-level security

Database-level security is controlled by the ACL, which defines who can use a database and what operations they are permitted there.

View-level security

If the view has a read access list, then it is enforced in the API. If the user does not have access to the view, the error message will indicate that the view does not exist.

Form-level security

If a form has a read access list, then it is enforced in the API if the API program implements it. The API ignores the compose access list for forms.

Document-level security

The document read, editor, and author access control lists are enforced by the API. For example, if the user does not have read access to a document, NSFNoteOpen() will fail, and NSFSearch() will not find the document. If a user has read access but not author access, then NSFNoteOpen() will succeed, but NSFNoteUpdate() will fail and will return the error ERR_NOT_AUTHOR.

Section-level security

A form may contain one or more sections. A section is a field that contains a list specifying who can edit the fields that follow the section field. Sections are not a real security feature, though, and an API program can write to or append to any field in a document regardless of section information.

Field-level security

Fields may be encrypted, and it is the responsibility of the API application to decrypt the field.

Encryption

Every Notes user is automatically assigned public and private encryption keys. The public key is usually stored on the Notes server. The private key is usually stored on the user’s hard disk. A “personal” key is just another name for the private key; the personal key is used when a user wants to encrypt a document that will be kept locally.

The public and private keys are used for sending encrypted email. Notes hides the complexity of this from the user, who merely clicks a checkbox to enable encryption. Email is encrypted using the sender’s private key and the recipient’s public key. When the recipient receives the email, it is decrypted using the sender’s public key and the recipient’s private key.

Notes supports attaching a signature to an email, which also makes use of public and private keys.

Domestic vs. international

Notes uses RSA encryption, which has been classified by the US Government as a military technology, and thus the North American version of Notes cannot be exported in its most secure form. To send an encrypted email or document outside of the US or Canada, the International English version of Notes must be used, which has a slightly less but still quite secure level of encryption.

Field-level encryption

Documents are not encrypted; fields are. It is best to think of the document as a collection of items, all of which have been set up as encryption items. For example, the “body” field of an email is encrypted, but the “to” and “cc” fields are not.

Notes C++ API

The C++ API is not yet released, but will soon be available as a general beta release. It is built on top of the C API, and provides true OOP, with all the benefits of C++. One implementation goal of Notes C++ was to minimize the performance overhead. Notes C++ is single-chain, not multiple-inheritance.

Developer benefits

These include:

• Reduced application code size. Much of the code that the C API leaves to the individual developer is handled by the C++ classes in its high-level functions and data abstractions.

• Reduced application debugging and maintenance time, as well as more readable code. Since it is C++, there is type-checking done at compile time. The C++ classes implement run-time exception handling that is supported via “catch” and “throw”. In addition, “failable” functions return status codes, which may be used both as information and to indicate an error.

• Sophisticated memory management. If an object allocates memory, it is responsible for freeing it. If the programmer allocates memory, the programmer is responsible for freeing it. If the programmer allocates an object but forgets to free it, it is automatically freed when the object goes out of scope.

• Ease of learning. The C++ classes are easier to learn than the hundreds of C API functions or the HiTest C objects.

• Rapid development and deployment.

• Multi-platform support. The API will support every platform that the Notes C API supports.

Searching a database

The C++ API has all of the searching capabilities of the C API, plus more. The C++ API-specific navigation includes:

// Iterators (class maintains the state)
ACLEntry = ACLEntryIterator.GetNextEntry();

// Arrays (indexed access to data)
Doc = Documents[i];

// Named data can be directly accessed
Status = Database.GetForm("Discussion Topic", &Form); 

Vendor-Independent Messaging

The Vendor-Independent Messaging (VIM) Interface began as an industry-standard, platform-independent application programming interface specification for messaging systems. It has evolved into the Lotus email standard interface for Notes and ccMail. In addition, various Lotus products have different levels of support for such interfaces as MAPI (Messaging Application Programming Interface), CMC (Common Mail Call), and SMI (Simple Messaging Interface). In future releases, Notes will support POP (Post Office Protocol) and SMTP (Simple Mail Transfer Protocol), but it would be very premature to discuss the level of support for these protocols that will be available through the API.

The VIM API enables programmers to write applications that link the functionality of messaging systems to the functions provided by end-user applications. With VIM, the resulting mail-enabled or mail-aware applications can be developed over a wide range of platforms. VIM provides a single interface that allows programmers to combine the services of various messaging systems into one application. Using the VIM API functions, one can design a number of specialized mail-enabled applications. For example, a programmer could develop an application designed to analyze real-time stock prices and send an email when a particular stock reaches or drops to a certain price.

The Lotus VIM Developer’s Toolkit provides header files, libraries, documentation, and sample programs, and is compatible with Notes-based electronic mail.

VIM does a few things that cannot be done using the C API, and does many things in a manner that is more convenient for the programmer. The C++ API will have a class implementing basic email capabilities; however, keep in mind that the C++ API is built on top of the C API, not VIM.

Some of the most important features of VIM include its ability to:

• compose and send messages with file attachments

• receive, store, and process delivered messages

• search and modify address books

• interoperate with ccMail

Leveraging Apple Technologies

Newton

The Notes C API Toolkit currently contains one Newton sample called MakeBook, and will soon have more. The sample program exports the Notes C API User’s Guide database into a form that can be transferred to the Newton and be read by the built-in Newton Book browser. This requires the use of an Apple-supplied Newton Book “compiler” called Book Maker, plus the Newton Developer Toolkit to build the output of Book Maker into a package and to download that package to the Newton. This program was demonstrated at the LotusSphere ’96 conference in Orlando. Browsing the Notes C API User’s Guide on the Newton is actually faster than browsing it using Notes Release 4 on a PowerPC or a Pentium-based machine, even if the database is stored locally on that machine. (Let us, however, keep this in context. MakeBook, though it could be modified to export any Notes database, is not a general-purpose Notes database export tool for end users, but rather a technology demonstration.)

DILs

Apple has recently released the Newton Desktop Integration Libraries (DILs) to enable developers to write Mac OS and Windows applications that exchange data with the Newton. In the future, the Notes API group may be releasing sample programs that show how to leverage the DILs in Newton/Notes applications. Recall that the MakeBook sample uses another program to transfer the data to the Newton from the Mac or Windows machine; functions in the DILs might handle that task.

OpenDoc

OpenDoc has the potential to be a key Notes development tool, since OpenDoc’s concept of containers and parts is somewhat analogous to the Notes paradigm of the Notes client application and runtime services implemented by databases, LotusScript, and API programs. The Notes API group is looking at ways to integrate the Notes API into OpenDoc to provide sample OpenDoc parts in the Lotus Notes C API Toolkit. Nothing has been planned at this time, but keep in mind that the Windows and OS/2 versions of OpenDoc are being developed by IBM, which recently acquired Lotus.

AppleScript

AppleScript can be used to make an application programmable by end users, and can be used to implement programmability between applications. Although the Notes client application is not AppleScript-aware, it is possible to create an AppleScript-aware application that provides an interface between AppleScript and the Notes C API. (This is very different from scripting the Notes client, a task that should be done using LotusScript.) For example, imagine implementing the AppleScript database suite, or some variation of it, which uses Notes as its database, as implemented via the C API. Another idea would be to use AppleScript to implement a layer on top of VIM, to make it easier for developers to mail-enable their applications. Lotus is also working on a “glue layer” interface between LotusScript and AppleScript.

Mac OS Development Environment

Shared library technology

The C API is implemented as a shared library on Mac OS (as on UNIX; it is implemented as a number of DLLs on Windows and OS/2). Although the library is linked with the application, the actual code does not get copied into the application. If more than one application uses the same shared library, only one copy needs to reside on the user’s machine. Both Notes and the API application call into the same copy of the shared library code. In addition to saving disk space, using shared libraries for Lotus Notes ensures that both Notes and API applications will always be running with the same version of the libraries.

For a long time, Apple did not provide a shared library technology for developers to use. This is the main reason why Notes Release 3 did not have a developer-accessible API. Then Apple implemented the Apple Shared Library Manager (ASLM) for 68K Macintosh models only, followed by the Code Fragment Manager (CFM) for PowerPC Macintosh models only. Thus, when the Notes Release 4 project began, there was no choice but to implement the 68K version with ASLM and the PowerPC version with CFM.

Today, both ASLM and CFM are available on both platforms, but too late for Notes Release 4. While this has no impact on Notes users or on Notes API code, it does have an impact on what linkers can be used to develop a Notes API application. Restriction of linker choices restricts compiler choices, and development environment choices.

MPW support

The current release of the API Toolkit for Mac OS recommends the use of MPW with the Symantec compilers for 68K and PowerPC. It is possible to use the Metrowerks compiler for PowerPC, but not the Metrowerks compiler for 68K, since Metrowerks does not support linking ASLM shared libraries. It is not possible to use Metrowerks to build 68K Notes API applications.

The C API Toolkit includes an 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.

Symantec and Metrowerks project environment support

Notes C API PowerPC applications can be built using the Symantec Project Manager. Notes C API PowerPC and 68K applications can be built using the Metrowerks IDE. Unfortunately, using Symantec Think C for building 68K Notes API applications is extremely difficult, and is not something that is being looked into further at this time.

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, as well as in the documentation that is included with the C API Toolkit.

Support of the Symantec and Metrowerks Project environments for the Notes C++ API Toolkit is a goal, since this will enable developers to use the class browsers, as well as easing the integration with the Symantec and Metrowerks class libraries.

Code Sample

Disclaimer: All of the header files, some macro definitions, and lots of error checking have been removed in an effort to make this code simpler, shorter, and easier to read. The full (and working) source code for this program is included on the Notes C API Toolkit CD-ROM, along with makefiles and build instructions for Mac OS 68K and PowerPC, and Windows 16- and 32-bit.

Listing 1: MakeBook.c

Globals
FILE    *outfile = NULL;
long    uniqueLabelCounter = 0;
char    *field_text;

Main

This standalone program is declared with argc and argv, even though these arguments cannot be used in 
the Mac OS, unless it were to be built as an MPW tool. Aside from the conditional code for initializing the 
Mac OS toolbox, all of this source is 100% platform independent. (The actual sample code on the Notes 
C API Toolkit CD ROM contains a macro that hides platform specific initialization.)

All output from this program goes to a text file, which is created and written using the standard C file i/o routines. 
Again, this choice of file i/o was made for platform independence. In Notes API applications, one may choose 
to use conditionally compiled code to add platform specific file system functionality such as Mac OS file 
types.

NotesInitExtended() is a Notes API function that initializes the Notes runtime library. At the end of main(), 
NotesTerm() is called. Every standalone program must have one set of init and term calls. Multi-threaded 
applications must have one set of calls for each thread. In this program, NotesTerm() is called as part of 
the macro API_RETURN().

The database is opened using NSFDbOpen(), processed with the function ReadDatabase(), and then closed 
using NSFDbClose(). The open function returns a “handle” to the database, which is then used by all functions 
that refer to that database. NSFDbOpen() takes the name of database as a full pathname, or as a filename 
if that database is stored locally. If the database is stored on a Notes server, there is an API function that 
will build the pathname.

void main(int argc, char *argv[])
{
 DBHANDLE db_handle; // handle of source database
 STATUS error = NOERROR;  // return status from API calls

#ifdef MAC
 InitMacToolBox();
#endif

 if ((outfile = fopen("book.src", "w")) != NULL)
 { 
    //
    // Output data that is required by the Apple Book Maker application, for the 
    // creation of a Newton Book.
    //
    // For more information, please refer to the “Newton Book Maker User’s Guide”,
    // which is included with the Apple’s Newton Toolkit for Mac OS and Windows.
    //
 fprintf(outfile, 
"\
.isbn Notes:LOTUS\n\
.date 02/05/96\n\
.author Rick Gansler\n\
.publisher Lotus Development Corp.\n\
.copyright (c) 1996 Lotus Development Corp.\n\
.shorttitle API User\n\
.title Lotus Notes - API User’s Guide\n\
.blurb\n\
The Lotus Notes API User's Guide exported from Notes to
Newton Book format.\n\
.layout Indented 1 Sidebar 11\n\
.layout TitlePage 12 NoTitle\n\
.layout ContentsPage 2 Sidebar 10 Main NoTitle\n\
.layout Default 12\n\
"); 

    // Initialize the Notes runtime library
 if (NotesInitExtended(argc, argv))
 NOTES_INIT_ERROR;
 
    // Open the database
 if (error = NSFDbOpen("API40UG.NSF", &db_handle))
 API_RETURN(ERR(error));
 
 field_text = (void *)malloc(32000);

    // Generate the Newton Book contents
 uniqueLabelCounter = 0;
 error = ReadDatabase(db_handle);
 if (error)
 {
 NSFDbClose(db_handle));
 API_RETURN(ERR(error));
 }

    // Close the database
 if (error = NSFDbClose(db_handle))
 API_RETURN(ERR(error));
 
 fclose(outfile);
 free(field_text);
 }

 API_RETURN(NOERROR);
}


ReadDatabase

ReadDatabase() takes a database handle, and reads each document in the database. In this case, the database 
has a view that is defined in the database. One could also create a custom view at runtime. The pairing of 
a view and a collection is analogous to a search result that has been sorted. Once the collection has been 
opened, ReadEntries() is called to return a buffer containing a reference to each document in the collection, 
plus a counter that indicates how many documents are in the collection. Each document is identified by its 
unique note id. A loop is used to iterate through the buffer and pull out each note id, which is passed to the 
function ReadNote().

STATUS  ReadDatabase(DBHANDLE db_handle)
{
 STATUS error=NOERROR;  // return status from API calls
 NOTEID ViewID;  // note id of the view
 HCOLLECTIONh  Collection;// collection handle
 COLLECTIONPOSITION CollPosition;  // index into collection
 HANDLE hBuffer; // handle to buffer of info
 DWORD  EntriesFound;// number of entries found
 WORD   SignalFlag;// signal and share warning flags
 BYTE   *pBuffer;// pointer into info buffer
 DWORD  I;// a counter
 NOTEID EntryID; // a collection entry id

    // Get the note id of the view we want
 if (error = 
 NIFFindView(db_handle,"TABLE OF CONTENTS",&ViewID))
 return(error);

    // Get the current collection using this view
 if (error = NIFOpenCollection(
  db_handle,// handle of db with view
  db_handle,// handle of db with data
  ViewID, // note id of the view
  0,    // collection open flags
  NULLHANDLE,    // handle to unread ID list (input & return)
  &hCollection,  // collection handle (return)
  NULLHANDLE,    // handle to open view note (return)
  NULL, // universal note id of view (return)
  NULLHANDLE,    // handle to collapsed list (return)
  NULLHANDLE))   // handle to selected list (return)
 return(error);

    // Set a COLLECTIONPOSITION to the beginning of the collection
 CollPosition.Level = 0;
 CollPosition.Tumbler[0] = 0;

    // Get the note ID and summary of every entry in the collection. In the 
    // returned buffer, first comes all of the info about the first entry, then 
    // all of the info about the 2nd entry, etc. For each entry, the info is
    // arranged in the order of the bits in the READ_MASKs.
 do
 {
 if (error = NIFReadEntries(
 hCollection,    // handle to this collection
 &CollPosition,  // where to start in collection
 NAVIGATE_NEXT,  // order to use when skipping
 1L,    // number to skip
 NAVIGATE_NEXT,  // order to use when reading
 0xFFFFFFFF,// max number to read
 READ_MASK_NOTEID, // info we want
 &hBuffer,// handle to info buffer (return)
 NULL,  // length of info buffer (return)
 NULL,  // entries skipped (return)
 &EntriesFound,  // entries read (return)
 &SignalFlag))   // share warning & more signal flag return
 {
 NIFCloseCollection(hCollection);
 return(error);
 }

    // Check to make sure there was a buffer of information returned
 if (hBuffer == NULLHANDLE)
 {
 NIFCloseCollection(hCollection);
 NSFDbClose(db_handle);
 return(NOERROR);
 }

    //
    // Lock down (freeze the location) of the information buffer. Cast
    // the resulting pointer to the type we need.
    //
    // OSLockObject() is sort of like the Notes equivalent of locking a
    // Mac handle and then dereferencing it. However, Notes abstracts 
    // memory management, since each Notes platform may implement it 
    // differently. For example, a Windows handle is a very different kind
    // of data object than a Mac handle.
    //
 pBuffer = (BYTE *) OSLockObject (hBuffer);

    // Start a loop that extracts the info about each collection entry from
    // the information buffer
 for (i = 1; i <= EntriesFound; i++)
 {
    // Get the NoteID of this entry
 EntryID = *(NOTEID*)pBuffer;

    // Advance the pointer over the NoteID
 pBuffer += sizeof(NOTEID);
 
 if (! (NOTEID_CATEGORY & EntryID))
   ReadNote(EntryID, db_handle);
 }
 
    // Unlock the list of NoteIDs. 
 OSUnlockObject(hBuffer);

    // Free the memory allocated by NIFReadEntries
 OSMemFree(hBuffer);
 } while (SignalFlag & SIGNAL_MORE_TO_DO);

    // Close the collection
 error = NIFCloseCollection(hCollection);
 
 return(error);
}


ReadNote

ReadNote() takes a note id and a database handle, opens the document referred to by the note id, reads 
only the fields in that document that are needed, formats them, and outputs them to a text file in a form that 
can be imported by the Apple program Book Maker.

STATUS far PASCAL ReadNote(NOTEID noteID, DBHANDLE db_handle)
{
 NOTEHANDLE note_hdl;
 WORD   field_len;
 long   sectionNum_num;
 long   chapterNum_num;
 char   sectionName_text[100];
 char   titleName_text[100];
 STATUS error;
 static longprevSectionNumber = -1;// this is a static
   
    // Open the document whose note id was passed to this function
 if (error = NSFNoteOpen(db_handle,noteID, 0, &note_hdl))
 return(ERR(error));
 
 sectionNum_num = NSFItemGetLong(note_hdl, "SectionNumber", 0L);

 chapterNum_num = NSFItemGetLong(note_hdl, "Chapter", 0L);

 field_len = NSFItemGetText(note_hdl, "SectionName",
 sectionName_text, 
 sizeof (sectionName_text));

 field_len = 
 NSFItemGetText(note_hdl, "title", titleName_text,
 sizeof(titleName_text));

    // If this document is the first in a new chapter, create a new heading in the 
    // Newton Book Overview (or table of contents)
 if (sectionNum_num > prevSectionNumber)
 {
 prevSectionNumber = sectionNum_num;
 fprintf(outfile, 
 ".subject 1 startspage centered name=%ld\n",
 (long)uniqueLabelCounter++);
 fprintf(outfile,
 "(%ld) %s\n",sectionNum_num,sectionName_text);
 }
 
    // Every document gets an entry in the Newton Book Overview. 
 fprintf(outfile,
 ".subject 2 name=%ld\n", uniqueLabelCounter++);
 fprintf(outfile,
 "(%ld) %s\n", chapterNum_num, titleName_text);
 
    // Body of the document (Notes Rich Text field)
 if (NSFItemConvertToText(note_hdl, "text", field_text,
 FILE_SIZE, ‘\0’) > 0)
 {
    // If the data from Notes contains a \r\n, then remove the \r. 
    // The code for this function is not included in this listing.
 ProcessLineFeeds(field_text);

    // If the data from Notes had a line that began with a period, that would 
    // confuse Book Maker, so we replace the period with a space. 
    // All Book Maker commands begin with a period at the start of a line.
    // The code for this function is not included in this listing.
 CorrectLinesStartingWithPeriod(field_text);

 fprintf(outfile, "%s\n", field_text);
 }
 
    // Close the note
 if (error = NSFNoteClose(note_hdl))
 return(ERR(error));

 return (NOERROR);
}

Summary

Lotus Notes Release 4 presents the Macintosh community with a very exciting opportunity. First, Release 4 is a complete overhaul of the user interface and functionality of Release 3, so should be well received by Mac users. Second, Release 4 exists in both 68K and PowerPC-native versions. Lastly, current support for LotusScript and the C API, and future support for VIM and the C++ API, give Macintosh developers the tools to bring custom Notes-based solutions to the Macintosh platform, as well as to take advantage of Apple technologies by incorporating them into custom Notes applications.

 
AAPL
$99.76
Apple Inc.
+2.09
MSFT
$44.08
Microsoft Corpora
+0.45
GOOG
$520.84
Google Inc.
+9.67

MacTech Search:
Community Search:

Software Updates via MacUpdate

TechTool Pro 7.0.5 - Hard drive and syst...
TechTool Pro is now 7, and this is the most advanced version of the acclaimed Macintosh troubleshooting utility created in its 20-year history. Micromat has redeveloped TechTool Pro 7 to be fully 64... Read more
PDFKey Pro 4.0.2 - Edit and print passwo...
PDFKey Pro can unlock PDF documents protected for printing and copying when you've forgotten your password. It can now also protect your PDF files with a password to prevent unauthorized access and/... Read more
Yasu 2.9.1 - System maintenance app; per...
Yasu was originally created with System Administrators who service large groups of workstations in mind, Yasu (Yet Another System Utility) was made to do a specific group of maintenance tasks... Read more
Hazel 3.3 - Create rules for organizing...
Hazel is your personal housekeeper, organizing and cleaning folders based on rules you define. Hazel can also manage your trash and uninstall your applications. Organize your files using a... Read more
Autopano Giga 3.7 - Stitch multiple imag...
Autopano Giga allows you to stitch 2, 20, or 2,000 images. Version 3.0 integrates impressive new features that will definitely make you adopt Autopano Pro or Autopano Giga: Choose between 9... Read more
MenuMeters 1.8 - CPU, memory, disk, and...
MenuMeters is a set of CPU, memory, disk, and network monitoring tools for Mac OS X. Although there are numerous other programs which do the same thing, none had quite the feature set I was looking... Read more
Coda 2.5 - One-window Web development su...
Coda is a powerful Web editor that puts everything in one place. An editor. Terminal. CSS. Files. With Coda 2, we went beyond expectations. With loads of new, much-requested features, a few... Read more
Arq 4.6.1 - Online backup to Google Driv...
Arq is super-easy online backup for the Mac. Back up to your own Google Drive storage (15GB free storage), your own Amazon Glacier ($.01/GB per month storage) or S3, or any SFTP server. Arq backs up... Read more
Airfoil 4.8.10 - Send audio from any app...
Airfoil allows you to send any audio to AirPort Express units, Apple TVs, and even other Macs and PCs, all in sync! It's your audio - everywhere. With Airfoil you can take audio from any... Read more
Apple iMovie 10.0.6 - Edit personal vide...
With an all-new design, Apple iMovie lets you enjoy your videos like never before. Browse your clips more easily, instantly share your favorite moments, and create beautiful HD movies and Hollywood-... Read more

Latest Forum Discussions

See All

This Week at 148Apps: October 13-17, 201...
Expert App Reviewers   So little time and so very many apps. What’s a poor iPhone/iPad lover to do? Fortunately, 148Apps is here to give you the rundown on the latest and greatest releases. And we even have a tremendous back catalog of reviews; just... | Read more »
Angry Birds Transformers Review
Angry Birds Transformers Review By Jennifer Allen on October 20th, 2014 Our Rating: :: TRANSFORMED BIRDSUniversal App - Designed for iPhone and iPad Transformed in a way you wouldn’t expect, Angry Birds Transformers is a quite... | Read more »
GAMEVIL Announces the Upcoming Launch of...
GAMEVIL Announces the Upcoming Launch of Mark of the Dragon Posted by Jessica Fisher on October 20th, 2014 [ permalink ] Mark of the Dragon, by GAMEVIL, put | Read more »
Interview With the Angry Birds Transform...
Angry Birds Transformers recently transformed and rolled out worldwide. This run-and-gun title is a hit with young Transformers fans, but the ample references to classic Transformers fandom has also earned it a place in the hearts of long-time... | Read more »
Find Free Food on Campus with Ypay
Find Free Food on Campus with Ypay Posted by Jessica Fisher on October 20th, 2014 [ permalink ] iPhone App - Designed for the iPhone, compatible with the iPad | Read more »
Strung Along Review
Strung Along Review By Jordan Minor on October 20th, 2014 Our Rating: :: GOT NO STRINGSUniversal App - Designed for iPhone and iPad A cool gimmick and a great art style keep Strung Along from completely falling apart.   | Read more »
P2P file transferring app Send Anywhere...
File sharing services like Dropbox have security issues. Email attachments can be problematic when it comes to sharing large files. USB dongles don’t fit into your phone. Send Anywhere, a peer-to-peer file transferring application, solves all of... | Read more »
Zero Age Review
Zero Age Review By Jordan Minor on October 20th, 2014 Our Rating: :: MORE THAN ZEROiPad Only App - Designed for the iPad With its mind-bending puzzles and spellbinding visuals, Zero Age has it all.   | Read more »
Hay Ewe Review
Hay Ewe Review By Campbell Bird on October 20th, 2014 Our Rating: :: SAVE YOUR SHEEPLEUniversal App - Designed for iPhone and iPad Pave the way for your flock in this line drawing puzzle game from the creators of Worms.   | Read more »
My Very Hungry Caterpillar (Education)
My Very Hungry Caterpillar 1.0.0 Device: iOS Universal Category: Education Price: $3.99, Version: 1.0.0 (iTunes) Description: Care for your very own Very Hungry Caterpillar! My Very Hungry Caterpillar will captivate you as he crawls... | Read more »

Price Scanner via MacPrices.net

2013 15-inch 2.0GHz Retina MacBook Pro availa...
B&H Photo has leftover previous-generation 15″ 2.0GHz Retina MacBook Pros now available for $1599 including free shipping plus NY sales tax only. Their price is $400 off original MSRP. B&H... Read more
Updated iPad Prices
We’ve updated our iPad Air Price Tracker and our iPad mini Price Tracker with the latest information on prices and availability from Apple and other resellers, including the new iPad Air 2 and the... Read more
Apple Pay Available to Millions of Visa Cardh...
Visa Inc. brings secure, convenient payments to iPad Air 2 and iPad mini 3as well as iPhone 6 and 6 Plus. Starting October 20th, eligible Visa cardholders in the U.S. will be able to use Apple Pay,... Read more
Textkraft Pocket – the missing TextEdit for i...
infovole GmbH has announced the release and immediate availability of Textkraft Pocket 1.0, a professional text editor and note taking app for Apple’s iPhone. In March 2014 rumors were all about... Read more
C Spire to offer iPad Air 2 and iPad mini 3,...
C Spire on Friday announced that it will offer iPad Air 2 and iPad mini 3, both with Wi-Fi + Cellular, on its 4G+ LTE network in the coming weeks. C Spire will offer the new iPads with a range of... Read more
Belkin Announces Full Line of Keyboards and C...
Belkin International has unveiled a new lineup of keyboard cases and accessories for Apple’s newest iPads, featuring three QODE keyboards and a collection of thin, lightweight folios for both the... Read more
Verizon offers new iPad Air 2 preorders for $...
Verizon Wireless is accepting preorders for the new iPad Air 2, cellular models, for $100 off MSRP with a 2-year service agreement: - 16GB iPad Air 2 WiFi + Cellular: $529.99 - 64GB iPad Air 2 WiFi... Read more
Price drops on refurbished Mac minis, now ava...
The Apple Store has dropped prices on Apple Certified Refurbished previous-generation Mac minis, with models now available starting at $419. Apple’s one-year warranty is included with each mini, and... Read more
Apple refurbished 2014 MacBook Airs available...
The Apple Store has Apple Certified Refurbished 2014 MacBook Airs available for up to $180 off the cost of new models. An Apple one-year warranty is included with each MacBook, and shipping is free.... Read more
Refurbished 2013 MacBook Pros available for u...
The Apple Store has Apple Certified Refurbished 13″ and 15″ MacBook Pros available starting at $929. Apple’s one-year warranty is standard, and shipping is free: - 13″ 2.5GHz MacBook Pros (4GB RAM/... Read more

Jobs Board

*Apple* Retail - Multiple Positions (US) - A...
Job Description: Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
Position Opening at *Apple* - Apple (United...
…customers purchase our products, you're the one who helps them get more out of their new Apple technology. Your day in the Apple Store is filled with a range of Read more
Position Opening at *Apple* - Apple (United...
**Job Summary** At the Apple Store, you connect business professionals and entrepreneurs with the tools they need in order to put Apple solutions to work in their Read more
Position Opening at *Apple* - Apple (United...
**Job Summary** The Apple Store is a retail environment like no other - uniquely focused on delivering amazing customer experiences. As an Expert, you introduce people Read more
Position Opening at *Apple* - Apple (United...
**Job Summary** As businesses discover the power of Apple computers and mobile devices, it's your job - as a Solutions Engineer - to show them how to introduce these Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.