Overview
This document describes how to install and use ObjectHandler on Windows and on systems which use Autoconf e.g. Linux.
ObjectHandler logging is performed by log4cxx, the logging framework for the Apache project. ObjectHandler uses a customized copy of log4cxx version 0.10.0, called "log4cxx 0.10.0f14", amended to provide a boost compliant build process and other minor enhancements.
Some ObjectHandler source code is generated by the gensrc utility.
ObjectHandler, gensrc, and log4cxx 0.10.0f14 are available for download from the QuantLib downloads page on bintray.
No binary installer is provided for the standalone ObjectHandler library. However ObjectHandler functionality is compiled into the binary installation of QuantLibXL.
1 Prerequisites
Before proceeding to compile the source code, consult the documents below.
1.1 Conventions
See the following document regarding naming conventions in use for the project: Conventions
1.2 Boost
ObjectHandler depends on Boost. Any recent version of Boost should be OK. If you're using VC9 then Boost 1.35 or later is required. QuantLib requires Boost 1.39 or later. You will need the compiled Boost libraries, the Boost header files alone are not sufficient.
1.3 Python 3.x
Some ObjectHandler code is autogenerated by gensrc, which is a Python script. Before rebuilding ObjectHandler you need to have Python 3.x installed on your machine. Here is the link to the Python website: http://www.python.org/.
On Windows, if Python is installed on your machine so that .py files are associated with the Python executable, then the gensrc scripts should build OK with no modification required.
Otherwise, after you install gensrc (below), you might need to edit this file...
ObjectHandler\gensrc\Makefile.vc
...and set the PYTHON variable equal to the location of the Python executable on your machine, e.g:
PYTHON=C:\Users\username\AppData\Local\Programs\Python\Python39\python.exe
2 Windows
2.1 Download
2.1.1 Directories
The Visual C++ project files for ObjectHandler rely on relative pathnames to refer to prerequisite projects gensrc and log4cxx. In order for this to work, these projects must reside side by side in the directory tree.
Create a new empty folder on your hard drive to serve as the root directory for the build. You can use any path, for purposes of this tutorial the build directory is C:\build_ql_1_22_0. As described below you should copy all of the required source code zip files to that directory and then unzip them in place. After all of the source code is unzipped you should have the following directory structure:
C:\build_ql_1_22_0\gensrc C:\build_ql_1_22_0\log4cxx C:\build_ql_1_22_0\ObjectHandler
2.1.2 Uncompress the Source Code
Go to the QuantLibAddin downloads page.
Download log4cxx-0.10.0f14.zip and uncompress the package to C:\build_ql_1_22_0\log4cxx.
Download gensrc-1.22.0.zip and uncompress the package to C:\build_ql_1_22_0\gensrc.
Download ObjectHandler-1.22.0.zip and uncompress the package to C:\build_ql_1_22_0\ObjectHandler.
2.2 Build
ObjectHandler is available in three configurations:
| Project | Description |
| ohlib | static library to be linked into standalone C++ applications |
| ohxllib | static library with additional functionality for Excel, to be statically linked into a single client XLL |
| ohxll | a standalone XLL comprising a global object repository which can be shared by other XLLs in the Excel session |
NB: The ohxll build of ObjectHandler requires a DLL version of the VC runtime library i.e. Debug or Release.
To build all available configurations and related examples - Open solution ObjectHandler\ObjectHandler_vc?.sln, choose configuration Release, and execute menu item Build | Build Solution.
2.3 Test
2.3.1 C++
Open a DOS prompt in directory
C:\build_ql_1_22_0\ObjectHandler\Examples\C++\bin
Execute the example program. The output should appear similar to the following:
C:\build_ql_1_22_0\ObjectHandler\Examples\C++\bin>ExampleCpp-vc80-mt-1_22_0.exe INFO - begin example program INFO - High level interrogation - after constructor INFO - log dump of object with ID = account2 property = ObjectId value = account2 property = ClassName value = Account property = Permanent value = 0 property = Customer value = customer1 property = Number value = 987654321 property = Type value = Current property = Balance value = 100 Permanent = false INFO - Low-level interrogation - after update INFO - Result of getBalance on underlying = 100 INFO - Log all objects after deleting account2: INFO - dump of all objects in ObjectHandler: Object with ID = account1: property = ObjectId value = account1 property = ClassName value = Account property = Permanent value = 0 property = Customer value = customer1 property = Number value = 123456789 property = Type value = Savings property = Balance value = Null Permanent = false Object with ID = customer1: property = ObjectId value = customer1 property = ClassName value = Customer property = Permanent value = false property = Name value = Joe property = Age value = 40 Permanent = false INFO - Balance of account account2 = 200 INFO - The initially time of creating account2 is INFO - 05/14/2008 10:47:58 INFO - The last time of creating account2 is INFO - 05/14/2008 10:47:58 INFO - relation the objects list is INFO - customer1 INFO - End example program
2.3.2 XLL - Static Link
- Start Excel
- Load the following files:
ObjectHandler\Examples\xl\xll\ExampleXLLStatic-vc??-mt-1_22_0.xll ObjectHandler\Examples\xl\exampleStatic.xls
- Hit
Ctrl-Alt-F9to recalculate
2.3.3 XLL - Dynamic Link
- Start Excel
- Load the following files:
ObjectHandler\xll\ObjectHandler-xll-vc??-mt-1_22_0.xll ObjectHandler\Examples\xl\xll\ExampleXLLDynamic1-vc??-mt-1_22_0.xll ObjectHandler\Examples\xl\xll\ExampleXLLDynamic2-vc??-mt-1_22_0.xll ObjectHandler\Examples\xl\exampleDynamic.xls
- Hit
Ctrl-Alt-F9to recalculate
2.4 Usage
In order to link ObjectHandler into your own project, use the configuration that corresponds to your chosen build as summarized in the tables below. Please refer to the example application indicated.
2.4.1 ohlib
| Project | ohlib |
| Description | Core ObjectHandler C++ static library |
| Example Client Application | ExampleCpp |
| Preprocessor Defines | - |
| Include Directories | $(OBJECT_HANDLER_DIR) |
| Link Directories | $(OBJECT_HANDLER_DIR)\lib $(LOG4CXX_DIR)\msvc\Lib |
| Link Libraries | ws2_32.lib |
2.4.2 ohxllib
| Project | ohxllib |
| Description | Excel static library |
| Example Client Application | ExampleXllStatic |
| Preprocessor Defines | XLL_STATIC |
| Include Directories | $(OBJECT_HANDLER_DIR) |
| Link Directories | $(OBJECT_HANDLER_DIR)\xlsdk\lib $(OBJECT_HANDLER_DIR)\ohxl\ohxllib\lib $(LOG4CXX_DIR)\msvc\Lib |
| Link Libraries | ws2_32.lib |
2.4.3 ohxll
| Project | ohxll |
| Description | Excel dynamic library |
| Example Client Application | ExampleXllDynamic |
| Preprocessor Defines | XLL_IMPORTS |
| Include Directories | $(OBJECT_HANDLER_DIR) |
| Link Directories | $(OBJECT_HANDLER_DIR)\xlsdk\lib $(OBJECT_HANDLER_DIR)\ohxl\ohxl\xll |
| Link Libraries | - |
2.4.4 #include
In all cases you need to add the following directive to your project's source file:
#include <oh/objecthandler.hpp>
2.4.5 Link
Your project's link to the ObjectHandler library is established automatically by the directive
#pragma comment(lib, OBJHANDLER_LIB_NAME)
in file oh/autolink.hpp
The name of the library depends on your compiler and configuration. For example, if you're using VC8, configuration Release (static runtime), the library is called
ObjectHandler-vc80-mt-s-1_22_0.lib
The location of the library depends on which project you're using (ohlib/ohxllib/ohxll), please consult the tables above.
3 Autoconf
3.1 Download
3.1.1 Directories
This example assumes that you do not have root access to your machine, so that the entire build and installation environment resides under your home directory.
Let's say your home directory is /home/erik. Create two subdirectories under that, one where you will compile the code and the other where you will install it:
/home/erik/build /home/erik/install
2.1.2 Uncompress the Source Code
Go to the QuantLib downloads page.
Download log4cxx-0.10.0f14.tar.gz and uncompress the package to /home/erik/build/log4cxx-0.10.0.
Download gensrc-1.22.0.tgz and uncompress the package to /home/erik/build/gensrc-1.22.0.
Download ObjectHandler-1.22.0.tgz and uncompress the package to /home/erik/build/ObjectHandler-1.22.0.
3.2 Build
3.2.1 Build log4cxx
Support for log4cxx is optional. If you do not require logging, then when you configure ObjectHandler (see below), pass in the argument –without-log4cxx, which will cause log messages to be written to stdout instead of to the log file. In that case you can skip ahead to the next section, 3.2.2 Build ObjectHandler. If you need logging, read on.
First you need to install apr and apr-utils. Our copy of log4cxx includes source code for apr and apr-utils. In the past we used to build them with these commands:
cd /home/erik/build/log4cxx-0.10.0/src/apr ./buildconf ./configure --prefix=/home/erik/install make install cd /home/erik/build/log4cxx-0.10.0/src/apr-util ./buildconf ./configure --prefix=/home/erik/install --with-apr=/home/erik/install make install
But those commands no longer seem to work on new linux systems. There might be a binary release available for your platform, on ubuntu you might try something like this:
sudo apt-get install libapr1-dev libaprutil1-dev
Another possibility is to go to the apache web site and download the latest sources for apr and apr-utils. At the time of this writing the files are apr-1.5.1.tar.gz and apr-util-1.5.3.tar.gz. Copy them to a temp directory, untar them, and compile them something like this:
cd /home/erik/temp/apr-1.5.1 ./buildconf ./configure --prefix=/home/erik/install make install cd /home/erik/temp/apr-util-1.5.3 ./buildconf --with-apr=../apr-1.5.1 ./configure --prefix=/home/erik/install --with-apr=../apr-1.5.1 make install
Once you have apr and apr-utils installed, go back and build log4cxx:
cd /home/erik/build/log4cxx-0.10.0
./autogen.sh
./configure --prefix=/home/erik/install --with-apr=/home/erik/install \
--with-apr-util=/home/erik/install
make install
3.2.2 Build ObjectHandler
If you don't need logging, pass in the argument –without-log4cxx to configure.
cd /home/erik/build/ObjectHandler-1.22.0
./configure --with-gensrc=/home/erik/build/gensrc-1.22.0 \
--prefix=/home/erik/install \
CPPFLAGS=-I/home/erik/install/include \
LDFLAGS=-L/home/erik/install/lib
make install
3.3 Test
cd /home/erik/build/ObjectHandler-1.22.0/Examples/C++ ./ExampleCpp
This should generate output similar to the following:
[erik@client2 C++]$ ./ExampleCpp INFO - begin example program INFO - High level interrogation - after constructor INFO - log dump of object with ID = account2 property = Balance value = 100 property = ClassName value = Account property = Customer value = customer1 property = Number value = 987654321 property = ObjectId value = account2 property = Permanent value = 0 property = Type value = Current Permanent = false INFO - Low-level interrogation - after update INFO - Result of getBalance on underlying = 100 INFO - Log all objects after deleting account2: INFO - dump of all objects in ObjectHandler: Object with ID = account1: property = Balance value = [Null value] property = ClassName value = Account property = Customer value = customer1 property = Number value = 123456789 property = ObjectId value = account1 property = Permanent value = 0 property = Type value = Savings Permanent = false Object with ID = customer1: property = Age value = 40 property = ClassName value = Customer property = Name value = Joe property = ObjectId value = customer1 property = Permanent value = false Permanent = false INFO - Balance of account account2 = 200 INFO - The initially time of creating account2 is INFO - 08/28/2008 15:54:18 INFO - The last time of creating account2 is INFO - 08/28/2008 15:54:18 INFO - relation the objects list is INFO - customer1 INFO - End example program
3.4 Usage
To incorporate ObjectHandler functionality into your own applications:
The header you need is
#include <oh/objecthandler.hpp>
To compile your program, ensure that the path containing the ObjectHandler header is among those searched by your compiler. If you have followed the build instructions above, the command would be
g++ -I/home/erik/install/include -c -o yourapp.o yourapp.cpp
When linking your program use the -l option to tell gcc to link to the log4cxx and ObjectHandler libraries, and use -L to specify the path containing those libraries, e.g:
g++ -o yourapp yourapp.o -L/home/erik/install/lib \
-lObjectHandler -llog4cxx
Finally before invoking your executable you need to ensure that your loader knows where to find the log4cxx and ObjectHandler libraries, e.g:
export LD_LIBRARY_PATH=/home/erik/install/lib