summary of API-Userguide:
Deploying C API applications
There are three ways to deploy your C API program to a number of Domino users:
You can have them follow the procedure outlined in the "Environment Settings - Summary" section, above.
If it is inconvenient for all users of your program to set the Notes_ExecDirectory variable, install the executable file into the Domino executable directory. If the users have the Domino executable directory on their PATH, they will be able to run your C API program and the program will get access to the resource files at run time.
If your users do not have the Domino executable directory on their path, but do have the Lotus binary directory ($LOTUS/bin, relative to the Lotus canonical directory). Install the C API program executable file into the Domino executable directory, then link the C API program from the Domino executable directory to the Lotus binary directory. For example,
% cp apiprog $LOTUS/notes/latest/ibmpow/apiprog
% cd $LOTUS/bin
% ln $LOTUS/notes/latest/ibmpow/apiprog apiprog
Environment Settings
This section explains how to set up your UNIX environment to build and run Lotus C API programs for Domino.
Summary
Make sure Lotus Domino and the Lotus C API for Domino and Notes are installed.
Set the environment variable LOTUS to the canonical Lotus directory,/opt/lotus, if necessary. All Lotus software is installed in the canonical Lotus directory.
Set the environment variable PATH to include the Domino executable directory, the Domino data directory and the Domino resource directory.
On S/390, set the environment variable LIBPATH to include the Domino executable directory. LIBPATH determines the location of dynamic link libraries (DLLs) at run-time.
While developing Lotus C API programs for Domino, set the environment variable Notes_ExecDirectory to specify the Domino executable directory.
Make sure C API program executable files have the same owner and group as other Domino binaries and also have the set group-id bit set.
After developing a C API program, the best way to deploy it to a number of Domino users is to install the C API program in the Domino executable directory.
The sections that follow define the following concepts:
the canonical Lotus directory
the Domino data directory
the Domino executable directory
the PATH environment variable
owner, group, and file permissions
accessing resource and character set translation files
The Canonical Lotus Directory
The canonical Lotus directory is the directory in which all Lotus products for UNIX are installed. A canonical Lotus directory is required because on some UNIX systems shared libraries are found in absolute file system locations.
Set the environment variable LOTUS to point to this directory:
/opt/lotus for all UNIX platforms except S/390
/usr/lpp/lotus for S/390
If you use the C shell, your .cshrc file should contain the line:
setenv LOTUS/opt/lotus
For sh or ksh, your initialization file should contain the following:<br/>
LOTUS=/opt/lotus; export LOTUS
All Domino software should be installed in the canonical Lotus directory. Specifically,
The Domino program directories should reside in $LOTUS/notes.
The Lotus C API Toolkit for Domino and Notes should reside in $LOTUS/notesapi.
All UNIX platforms support symbolic directory links. Therefore, Lotus products may physically reside anywhere in the file system, so long as a directory link in the canonical Lotus directory points to where the product actually resides. For example, the directory/opt/lotus/notesapi may be a symbolic link to the directory where the Lotus C API Toolkit for Domino and Notes physically resides.
The make files for Lotus C API sample programs for Domino and Notes use $LOTUS to locate the directory where the Lotus C API for Domino and Notes include files and object files reside.
The Domino data directory
The Domino data directory is the directory containing server's notes.ini file, the Domino databases, and templates.
Under UNIX, the default Domino data directory is named/local/notesdata and it must reside on the local disk.
By convention, set the environment variable NOTES_DATA_DIR to point to the Domino data directory. If you use the C shell, your .cshrc file should contain the line:
setenv NOTES_DATA_DIR your-Domino-data-directory
For sh or ksh, your initialization file should contain the following:<br/>
NOTES_DATA_DIR=your-domino-data-directory; export NOTES_DATA_DIR
The Domino executable directory
The Domino executable directory is the directory where the Domino executable program libraries reside. Relative to $LOTUS, the root of the Lotus tree, the Domino executable directory is:
$LOTUS/notes/latest/arch
Where
latest is a symbolic link to the release name (for example, 6000),
arch is the code name for the architecture of the UNIX platform (for example, sunspa). It consists of up to three letters for the vendor (for example, hp, sun, or ibm) and up to three letters for the CPU or machine type (for example, spa for SPARC). For example, the Domino executable directory for Domino for Solaris SPARC Edition is:
$LOTUS/notes/latest/sunspa
By convention, set the environment variable Notes_ExecDirectory to point to the Domino executable directory. If you use the C shell, your .cshrc file should contain the line:
setenv Notes_ExecDirectory your-Domino-executable-directory
For sh or ksh, your initialization file should contain the following:<br/>
Notes_ExecDirectory=your-Domino-executable-directory;
export Notes_ExecDirectory
The PATH Environment Variable
The PATH environment variable must contain both the Domino data directory, the Domino executable directory and the Domino resource directory.
Make sure PATH specifies the absolute path to the Domino data directory. If the filename substitution (such as ~) is used, a C API program may not be able to find the notes.ini file.
S/390 LIBPATH Environment Variable
The LIBPATH environment variable must include the Domino executable directory. S/390 uses LIBPATH to locate shared libraries (aka shared objects) at runtime, including the Domino shared library libnotes.
Owner, Group, and File Permissions
Running C API programs on UNIX now require that you run them under the same login as the server. Otherwise you will not have permission to write to the databases in the data directory.
After compiling but before running a Lotus C API program for Domino, make sure the executable file for the C API program has the same owner and group as other Domino binaries and also has the set group-id bit set.
By default, all Domino executable files have owner "server" and group "notes." For example, a command to list the owner, group, and permissions of the Domino executable "server" for Domino for Solaris SPARC Edition would print something similar to the following:
% ls -l $LOTUS/notes/latest/sunspa/server
-r-xr-sr-x 1 server notes 14102624 June 25, 06:39/opt/lotus/notes/latest/sunspa/server
In this case, you must set the owner of your C API executable program to "server" and the group to "notes." You must also set the group ID bit. The following commands show how to set the owner, group, and permissions of the C API sample program executable "intro" to the required values:
% cd $LOTUS/notesapi/samples/basic/intro
% su
Password: <enter the super user password>
chown server intro
chgrp notes intro
chmod 2555 intro
exit
%
You do not need to be a super user to change the owner and group settings of a program that you built.
see also "Lotus C API Notes/Domino 6 User Guide"
I receive source code by mail and am willing to send it to you. PLease email me:
Hans-Georg dot Franke at yahoo dot de