|HMNL Home|| The Domino eXplorer Development Environments|
Notes API Installation
For both Windows and Linux DXTools assumes that the Notes API is installed in the default configuration specified in the API documentation.
Project Directory Structure
The default Domino eXplorer development environment follows the Visual Studio paradigm of a “Solution” directory that contains multiple “Project” directories with a single application directory per application, this paradigm is followed on both Windows and Linux development environments.
Solution Directory - <any name>
Common Code Sub-Directory - "DXCommon"
Application Project Directory - <Application Name>
In Visual Studio the DXCommon project directory should have the “Do Not Build” property set.
The standard DX header and code files are NOT designed to be added to the default include search directories on either environment. The package expects to find a directory called “DXCommon” as a project level directory in each solution directory that will be used to build DX applications, these should be included in applications by relative re-direction. An include statement for the PlatBase.h header file that is located in the “Platform” sub-directory of the DXCommon package would be coded as follows.
// Platform Includes
#include "../DXCommon/Platform/PlatBase.h" // Basic platform includes
Although a copy of the DXCommon package could be physically placed in each solution directory it would be more usual to place the package in a shared location on the development workstation/server and then create a symbolic link in each of the solution directories.
The DXCommon kernel is supplied as a zipped archive (.zip). The contents of the archive should be unpacked to either the <solution directory>\DXCommon directory or unpacked to a directory that will then be used as the base for a symbolic link from the <solution directory>\DXCommon directory.
As an example.
Unpack the DXCommon kernel into a directory “c:\usr\include\DXCommon-3.12.0” and then create the symbolic link from within the solution directory using the following command.
mklink /D DXCommon “c:\usr\include\DXcommon-3.12.0”
The DXCommon kernel is supplied as a gzipped archive (.tar.gz). The contents of the archive should be unpacked to either the <solution directory>/DXCommon directory or unpacked to a directory that will then be used as the base for a symbolic link from the <solution directory>/DXCommon directory.
File ownership and access settings should be adjusted according to your local policies.
As an example.
Unpack the DXCommon kernel into a directory “/usr/include/DXCommon-3.12.0” and then create the symbolic link from within the solution directory using the following command.
ln -s /usr/include/DXCommon-3.12.0 DXCommon
This deployment model allows different levels of the DXCommon package to be used in different solutions without reconfiguring the development environment.
Building DX Applications
The following non-default settings should then be made to the project settings. Any other settings should not prevent a successful build.
- Static linking of the runtime is used as since the advent of Side-By-Side (SXS) assembly of applications it is increasingly common to find server environments that do not have the latest C/C++ Runtime manifests installed.
- /Zp1 packing is a Notes API requirement as all Notes API structures are packed and not padded or member aligned.
- /Oy- is an important setting, without it the compiler will use the Frame Pointer as a general purpose register rather than pointing to the current frame, this will cause any NSD dump to be complete garbage and make debugging virtually impossible.
- The additional libraries for the debug settings Dbghelp.lib and Psapi.lib are used to enable additional debug capabilities such as memory leak detection that are provided by DXCommon kernel modules.
Select “Build” and then “Build <application name>”.
A makefile is supplied in the source distribution of any distributed DX application. The makefile is listed below along with any specific notes. The Makefile supports the following invocation models.
make <application name>
This form of the command will build any object modules that are out of date and re-link the executable.
make rebuild <application name>
This form of the command will force a rebuild of all object modules and re-link the executable.
make rebuild <application name> BV=DBG
This form of the command will force a rebuild of all object modules with the _DEBUG define set and will re-link the executable.
The following shows the common compile and link options used in DX application makefiles.
# Define the build options
CC = g++
CCOPTS = -c -march=i486
NOTESDIR = $(LOTUS)/notes/latest/linux
LINKOPTS = -o <application name>
DEFINES = -DUNIX -DLINUX -DHANDLE_IS_32BITS
INCDIR = $(LOTUS)/notesapi/include
LIBS = -lnotes -lm -lnsl -lpthread -lc -lresolv -ldl
DEFINES = -DUNIX -DLINUX -DHANDLE_IS_32BITS
Deploying DX Applications
Copy the resulting executable (<application name>.exe) and the associated Program Debug Database (<application name>.pdb) to the Notes Executable directory on the server or workstation where you want to run the Add-In or command processor.
Copy the resulting executable (<application name>) to the Notes Executable directory where you want to run the Add-In or command processor. According to your local security policies and Domino install you may need to have an administrator copy the executable and possibly change ownership of the executable. Note that the application name is folded to lower case if it is to be used on a server as certain interfaces coerce the name to lower case.
The default ownership and attributes indicated by the Notes API documentation are as follows.
chown server <application name>
chgrp notes <application name>
chmod 2555 <application name>
Deploying DX Databases
Any application supplied as a standard DX Tool that uses a database distributes the database as a "Virtual Template", these are Notes Database designs that are delivered via the internet in DXL source format.
The installation of the control database is done from a “Virtual Template” that is available on the internet, this section assumes that you have available and installed the Remote Database Create (Windows:
RDBCreate.exe and RDBCreate.pdb Linux: rdbcreate) tool. If you do not have this tool then download the DXTool source for RDBCreate and build it. Refer to the “Using RDBCreate” manual.
From a command window go to the Notes Executable directory where RDBCreate exists enter the following command.
RDBCreate <server name> <database name> <templateURL> -V
<server name> is the abbreviated name of the server on which you want to install the control database.
<database name> is the name of the control database relative to the notes data directory.
<templateURL> is the URL for the Virtual Template you wish to install.
For example the QCopy Control Database, uses the following template URL: