Skip to content

Building MAC Applications

Chapter 3-4
Building MAC Applications

Introduction

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

    Program Structure
    Initialization and file-naming conventions

    Toolkit Files
    Platform-specific files supplied with the HCL C API Toolkit for Notes

    Compatibility
    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


Getting Started

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


Compiler installation

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.

Summary

  • 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 MAC 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 /User/notes/notesapi may be a symbolic link to the directory where the HCL C API Toolkit for Notes physically resides.
    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>
      Notes_ExecDirectory=your-Notes-executable-directory;
      export Notes_ExecDirectory


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[0]. The value of argv[0] is the name of the program as specified on the command line. If argv[0] 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[0], 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.

      1. Verify that the Notes Clients executes successfully in your environment. C API programs require that the Notes Clients is installed properly in the environment.
      2. Open an xterm window, or use rlogin or telnet to get a shell and a command prompt.
      3. Under the default installation of the HCL C API Toolkit for Notes, this sample directory is located under:

        $LOTUS/notesapi/samples/basic/intro
      4. 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.
      5. 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.
      6. 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:

        $LOTUS/notesapi/notedata/intro.nsf
      7. Enter this at the command prompt:

        intro intro.nsf

        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)
      8. Start Notes,Open the database "intro.nsf".
      9. 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)."



    Program Structure

    Program Initialization

    C API programs for MAC may use any of the following methods to initialize the Notes Client run-time system.
      NotesMain

      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.


      main

      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.

      MainEntryPoint

      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.

    Naming Conventions

    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:

        MAC: $LOTUS/notesapi/lib/macosx

    Custom Libraries
      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

    Toolkit Files

    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.



    Compatibility

    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.


    Compiling

    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


      Linking

      Stack Size
      There are no special considerations for stack size for MAC C API applications for Notes.


      Building shared libraries

      Linker Switches

      The recommended linker switches depend on the linker you use.

      MAC
      To link C API applications under Linux, use the switches in macosx_cmp.txt.

      Debugging

      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.

      ---