Calling DLL routines from LotusScript. Part II: Lotus Notes C API

Download examples in Release 6 NSF format

I originally conceived of writing on this topic 6 years ago when I wrote my Windows API article. Back then, I was using Notes Release 4.6. Amazingly, this topic is still as relevant today as it was back then! This article is not a tutorial on using the C API but only on the nuances of using the C API through LotusScript.

At times, LotusScript falls short in giving you the access you need to your Notes/Domino databases through the classes it provides. On the other hand, you can do theoretically anything to your databases by using the Lotus C API. Although, coding in C (or C++) to get full access to your databases is not for the faint of heart. And, if you are developing for the Notes client, C and C++ programs are not easy to roll out. But, there is a middle ground. You can call some of those same C API routines directly from LotusScript without requiring additional software for deployment. This only works with the C API and not the C++ API since the C++ API requires a DLL that does not install with the base Notes client.

Coding for the C API is analogous to coding for the Windows API. There is one major advantage. Whereas for Windows, you need to hunt around to find the calls implemented inside its DLLs, Lotus has it all documented in one place: the Lotus C API Toolkit for Domino and Notes. Download this toolkit before proceeding because you will need the reference database as your guide to all the calls you can make. It is an excellent source of information.

Example 1: a simple example made simpler
It is probably best to start with an example. Below is a variation of one of the sample programs that comes with the C API toolkit. It returns the major build number of the Notes/Domino executable. It has been further simplified to save space here, but, it still remains functional. Here we are using the local names.nsf as the target database so the major build number will be that of our client. If we wanted to access the names.nsf database on a server, we would instead specify “server!!names.nsf” for db_filename.

Now we’ll look at the same functionality but implemented using LotusScript calls to the C API. The first piece to examine is the Declarations section that makes the external functions available to LotusScript. All of the C API functions are implemented in nnotes.dll. For reference, I like to include the C signature as a comment before the Declare statement. It helps when doing the initial translation as well as later for documentation purposes.

The key is to properly translate the C data types into LotusScript data types. Since you are often dealing with pointers into memory, care should always be taken. You should expect client crashes as you work with C API calls for the first time and work out their declare statements. To do the translation you first need to consider the data type(s) used in the API call definition and determine the correct LotusScript data type. Generally, you are dealing with a well-defined subset of C types that, once mapped the first time, can help you with further mappings. A few of the more common are in the following table:

Once the type translation is determined you then need to determine the type of reference. Like C, LotusScript has two types of references for passed variables: by value (ByVal is specified) and by reference (nothing is specified). In C, variables passed by reference are done via the use of a pointer. When a C API declaration is defined using a pointer, the asterisk (*) symbol will precede the variable name. Variable names without the preceding asterisk are being passed by value.

The following table will help you with some sample translations you will see often. It is not intended to be a complete reference.

With the declarations set, we can get to the code. What follows is an agent’s initialize routine that prints the build message to the status bar using the C API calls. You will notice is that flow is identical since we make the same calls in the same order. You can implement the other samples that come with the C API in a similar way. Instead of names.nsf, the current database is used.

When using the C API, I have found that it pays to follow the example set in the samples by building in a fair amount of error checking, messaging and recovery. The general rule is to check every operation for an error and, if you find one, don’t continue to the next operation. Instead, generate a meaningful error message and cleanup anything you can before exiting.

Example 2: a more practical example – changing the template name of a database
The next example is a practical one, although, I don’t remember exactly why I had to do this at one time. The template name is a property of NotesDatabase, although, it is read-only. If you want to change this programmatically, you can do so by using the C API. This example illustrates a couple of points: the translation of constants that is necessary when moving from C to LotusScript and the allocation of memory when passing data between LotusScript and the C API.

We’ll first start with the use of constants. The template name is stored as one of several elements in the "database information buffer." To get the buffer you use NSFDBInfoGet and to put data back into it you use NSFDBSetInfo. The database information buffer you pass in and get out contains several parts. You use NSFDBInfoParse to get a specific piece out of the database information buffer. You do this by specifying a constant as one of the parameters to NSFDBInfoParse that represents the piece you want. From the C API documentation we can see that these constants are in the form INFOPARSE_xxx and are defined in nsfdb.h. Inside this file we find the following C definitions:

For the constant values you will usually see integers, whose values you can translate directly, and hexadecimal numbers. In C, the hex numbers are specified in a form like 0x0100. In LotusScript, you would specify &h0100 for the same value. We can translate the definitions we need for the example along with the other calls and definitions needed for the aforementioned C API calls into the declarations section of a LotusScript agent:

The next part of this example is how to deal with the information buffer. If you have done much work with the Windows API, you have probably used a similar method to pass information between the two languages. You need allocate memory for the buffer by building a string of the correct size. For this, use the String function. The C API documentation tells us that the size of the buffer is defined by NSF_INFO_SIZE. This value is found in nsfdb.h and has been translated in the declarations above.

Example 3: Using C structures
The last example presented here contains details on using structures contained within the C API. Often structures need to be passed into and retrieved from C API calls. This example will retrieve the user activity information from a database. It is a was chosen because it is a simple example that uses a structure not because it is a practical example. You first start by translating the C struct into a LotusScript Type. For this, you will need to translate the data types from C into LS the same way you do for the function calls. You will find the struct definition in the C API documentation as well as in a header file. Again, as a matter of course, I like to include the C definitions as comments along with the LotusScript code. The structure we are dealing with here is DBACTVITY.

The above code section contains all of the declarations we need to make for this example.

Note: This uses a somewhat less flexible way of declaring ConvertTIMEDATEToText. The parameters IntlFormat and TextFormat are not defined using their actual types but using Integer instead. This allows us to pass a 0 in the call which is the equivalent of passing a NULL in the C world. A NULL for these parameters instructs the ConvertTIMEDATEToText to build for itself the Format structures using default information about the internationalization settings. A more flexible way would be to implement this by defining the INTLFORMAT and TFMT structures as Types and by using OSGetIntlSettings to populate the INTLFORMAT structure and/or custom building it for your specific need. For this case, we would declare it as follows:

Furthermore, to make this declaration flexible enough to handle both the passing of the NULLs ans the structures you can declare IntlFormat and TextFormat as Any. Although, this reduces the effectiveness that the LotusScript compiler provides.

The INTLFORMAT and TFMT structure implementations as Types have been omitted here, but, by following this example you should be able to translate them. When I attempted to use this alternative for this example, I was able to populate the IntlFormat structure but I received an error which I could not get around when using it with ConvertTIMEDATEToText. I am sure it is possible with the right declarations.

The rest of the code for this example is as follows. The call to NSFDbGetUserActivity populates the Type with data and we can get to its components it like we would for any LotusScript Type.

The dates are stored in a TIMEDATE structure. This happens to be the same structure you will use when dealing with replica IDs. To get a readable date, we call ConvertTIMDATEToText passing it the correct component of the DBACTIVITY structure.

Conclusion
My own personal experience is to use this technique to solve problems that are simple in nature but not possible to implement in native LotusScript due to the its (sometimes) restricted view of the world. To be sure, there are some things in the C API that are just not a good idea to be doing through LotusScript. I have given up trying to work with Rich Text using this method.

While the C API can be very unforgiving if you reference memory in the wrong way, with some patience, this can be a really powerful solution to your hardest LotusScript problems. Now, you can do things you never thought possible.

Other resources
There is a book on this topic. I have not read nor seen the book so I cannot provide a review of it. The book is called "LotusScript to Lotus C API Programming Guide".

You can also try the page at NSFTools.com where they have some more informtion on the topic.