Building Windows Applications

Chapter 3-1

Building Windows Applications

Introduction

The HCL C API Toolkit for Domino and Notes lets you build Windows(32 or 64 bit) applications using the Microsoft Visual C++ tools that run with the release of HCL Domino or HCL Notes for all supported Windows platforms. This chapter describes the details specific to building C API applications in the Windows environment. It covers the following topics:

Getting Started

Program Structure

Toolkit Files

Compatibility

Compiling, Linking, and Debugging

Microsoft Visual Studio 2017/2022

Getting Started

Hardware Required

Same requirements as Notes/Domino with addition of space for HCL C API Toolkit and compilation

Software Required

The following software is required to develop HCL C API programs for the Notes client:

HCL Domino or HCL Notes 14.0.0 for Windows. All Windows platforms supported by Notes 14.0.0 are also supported by this toolkit.
Microsoft Visual Studio 2017/2022.

The following software is required to develop HCL C API programs for Domino:

HCL Domino or HCL Notes 14.0.0 for Windows. All Windows platforms supported by Domino 14.0.0 are also supported by this toolkit.
Microsoft Visual Studio 2017/2022.

Compiler Installation

Windows support a flat, 32-bit memory model for all programs.

Environment Settings

Set the following environment variables before building or running HCL C API programs for Domino and Notes under Windows.

Environment variables may be set in a variety of ways. For example, they may be set in the Environment Variables section of your system settings, in a batch file, in a program, or in a makefile. For more information, refer to the Windows documentation. You may need to restart Windows for the new configuration to take effect.

References to "d:" in the descriptions below refer to the appropriate fixed disk letter.

PATH should contain:

The Microsoft C compiler directory which is normally located in the Visual C++ 2017/2022 bin directory.
The Domino or Notes program directory; normally d:\lotus\notes. The Domino or Notes program directory contains the Domino or Notes executables and DLLs. This is required if the DLLs are loaded implicitly. As an alternative, the DLLs may be loaded explicitly by an application. See the chapter "Program Structure: Overview" in this User Guide for more information.

LIB should contain:

The HCL C API libraries directory; normally d:\notesapi\lib\mswin32(or d:\notesapi\lib\mswin64 for 64 bit Windows).
The Microsoft C libraries directory

INCLUDE should contain:

The HCL C API include files directory: normally d:\notesapi\include.
The Microsoft C include files directory

Common makefile environment file:
This file has the common compilation options that used to compile C-API samples code in windows. Set the PATH environment to the C-API samples folder,
set PATH=d:\notesapi\

Header File Conflict

The Microsoft Visual Studio 2017/2022 and the HCL C API Toolkit for Domino and Notes contain some include files with the same name (such as mq.h, neterr.h and stats.h) but the contents of the files differ. If your API program requires the HCL C API header file for Domino and Notes but does not require the Visual C++ 2017/2022 version of the file, you may resolve the conflict by putting the HCL C API for Domino and Notes include path before the Visual C++ 2017/2022 include path in your INCLUDE environment variable. 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.

The header file in the HCL C API Toolkit for Domino and Notes, global.h, contains a definition for the data type QWORD that is also defined in the Microsoft Visual C++ 2017/2022 header file, sqltypes.h. Although the definitions ultimately result in the same data type, 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 the sqltypes.h header file in a separate module.

Testing the Installation

After installing Domino or Notes, the C compiler, the development files, the documentation, and the sample API programs, follow these steps to build and test the sample API program introwin.exe.

Verify that Domino or Notes executes successfully in your environment. HCL C API programs for Domino and Notes require that Domino or Notes be installed properly in the environment.
From the Windows program manager, start an MS-DOS Command Prompt.
Change to the directory containing the sample program INTROWIN. Normally, this is

d:\notesapi\samples\basic\introwin
Type DIR to list the files in this directory. This directory contains the Windows makefile, mswin32.mak(or mswin64.mak for 64 bit Windows).
Enter this at the command prompt to build introwin.exe:

nmake /f mswin32.mak or mswin64.mak /a

The program should compile and link with no errors. The resulting executable, introwin.exe, is a Windows program.
Make sure the database, intro.nsf, is in the Domino or Notes data directory.
From either the File Manager or the MS-DOS Command Prompt, run the program introwin.exe. The "Intro Notes API Program" window should open with a File menu option.
Select File - Get Database Title. The "Get Database Title" dialog box appears. Type "intro" in the "Get Database Name" edit field. Select OK.

A dialog box should display the following output:

Database title: API Test Database (intro)

Program Structure

Initializing the Domino or Notes Run-Time System

A C API program may use any of the following methods to initialize the Domino or Notes run-time system:

NotesMain

AddInMain

main

MainEntryPoint

Naming Conventions

HCL Domino Server add-in programs and menu add-ins use a Domino-specific naming convention. The name of a Windows server or menu add-in must begin with "n", followed by one to seven characters and the appropriate file extension (.exe or .dll). For example, the sample program basic\add_res, when built as a Windows application, has the name nadd_res.exe.

There are no other naming restrictions for HCL C API applications for Domino and Notes. Any other type of C API application may use any valid program file name.

Toolkit Files

This section describes the components of the HCL C API Toolkit for Domino and Notes that support the Microsoft Visual C++ 2010 compiler and linker.

HCL C API Header Files for Domino and Notes

In the HCL C API Toolkit for Domino and Notes, support for all platforms is provided by the common include files in \notesapi\include. When compiling, the header files require the use of the compiler command-line switch "-DWIN32" to enable conditional compilation features specific to Win32.

HCL C API Library File for Domino and Notes

The file \notesapi\lib\mswin32\notes.lib(change mswin32 to mswin64 for 64 bit Windows) is the DLL import library needed to link HCL C API applications that make calls to HCL Domino or HCL Notes. If your application loads the Notes DLLs explicitly, you do not need to link notes.lib.

HCL C API Bootstrap Object Files for Domino and Notes

The bootstrap object files in the directory \notesapi\lib\mswin32(change mswin32 to mswin64 for 64 bit Windows) are required to construct a API program using the NotesMain entry point and to construct server add-in tasks. The file notes0.obj provides the entry point and Domino or Notes run-time initialization for applications. The file notesai0.obj is used in conjunction with notes0.obj to provide the entry point and run-time initialization for HCL Domino Server add-in tasks.

HCL C API Editfax library

The file \notesapi\lib\mswin32\editfax.lib(change mswin32 to mswin64 for 64 bit Windows) is the Editfax import library needed to link HCL C API applications that implement the Editfax APIs.

Compatibility

HCL Domino and HCL Notes 14.0.0 support applications developed using the HCL C API Toolkit for Notes/Domino 14.0.0 as well as existing Domino and Notes Releases (providing that Release/Build environment is supported on the given Windows OS).

Data Addressing and Pointers

HCL C API functions for Domino and Notes expect all addresses and pointers to be pointers in the flat-model virtual memory space.

Calling Conventions

Most HCL C API functions for Domino and Notes use the __stdcall calling convention, just as the Windows API does. A few functions require a variable number of parameters; these functions use the cdecl calling convention. Under normal circumstances, specifying the appropriate calling convention is handled by the C API header files.

Data Structure Packing

Is dependent on the compiler and bitness of the program and controlled via the compiler flags

Compiling

This section describes the settings to use when building HCL C API applications for Domino and Notes from the command line or via a makefile. To build applications with the Visual C++ 2017/2022 developer environment, please refer to the "Microsoft Visual C++ 2017/2022" section below.

Platform ID Macro

The HCL C API include files for Domino and Notes use the platform ID macro for conditional compilation that depends on the target execution environment. You can also use this macro in API applications to control compilation of platform-dependent features. For 32-bit Windows applications, the platform ID macro is W32. The old macro, NT, is still supported for compatibility with existing API applications. Be aware that the UNIX platform ID macro also defines the W32 platform ID macro. If you need conditional compilation for 32-bit Windows, but not for UNIX, be sure to check that W32 is defined and UNIX is not defined. Alternatively you can use the NT platform ID macro for 32-bit Windows conditional compilation.

Compiler Switches

To compile HCL C API code for Windows, please follow the guidelines in the appropriate cmp.txt file (w32_cmp.txt for 32 bit, w64_cmp.txt for 64 bit)

Linking

Stack Size

Stack space on Win32 platforms is managed dynamically, with default settings that may be modified in an application. As a general guideline, at least 2,048 bytes of stack space should be available when calling a HCL C API application for Domino or Notes.

Linker Switches

Please see the appropriate cmp.txt file

Run-Time Libraries

The HCL C API for Domino and Notes is implemented as a dynamic-link library (DLL) which is statically linked to the multi-threaded version of the Microsoft C run-time library. Domino and Notes do not require installation of the Microsoft run-time DLLs. However, the Microsoft linker reports a warning if applications are linked with both the C API library and the Microsoft DLL run-time libraries. This is because of problems that occur when applications and DLLs are linked with different versions of the C run-time libraries. Multiple copies of information are stored in different memory blocks, and the application and DLL must be designed to ensure that resources such as memory or files and handles allocated by one instance of the C run-time library are used and released by the that instance.

The HCL C API for Domino and Notes does not share C run-time memory or file handles with the application. Applications may be linked with any version of the Microsoft C run-time libraries. To avoid this warning, applications must be linked with the statically-linked C run-time libraries.

For more information on the limitations on C runtime libraries, and information on how statically-linked and dynamically-linked run-time libraries can be combined, please consult the Microsoft Visual C++ 2010 documentation, or see Microsoft Knowledge Base article Q94248, "Using the C Run-Time".

For applications built using the standard macros from win32.mak, you can use the following macros:

If you want to link with the dynamically-linked run-time libraries, you can use the following macros:

Microsoft Visual C++ 2017/2022 Development Environment (64 bit)

This section describes Microsoft Visual C++ 2017/2022 development environment project settings that are required when you are building applications that use the HCL C API for Domino and Notes.

Directory Settings

You must specify the HCL C API for Domino and Notes include file and library file directories in the Visual C++ 2017/2022 directory settings:

I. Select "Project - Properties ..." to open the Options dialog box.
II. Select the "VC++" Directories
III. Select Include Directories and add the HCL C API include file directory (for example, c:\notesapi\include)
IV. Select Library directories and add the HCL C API library file directory (for example, c:\notesapi\lib\mswin64)

These settings change the environment maintained by the Visual C++ 2017/2022 and will be retained for all projects.

Project Settings

Project settings specify what file to run and where to run it.

I. Select "Project - Properties..." to open the project's Property Pages dialog box.
II. Expand the "Configuration Properties" folder, then the "Debugging" category.
III. Enter the name of the program executable in the "Command" field.
IV. Enter the path to the Domino or Notes executable directory in the "Working Directory" field.
V. If the file notes.ini is located somewhere other than the Windows system directory or the Domino or Notes program directory, enter an "=" sign followed by the fully-qualified pathname of the notes.ini file in the "Command Arguments" field. For example, if the notes.ini file is in the directory "d:\apps\notes," enter:

=d:\apps\notes\notes.ini

Compiler Settings

The compiler settings correspond to the compiler switches and input options required when building applications from the command line:

I. Select "Project - Properties..." to open the project's Property Pages dialog box. Expand the "Configuration Properties" folder.
II. If you wish, select the "General" category and set the "Output Directory" field to specify the relative directory for your program.
III. Select the "Debugging" category.
IV. Enter the path to the Domino or Notes installation directory in the "Working Directory" field.
V. Select the "C/C++" sub-folder. Note that this sub-folder is not available if the project uses a makefile that was not created by the Visual C++ 2017/2022. In this case, you must use the compiler switches described above on the compiler command line.
VI. Compiler settings are entered by choosing a category.
VII. Select "Active Debug" configuration and platform x64
VIII. We recommend setting the "Warning level" to "Level 3" under the "General" category. This corresponds to the switch /W3.
IX. Select the "Code Generation" category.
X. Select an appropriate entry from the "Runtime Library" pull-down menu. The compatible libraries are:

Multi-Threaded (/MT)
Single-Threaded Debug (/MTd)
Multi-Threaded DLL (/MD) Muti-Threaded DLL Debug (/MDd)

XI. Select the appropriate setting from the "Struct Member Alignment:

Link Settings

The only link settings relevant to the HCL C API for Domino and Notes are the selection of object and library modules:

I. Select "Project - Properties..." to open the project's Property Pages dialog box. Expand the "Configuration Properties" folder.
II. Select the "Linker" sub-folder. Note that this tab is not available if the project uses a makefile that was not created by the Visual C++ 2017/2022. In this case, you must use the linker switches described above on the linker command line.
III. Linker settings are entered by choosing a category. Select the "Input" category.
IV. In the "Additional Dependencies" field, add notes.lib.
V. If your application is a NotesMain application, add notes0.obj.
VI. If your application is a HCL Domino Server add-in, add notesai0.obj and notes0.obj.
VII. If your application implements the Editfax APIs, add editfax.lib.
If you are linking with notes0.obj and are using a run-time library other than libc.lib, select the option "Ignore All Default Libraries" to ignore the default library information in notes0.obj. This corresponds to the

Debugging with the Visual C++ 2017/2022

There are no special considerations for debugging applications or DLLs that make calls to the HCL C API for Domino and Notes. The only special considerations are for DLLs that are called from Domino or Notes, such as menu add-ins, hook drivers, or Extension Manager DLLs. The following instructions apply only to debugging DLLs that are called from Domino or Notes.

Normally, Domino and Notes expect to find any DLLs that it must load in the directory where the Domino or Notes executables are installed. To specify that DLLs built using the Visual C++ 2017/2022 are placed in this directory:

I. Select "Project - Properties..." to open the project's Property Pages dialog box.
II. Expand the "Configuration Properties" folder and select the "General" category.
III. Enter the path of the Domino or Notes installation directory in the "Output Directories" field.

The Notes user interface is implemented as a loader program, notes.exe, and the workstation executable. To debug a DLL that is loaded by Notes, you must specify the workstation executable (not notes.exe) for Visual C++ 2017/2022 :

I. Select "Project - Properties..." to open the project's Property Pages dialog box.
II. Expand the "Configuration Properties" folder and select the "Debugging" category.
III. Enter the name of the Notes workstation executable, notes.exe, in the "Command" field.
IV. Enter the path to the Notes installation directory in the "Working Directory" field.
If the file notes.ini is located somewhere other than the Windows system directory, enter an "=" sign followed by the fully-qualified pathname of the notes.ini file in the "Command Arguments" field. For example, if the notes.ini file is in the directory "d:\apps\notes," enter:

=d:\apps\notes\notes.ini

Building 32-bit Windows Applications with IBM VisualAge C++

You can build C API applications with the IBM VisualAge C++ toolkit. However, please note that the C API toolkit does not fully support the IBM VisualAge C++ toolkit nor has it been thoroughly tested with IBM VisualAge C++.

Programs built with the IBM VisualAge C++ must be "main" programs. You will not be able to use NotesMain or AddinMain because these rely on notes0.obj or notesai0.obj which are not compatible with the IBM VisualAge C++ compiler and linker.

Here is an example of an IBM VisualAge C++ makefile to build an application with IBM Visual Age. This example will build the basic\intro program that comes with the C API toolkit.

PROGNAME = INTRO

# Dependencies $(PROGNAME).EXE: $(PROGNAME).OBJ $(PROGNAME).OBJ: $(PROGNAME).C

# Compilation command. .C.OBJ: icc /C+ /Gm+ /Sp1 /DW32 /W3 $*.C

# Link command. .OBJ.EXE: ILINK /OUT:$*.EXE $*.OBJ notes.lib

---