Building MAC Applications
Building MAC Applications
This chapter identifies the hardware and software requirements for developing HCL C API programs for Notes under MAC and explains how to set up your MAC environment. It covers the following topics:
- Getting Started
Hardware and software requirements, Compiler installation, Environment settings for compiling the sample, Running HCL C API programs, and Testing the installation
Initialization and file-naming conventions
Platform-specific files supplied with the HCL C API Toolkit for Notes
Information on addressing, calling conventions, and data alignment
Compiling, Linking, Building shared libraries, and Debugging
Platform-specific information on compiler, linker, and debugger settings for C API applications
This section describes the hardware and software requirements for MAC platform supported by the HCL C API for Notes.
Hardware and software requirements
Are identical to those required by Domino with addition of space for the HCL C API Toolkit and compilation
There are no special requirements for installation of the compilers or other tools.
Environment settings for compiling the sample
This section explains how to set up your MAC environment to build and run HCL C API programs for Domino.
- Make sure HCL Notes Client for MAC and the HCL C API for Notes are installed.
- Set the environment variable LOTUS to HCL C API for Notes directory.
- Set the environment variable PATH to include the Notes Client executable directory.
- Set the environment variable DYLD_LIBRARY_PATH to include the Notes Client executable.
- Set the environment variable Notes_ExecDirectory to specify the the Notes Client executable directory.
The sections that follow define the following concepts:
- The canonical Lotus directory
- The Notes executable directory
The canonical Lotus directory
- Set the environment variable LOTUS to point to HCL C API for Notes directory:
- The directory where you uncompress the HCL C API Toolkit, for example: /Users/notes
If you use the C shell, your .cshrc file should contain the line:
- setenv LOTUS /User/notes
For sh or ksh, your initialization file should contain the following:
- LOTUS=/User/notes; export LOTUS
- The make files for HCL C API sample programs use $LOTUS to locate the directory where the HCL C API for Notes include files and object files reside.
The Notes executable directory
- The Notes executable directory is the directory where the Notes executable program libraries reside.
Under MAC,the Notes Client excutable program libraries reside /Applications/Notes.app/Contents/MacOS/ by default
By convention, set the environment variable Notes_ExecDirectory to point to the Notes executable directory. If you use the C shell, your .cshrc file should contain the line:
- setenv Notes_ExecDirectory your-Notes-executable-directory
<br> For sh or ksh, your initialization file should contain the following:<br>
Running HCL C API programs
This section explains how to set up your MAC environment to run HCL C API programs for Notes.
MAC is a Notes Client only platform. It is required that you run C API programs on MAC under the same login as the client.
you do not need to be a super user to change the owner and group settings of a program that you built.
The initialization algorithm
At initialization time, Notes and C API programs search for the Notes Client executable directory. In order to find the Notes Clients executable directory, C API programs that are written as main programs must call NotesInitExtended.
This algorithm determines the Notes Client executable directory:
1. If the Notes_ExecDirectory environment variable is set, the value of Notes_ExecDirectory is taken to be the Notes Clients executable directory.
2. Otherwise, use argv. The value of argv is the name of the program as specified on the command line. If argv specifies a full or relative path name, the directory portion of that pathname is taken to be the Notes Client executable directory; otherwise the PATH environment variable is used to locate the directory containing argv, and that directory is taken to be the Notes Client executable directory.
While developing your C API program, set the Notes_ExecDirectory environment variable to specify the Notes Client executable directory in your environment.
Testing the installation
After installing the Notes Clients, the C compiler, the development files, the documentation, and the sample C API programs, follow these steps to build and test the sample C API program intro. Any problem building or executing an unmodified sample program indicates a problem in the environment.
- Verify that the Notes Clients executes successfully in your environment. C API programs require that the Notes Clients is installed properly in the environment.
- Open an xterm window, or use rlogin or telnet to get a shell and a command prompt.
- Under the default installation of the HCL C API Toolkit for Notes, this sample directory is located under:
- Change to the directory where intro was copied and type ls to list the files in this directory.
The .mak files in this directory are make files for the various operating environments. The C API kit includes multiple build support files for samples that can be built for multiple platforms.
- Build intro using the make file appropriate to your operating environment. For example,type the following command at the command prompt:
make -f macosx.mak
The program should compile and link with no errors.
- Copy the database, intro.nsf, from the notedata directory in the C API kit to the Notes data directory. Under the default installation of the HCL C API Toolkit for Notes, this database is located under:
- Enter this at the command prompt:
It should display the HCL C API for Domino and Notes release number followed by:
The title for the database intro.nsf is...
API Test Database (intro)
- Start Notes,Open the database "intro.nsf".
- Check the database title by selecting File - Database - Properties. The title should be the same as the one printed by the intro sample: "API Test Database (intro)."
C API programs for MAC may use any of the following methods to initialize the Notes Client run-time system.
You can structure C API programs for MAC as a subroutine named NotesMain. In this case, link with the bootstrap object file notes0.o. This object file provides the "main" program required by MAC systems.
NotesMain uses the system's standard calling convention. The argument count provided to the subroutine is an integer.
You can structure the program as a standard C or C++ program with entry point main. In this case, the program must call the function NotesInitExtended to explicitly initialize the Notes Client run time system before calling any other HCL C API for Notes functions. When the program no longer needs to call any HCL C API functions for Notes, it must call the function NotesTerm to terminate the Notes run time system explicitly.
You can structure the program as a shared object library with a main entry point named MainEntryPoint. In this case, the C API program is configured as an add-in to the software. Typically, the Notes client software loads and calls the main entry point of this custom library in response to a Notes user's command or menu selection. In this case, the Notes Client run-time system is initialized before MainEntryPoint receives control. The Notes Client run-time system is terminated when the user exit the Notes Client.
Platform-Specific File Directories
- The platform-specific files supplied with the HCL C API for Notes are in the library directory. The pathname for this directory depends on the platform:
- On MAC platforms, the filenames of shared objects must start with the characters "lib", Append to "lib" the name you want to give the file, the extensions used .dylib , for example,
Platform File extension Typical Filename
MAC .dylib libfoo.dylib
This section describes the components of the HCL C API for Notes that support building applications for MAC platforms.
HCL C API for Notes Header Files
In the HCL C API for Notes, support for all platforms is provided by the common include files in $LOTUS/notesapi/include. When compiling, the Notes header files require the use of the many compiler command-line switches which will be detailed below and are also in the macosx_cmp.txt file included in the include directory of the SDK.
For details, see "Compiling," below.
Be aware that the MAC platform ID macro, "-DMAC" also defines the "-DW32" platform ID macro which stands for the Win32 APIs.
Detail please see the macosx_cmp.txt in the cmp folder.
Header File Conflict
It is possible that a header file that is included with the compiler's software development kit may have the same name, but different contents, as a C API for Notes header file. If your API program requires the HCL C API header file for Notes but does not require the other file that has the same name, you may resolve the conflict including the HCL C API for Notes headers before the others during compilation. Alternatively, you may specify the full path of the header file in the #include statement in your source code. This alternative allows your program to include both files in a single source module.
It is also possible that a header file that is included with the compiler's software development kit may contain a definition that is also defined in a header file in the HCL C API for Notes and the syntax of the definitions cause errors when compiling source code that includes both header files. In such cases it is recommended to keep code that requires each header file in a separate module.
HCL C API Library Files for Notes
Since the HCL C API for Notes is supplied as a shared object library on MAC platforms, no separate library files are supplied with the HCL C API Notes. For details, see "Linking," below.
Data Structure Packing
On MAC systems, most data structures passed between Notes and API applications are aligned on the appropriate data boundaries. However, some structures containing data that is stored directly in a Notes database are stored in Notes canonical format. You must convert this data using ODSReadMemory and ODSWriteMemory.
Platform ID Macro
Mac platform has a platform-specific ID macro: MAC
Compiler Switches and Options
To compile Domino C API applicaitons under Linux use the switches in macosx_cmp.txt
There are no special considerations for stack size for MAC C API applications for Notes.
Building shared libraries
The recommended linker switches depend on the linker you use.
To link C API applications under Linux, use the switches in macosx_cmp.txt.
To build a version of an application for symbolic debugging, add the following flag to the compiler command:
-g Cause the compiler to generate additional information needed by the symbolic debugger.
You may want to avoid use of the -O flag, used to generate optimized code.