Environment set-up for using the Lotus Notes C API toolkit on Linux

Moitrayee Gupta

Copyright 2007 by IBM All rights reserved.

TABLE OF CONTENTS

Intended Audience Introduction Steps Troubleshooting References

3 3 3 6 7

INTENDED AUDIENCE
This document intends to serve as a reference for all practitioners interested in compiling and running C programs for Lotus Notes, using the Lotus Notes C Toolkit API, on a Linux-based platform.

This document lists out the steps to be followed for setting up the required environment for compiling and running Lotus Notes C programs on a Linux desktop. The Linux distribution used here is Debian Ubuntu, and the Lotus Notes version is 7.0. Along with listing out the steps to be followed, the document also contains a section on common error messages and how to resolve them. For IBM internal use, Lotus Notes for Linux is provided by the LTC 'OpenClient' or c4eb (Client for e-Business) project (http://ltc.linux.ibm.com/wiki/LinuxDesktop), which aims at packaging and providing IBM-specific tools like Lotus Notes, Sametime, ILC etc. on Linux based platforms. For Debian operating systems, there is the parallel dc4eb (Debian Client for e-Business) project (http://ltc.linux.ibm.com/wiki/LinuxDocs/Distro/Debian), which offers two types of Notes packages - a native Notes client (Eclipse based) and a Windows Notes client (running on Wine). This document uses the Windows Notes client running on Wine. Writing programs for Lotus Notes is made easy with the Lotus Notes C API toolkit provided by IBM. This toolkit provides all the required header files, as well as sample programs and explanatory documentation. The toolkit is available as a free download on www.ibm.com.

INTRODUCTION

STEPS
This section lists out the steps that should be done to get started with developing Lotus Notes programs using the C API toolkit on a Linux platform : Step 1 - Install and configure the Lotus-Notes 7 package provided by the LTC-dc4eb project : 1. Add the following repository entry to the '/etc/apt/sources.list' file on the host : deb http://olymp.hursley.ibm.com/dc4eb/ stable ibm main contrib nonfree 2. Run the following commands to install the Lotus-Notes packages on the host : $ sudo apt-get update $ sudo apt-get install wine $ sudo apt-get install lotus-notes 3. Once the installation is complete, start the Notes client from the 'Applications>Office' menu. Enter the location of the ID file, and configure the location and user preferences.| Step 2 - Download the Lotus C Toolkit, available on www.ibm.com : 1. Download the toolkit package from http://www14.software.ibm.com/webapp/download/nochargesearch.jsp? k=ALL&S_TACT=104CBW71&status=Active&q=Lotus+%22C+API%22 The current version is 8.0. You will need a valid ibm.com username and password

to download the C toolkit (This is not the same as the w3 Intranet username and password). 2. Unzip the toolkit on the host, to get the 'notesapi' directory. The toolkit includes the API header files (in the 'notesapi/include' directory), the API documentation (in the 'notesapi/doc' directory) and some sample programs (in the 'notesapi/samples' directory). Step 3 - To use the Lotus C API, the 'libnotes' library has to be installed on the system. Download and install it from olymp.hursley.ibm.com : 1. Add the following repository entry to the '/etc/apt/sources.list' file on the host : deb http://olymp.hursley.ibm.com/dc4eb/ stable ibm main contrib nonfree 2. Run the following commands to install 'libnotes' on the host : $ sudo apt-get update $ sudo apt-get install libnotes0 This should result in a file 'libnotes.so' being created in the /usr/lib directory. Step 4 - Set the environment variables required by the Lotus Notes runtime : 1. NOTES_DATA_DIR This variable has to point to the location of the Notes initialization file, 'notes.ini'. For the 'notes-wine' install of Lotus Notes, this file is located in <home-dir>/.notes-wine/drive_c/notes. Set the NOTES_DATA_DIR variable to this location, as follows : # export NOTES_DATA_DIR=/home/moi/.notes-wine/drive_c/notes 2. Notes_ExecDirectory This variable has to point to the location of the Lotus Notes executable program libraries. For the 'notes-wine' install of Lotus Notes, this file is located in <home-dir>/.notes-wine/drive_c/notes. Set the Notes_ExecDirectory variable to this location, as follows : # export Notes_ExecDirectory=/home/moi/.notes-wine/drive_c/notes The above statements can be put into an initialization script, which can be executed at the beginning, to set the variables. Alternatively, they can be added to the '.bash_profile' file of the user. At this point, the environment setup is complete! Step 5 Execute a test program to verify the setup : To check if everything has been set up correctly, write and execute a small test program, which will initialize the Notes runtime and open the user's mail file. This program needs the user's mail server name and mail file name, as arguments. #include<stdio.h> #include<malloc.h> #include<string.h> #include "global.h" #include "nsfdb.h" #include "nsfdata.h" int main(int { char char char argc, char *argv[]) *servername = NULL; *mailfile = NULL; *path = NULL; //user's mail server name //user's mail file location

DBHANDLE db_handle = NULLHANDLE; STATUS error = NOERROR; if(argc < 2) { printf("Usage : ./test <mail_server_name> <mail_file_name> \n"); } /* Initialize the Notes runtime */ if (error = NotesInitExtended (argc, argv)) { printf("Unable to initialize Notes\n"); return (1); } /* Get the user's mail server name */ servername = (char*)(malloc(strlen(argv[1]) * sizeof(char))); strcpy(servername, argv[1]); /* Get the user's mail file location */ mailfile = (char*)(malloc(strlen(argv[2]) * sizeof(char))); strcpy(mailfile, argv[2]); path = (char*)(malloc((strlen(servername) + strlen(mailfile) + 3) * sizeof(char))); /* Construct the full path to the mail file */ if (error = OSPathNetConstruct( NULL, servername, mailfile, path)) { printf("Error constructing path\n"); NotesTerm(); return (1); } /* Open the user's mail file */ if (error = NSFDbOpen (path, &db_handle)) { printf("Unable to open database\n"); NotesTerm(); return (1); } else { printf("Database opened successfully\n"); if (error = NSFDbClose(db_handle)) { printf("Unable to close database\n"); NotesTerm(); return (1); } } return 1;

free(servername); free(mailfile); free(path); NotesTerm(); printf("\nProgram completed successfully.\n"); return (0); } For the code to compile successfully, it has to be linked with the 'libnotes' library. Also, the location of the Notes C API header files has to be specified, along with some specific compiler switches DUNIX, DLINUX and DHANDLE_IS_32BITS : $ gcc -DUNIX -DLINUX -DHANDLE_IS_32BITS -I <location-of-Ctoolkit>/notesapi/include -lnotes -o test test.c Once the code compiles successfully, run the executable with the Notes mail server name and the mail file name as arguments : $ ./test d23ml170 mail8/moitgupt.nsf This will initialize the Notes runtime, and open the specified mail file, using the ID file specified as the value of the 'KeyFilename' parameter in the 'notes.ini' file. The password for the ID file will have to be entered by the user. If the database is opened successfully, the program prints out a success message, closes the database, terminates the Notes runtime, and exits.

TROUBLESHOOTING
The following are the most common errors encountered while compiling and executing programs using the Lotus Notes C API toolkit : 'libnotes.so' is not present or not installed properly Error message : When compiling the test program, the following error message is displayed : /usr/bin/ld: cannot find -lnotes collect2: ld returned 1 exit status Solution : 1. Check that the 'libnotes0' package has been installed : moi@moitgupt:~$ dpkg -l | grep libnotes ii libnotes0 6.0.2-unstable4 Native Linux library for accessing Lotus Domino database 2. Verify that the 'libnotes.so' library is present in /usr/lib : moi@moitgupt:~$ ls /usr/lib/ | grep libnotes.so libnotes.so libnotes.so.6 libnotes.so.6.0.2 global.h: No such file or directory Error message: When compiling the test program, the following error messages are printed out : test.c:4:20: error: global.h: No such file or directory test.c:5:19: error: nsfdb.h: No such file or directory test.c:6:21: error: nsfdata.h: No such file or directory test.c: In function main:

test.c:13: error: DBHANDLE undeclared (first use in this function) Solution : 1. Check that the correct location is specified for the '-I' option, in the gcc command line . The location specified should contain the header files provided along with the Lotus Notes C API toolkit. After unpacking the toolkit, the default location is <root-dir>/notesapi/include. 2. Verify that the location specified contains the required header files : moi@moitgupt:~ $ ls notesapi/include/ | grep global.h global.h moi@moitgupt:~ $ ls notesapi/include/ | grep nsfdb.h nsfdb.h Unable to initialize Notes Error message: After compiling the test program successfully, the above error message is displayed when the program is executed. This means that the Notes Runtime could not be initialized correctly. Solution : 1. Verify that the Notes environment variables have been set : moi@moitgupt:~ $ echo $NOTES_DATA_DIR /home/moi/.notes-wine/drive_c/notes/ moi@moitgupt:~ $ echo $Notes_ExecDirectory /home/moi/.notes-wine/drive_c/notes/ 2. Check the values that these environment variables have been set to : NOTES_DATA_DIR should be set to the location of the 'notes.ini' file Notes_ExecDirectory should be set to the location of the directory containing the executable Windows libraries (.dll files) Unable to open database Error message : After compiling the test program successfully, the above error message is displayed when the program is executed. This means that the database that was specified could not be opened. The good news is that the Notes runtime has been successfully initialized! Solution : 1. Verify that the database specified exists on the server specified. Open up Lotus Notes, go to 'File -> Open Database', enter the name of the server, and check if the database is listed in the directory listing of the server. 2. Verify that you have adequate permissions to open the database specified. Open up Notes, go to 'File -> Open Database', enter the name of the server, select the database from the list, and try to open it. If you can't open it from here, you won't be able to open it through the toolkit API either. 3. Check the entry for 'KeyFilename' variable in the 'notes.ini' file. This variable has to be set to the location of the ID file on the system. Edit it so that it points to the ID file and re-run the program. If the location is correct, the test program should print out the complete path of the ID file, and then wait for you to enter the password. Once you enter the password, and press 'Enter', you should get the message 'Database successfully opened'.

REFERENCES

The LTC LinuxDesktop homepage - http://ltc.linux.ibm.com/wiki/LinuxDesktop Lotus C API toolkit User Guide http://www-12.lotus.com/ldd/doc/tools/c/7.0/api70ug.nsf Lotus C API toolkit Reference http://www-12.lotus.com/ldd/doc/tools/c/7.0/api70ref.nsf