Lotus Domino is a very powerful groupware application server with several ways of implementing your software solution. There are so many choices for programming in Domino/Notes that it can be hard to choose which application strategy to follow. Notes wants to be your graphical interface to everything and is equipped to make that as easy as possible. For instance, Lotus has made it very easy to use DB2 UDB for AS/400 as a data store for Notes. Domino Enterprise Connection Services (DECS), which is part of the base Domino package, uses ODBC to store and retrieve individual records from external databases corresponding to forms in a Notes document. However, DECS does not push data into Notes from the back-end database.

Fortunately, Domino provides a number of solutions for this DECS limitation. One of them is the Notes API, which allows you to write programs that extract data from an external database and store this data in a Domino database.

This article is an introductory user’s guide to Notes C API programming using RPG IV. It covers the technical details of using the C API. Even though the API is written in C, you don’t have to understand the C language to use it, nor do you need to have a C compiler.

History and Background

Earlier in Notes’ life, there were several APIs to choose from. The lowest level, and the most functionally rich, was the Notes C API. At a higher level, being easier to use but with a bit less functionality, was the Notes HiTest API. Higher still was the Notes C++ API.

Then the happy decision to port Domino to the AS/400 was made. Shortly after that, some very helpful developers at Rochester wanted to give AS/400 programmers a head start with Lotus Notes API programming. So they decided to create a free, unsupported, downloadable library called RNHLIB containing function prototypes, help functions, and HTML documentation on how to use the Notes HiTest APIs.

However, as of Release 5 of Domino, the HiTest APIs are no longer officially supported by Lotus. You can still use the HiTest APIs, but they will not be enhanced any further. So, while the RNHLIB library functions do work, they are built over a function set that will not continue to grow and will possibly cease to work at some point in the future.

According to Lotus, the C API is, and will continue to be, the standard API for Lotus Notes programming. Thus, it would make sense to build any API-level access using the Notes C API, rather than the HiTest API.

However, the kind folks at Rochester have not built prototypes for the Notes C API, so programmers must. I chose to build the C API prototypes and help functions within the framework of the existing RNHLIB copybooks.

Before You Dig In

You can use the Notes C API to perform almost any function available within Notes. The subset of APIs I have prototyped will allow you to open and close a database; open, create, modify, and delete a Notes document; and create, retrieve, modify, and delete items (fields) within a Notes document. There are many more functions to prototype, and it is my sincere hope that the readers of Midrange Computing will continue to build upon this API set and share their prototypes with the rest of the AS/400 programming world.

To support Lotus Notes C API programming I had to declare a lot of prototype fields and constants. These are in member NTCNOTES. I also made use of several help functions written by the RNHLIB team (as well as writing some new ones myself), including setenv(), which sets environment variables necessary to the API, and SwitchTo/ FromQNOTES(), which switches your job to the QNOTES user profile and back. I also used addlibs() and rmvlibs() to manipulate the library list. These help functions are in member NTCTOOLS. Before I go any further, I should point out that my work built on that already done by the kind folks at Rochester and would have taken much longer otherwise. Kudos to IBM for making this API prototype set available.

As a general rule, the C API functions return a status variable of type NSFSTATUS, which I have prototyped for you. A return value of 0 (zero) means that the call was successful. Any return value other than 0 indicates a specific error. Lotus supplies a C function (OSLoadString()) that returns the text version of this error, but I have not yet encapsulated this function, as it requires a C macro to be run as a preparatory step. (Perhaps one of you would be willing to submit this prototype to the magazine?)

Data Types and Other Items

Notes has several data types. Some map well to relational databases. Text is like an alphanumeric field, except that it is not fixed in length by definition. A number is always stored in Notes as a double-precision floating-point value. (By the way, this means that Notes numbers are limited to 17 significant digits, as this is the upper limit of precision for double-precision floating-point values.) DateTime is an AS/400 time stamp. There are other list types that do not map well to relational database fields, but I haven’t covered them in this article. For instance, Notes has a text list data type that is similar to an element list in a command definition. This does not map well to a single field in a relational table since it represents multiple values.

Get Initialized!

Writing Notes C API programs is similar to writing HiTest API programs. In the setup and initialization process, for example, you have to make sure the library list is configured correctly; then you have to set up the path variables and switch to the QNOTES user profile. The HiTest help functions handle these tasks for you.

The next required step for using C API in an RPG IV program is initialization. Figure 1 contains an RPG snippet for this step.

To accomplish this initialization you have to perform a “fakeout” of the C API. Argc and argv represent the entry parameters to a standard C program’s main() function. A standard C program receives two arguments, or parameters. The first, argc (argument count), is a count of the parameters. The second, argv (argument vector), is a pointer to an array of pointers to the actual parameters. To accomplish this “double indirection,” I use the

%addr function to get the address of the variable “arg” and store that in arg@. I then use the %addr function again to get the address of arg@, store it in argv, and pass that to the function. You will see this “pointer to a pointer” technique used a lot in the Notes C API.

The Notes C API expects most strings to be converted to the Lotus Multi-byte Character Set (LMBCS). Taking my inspiration from the CvtTo/FromDomStr() functions provided in the HiTest API set, I wrote functions CvtToNSFString() and CvtFromNSFString(), which use the C API function OSTranslate(). These functions enable RPG IV to converse with the C API and are in member NTCTOOLS.

Parts Is Parts

Having successfully initialized the Notes C API, you can now open a database. To do this, pass the file path to the function, as illustrated by the RPG code in Figure 1. The NSFOpenDb() function receives the path to the database in a null-terminated string, and returns a handle to the database. This is really just a number, but it means something to Notes.

As shown in Figure 2, to create a new Notes document, you specify that the database should create one by using a valid database handle. The Notes API creates a Notes document in that database, returning a handle to the database.

Also as illustrated in Figure 2, to specify the default form for the Notes document, you add a text item to the note called Form using NSFItemSetText(). You pass the NOTEHANDLE to the Notes document so that the API knows where to insert the new item. You would use this API to add or update any text (character) item to a Notes document. Figure 2 also demonstrates the very similar code to add a Number item using NSFItemSetNumber(). Again, the same API is used to add a new item or update an existing item.

As shown in Figure 3 (page 71), creating TIMEDATE items requires a bit more work. Sometimes when the API reference says it wants an ASCII string as input, it really means it! So you have to convert the Date/Time string to ASCII first. For this task, I use the API QDCXLATE. Then I call the function ConvertTextToTIMEDATE() to get a Notes TIMEDATE value. Finally, I call NSFItemSetTime() to create the data item. Again, a lot of this functionality should be encapsulated into a higher-level function. Note once again (in Figure 3) the “double indirection” pointer to a pointer to a variable.

A Notes document’s Universal Identifier (UNID) is like the relative record number of a database record, except that it will never change, even if you send the note to another database. You can view the UNID of a Notes document by right-clicking in a document, selecting Document Properties, and then selecting the rightmost tabbed pane (the one with the propeller hat on it). The UNID is in the first two lines shown there. However, it is represented differently there than it is in the API. What you see in that pane is the hexadecimal representation of the UNID. However, that representation is in a different order than what you find in the UNID used by the API. Why Lotus represents the UNID in different ways is a mystery to me! One common function is to open a document by specifying the UNID for that document. However, you can’t directly retrieve the UNID of a note. The UNID is in the first 16 bytes of the Note Originator ID, or OID. So you must retrieve the OID using the NSFNoteGetInfo() API, and extract the UNID from it, as illustrated in Figure 4.

You’ve created a new Notes document and added data items to it. All you have to do now is close the document, right? No! If you close the document at this point, you’ll lose all that you have created. To save the new document to disk, you must call the NSFNoteUpdate() function, and then close it with the NSFNoteClose() function, as shown in Figure 5.

Go Get It

So you know how to create a Notes document and add items to it. Now I’ll show you how to retrieve them. Figure 6 illustrates how to retrieve a text item using NSFItemGetText(). Note that the CvtFromNSFStr() function was used and that the input and return variables are the same. It’s neat that this works.

Figure 6 also illustrates how to retrieve a Number item using NSFItemGetNumber(). There is more work involved in retrieving a TIMEDATE value. Once again, this is a multistep process. You retrieve the TIMEDATE value using NSFItemGetTime(), convert it to text using ConvertTIMEDATEToText(), and then convert the text from ASCII with QDCXLATE (see Figure 7). Further encapsulation would be good here, too.

Make It Go Away

Deleting a Notes document is different from creating a note. You delete a Notes document by its NOTEID, not by the NOTEHANDLE returned from NSFNoteCreate(). As shown in Figure 8, you use NSFNoteGetInfo(), the same function used to get the UNID.

Having done that, just call NSFNoteDelete(), also as shown in Figure 8. All that’s left to do now is close the database and detach from Notes (see Figure 8).

First, you close the database, and then the terminate function, NotesTerm(), is called. Since this function returns no value and takes no parameters, I just used a CALLP to invoke it.

It is good manners to undo any changes made to an environment, so switch back from the QNOTES profile and remove the library list changes before exiting. Again, the RNHLIB help functions are your friends. However, my experience has been that the OS/400 API to switch back to the original user profile doesn’t always work properly. I was often required to sign off my interactive session and sign back on to get my authorities back.

Building Blocks

In addition to the prototype and helper function source members that are available in a downloadable Save file at www.midrangecomputing.com/mc, I've included the RPGLE source for a sample program you can compile and run to test your new-found Notes C API savvy. Creating the program is a two-step process. First, you create the module:

CRTRPGMOD MODULE(LIBNAME/NTCAPITEST)

SRCFILE(LIBNAME/SRCFILE)

SRCMBR(NTCAPITEST)

Then you create the program. I found that the OPTION(*DUPPROC) parameter was necessary because there was a conflict between the Java function GetVersion() and the Notes function GetVersion(). I never could figure out how or why the CRTPGM command was finding the Java function, but this solved the problem. I also created a binding directory named NTCBNDDIR that contained the non-Lotus modules needed to support Notes C API programming, namely NTCTOOLS and NTCLIBL:

CRTPGM PGM(LIBNAME/NTCAPITEST)

MODULE(LIBNAME/NTCAPITEST)

BNDSRVPGM(QNOTES/LIBNOTES)

BNDDIR(NTCBNDDIR)

ACTGRP(*CALLER)

OPTION(*DUPPROC)

It’s Your Turn

The Notes C API is very flexible and very deep. There are many useful functions I have not prototyped. For instance, NSFSearch() can be used to retrieve a list of Notes

documents matching selection criteria. Further encapsulation of some of the functions I have presented would be valuable from a clarity or usability standpoint. Nonetheless, I hope this will speed you on your way to using your Domino server in ever more productive and interesting ways.

D arg s 10A inz('NTCAPITEST')
D arg@ s * inz(%addr(arg))
D argv s * inz(%addr(arg@))
D argc s like(NSFDWORD) inz(1)
D Path s 256A
D Database s like(NSFDBHANDLE)

C eval Status = NotesInitExtended( argc : argv )
C eval Status = NSFDbOpen(
C CvtToNSFStr(Path) :
C Database)

C eval Status = NSFNoteCreate(
C Database :
C NoteHandle)

C eval ItemName = 'TextItem'
C eval Status = NSFItemSetText(
C NoteHandle :
C CvtToNSFStr(ItemName) :
C CvtToNSFStr(ItemValue) :
C %len(%trim(ItemValue)))

C eval ItemName = 'NumberItem'
C eval Status = NSFItemSetNumber(
C NoteHandle :
C CvtToNSFStr(ItemName) :
C Double)

D TotLen S 5p 0 inz(20)
D OutLen S 5p 0
D XltTbl DS
D Table 10 inz('QASCII ')
D TableLib 10 inz('*LIBL ')
D TimeText s 20a inz('10/22/1962 08:30:00')
D TimeText@ s * inz(%addr(TimeText))
D TimeText@@ s * inz(%addr(TimeText@))
D TimeValue s like(NSFTIMEDATE)
D TimeValue@ s * inz(%addr(TimeValue))
D TimeTextLen s like(NSFWORD) inz(20)

* Add an item of type TIMEDATE
C call 'QDCXLATE'
C parm TotLen
C parm TimeText
C parm Table
C parm TableLib

C eval Status = ConvertTextToTIMEDATE(
C *NULL :
C *NULL :
C TimeText@@ :
C TimeTextLen :
C TimeValue@)

C eval ItemName = 'TestTimeItem'
C eval Status = NSFItemSetTime(
C NewNoteHandle :
C CvtToNSFStr(ItemName) :
C TimeValue)

Figure 3: Here the RPG program creates a date item in a Notes document.

Figure 1: This RPG program snippet performs Notes API initialization and opens the database.

Figure 2: Here the RPG program creates a Notes document, assigns a form name as a text item, and then adds a number item.

D NoteHandle s like(NSFNOTEHANDLE)
D UNID s like(NSFUNID)

C eval Status = NSFNoteGetInfo(
C NoteHandle :
C NSF_NOTE_OID :
C %addr(NoteOID))
C eval UNID = %subst(NoteOID:1:16)

C eval Status = NSFNoteOpenByUnid(
C Database :
C UNID :
C 0 :
C NoteHandle)

C eval Status = NSFNoteUpdate(NoteHandle : 1)
C eval Status = NSFNoteClose(NoteHandle)

D RtvString s 80a
D RtvString@ s * inz(%addr(RtvString))
D RtvDouble s 8f
D RtvDouble@ s * inz(%addr(RtvDouble))

C eval ItemName = 'TextItem'
C eval Status = NSFItemGetText(
C NewNoteHandle :
C CvtToNSFStr(ItemName) :
C RtvString@ :
C %len(%trim(RtvString)))
C eval RtvString = CvtFromNSFStr(RtvString)

C eval ItemName = 'NumberItem'
C eval Status = NSFItemGetNumber(
C NewNoteHandle :
C CvtToNSFStr(ItemName) :
C RtvDouble@)

D RtvTimeValue s like(NSFTIMEDATE)
D RtvTimeValue@ s * inz(%addr(RtvTimeValue))
D RtvOkay s 1a
D RtvTimeText s 80a
D RtvTimeText@ s * inz(%addr(RtvTimeText))
D RtvBufferLength...
D s like(NSFWORD) inz(80)
D RtvTextLen s like(NSFWORD)
D RtvTextLen@ s * inz(%addr(RtvTextLen))

* Retrieve the value of the TIMEDATE item "TestTimeItem"
C eval ItemName = 'TestTimeItem'
C eval RtvOkay = NSFItemGetTime(
C NewNoteHandle :
C CvtToNSFStr(ItemName) :
C RtvTimeValue@)
C eval Status = ConvertTIMEDATEToText(
C *NULL :
C *NULL :
C RtvTimeValue:
C RtvTimeText@ :
C RtvBufferLength :
C RtvTextLen@)
C eval TotLen = RtvTextLen
C eval Table = 'QEBCDIC '
C call 'QDCXLATE'

Figure 4: Here the RPG program retrieves a Notes document’s UNID and opens a document by its Universal ID.

Figure 5: To store an updated Notes document to disk, you update it and then close it.

Figure 6: Here the RPG program retrieves a text item and a number item.

Figure 7: Here the RPG program retrieves a Date item.

D NoteID s like(NSFNOTEID)

C eval Status = NSFNoteGetInfo(
C RtvNoteHand :
C NSF_NOTE_ID :
C %addr(NoteID))

C eval Status = NSFNoteDelete(
C Database :
C NoteID :
C 0)

C eval Status = NSFDbClose(Database)
C callp NotesTerm

Figure 8: Delete a Notes document, close the database, and terminate your API session.

Also Read

The API Corner: Moving Jobs Within and Across Job Queues

The API Corner: What Time Zone Do You Want That Date and Time In?

The API Corner: How Do You Want That Date and Time?