Using C++ with Caché
The Caché C++ Binding
[Home] [Back] [Next]
InterSystems: The power behind what matters   
Class Reference   
Search:    

The Caché C++ binding provides a simple, direct way to use Caché objects within a C++ application. You can create C++ applications that work with the Caché database in the following ways:

Each of these features is discussed in the following chapters.
This document assumes a prior understanding of C++ and the C++ standard library. Several C++ compilers are supported, but Caché does not include a C++ compiler or development environment.
C++ Binding Architecture
The Caché C++ Binding gives C++ applications a way to access and manipulate objects contained within a Caché server. These objects can be persistent objects stored within the Caché object database, or they can be transient objects that perform operations within a Caché server.
The Caché C++ Binding consists of the following components:
The Caché C++ Generator can create C++ client classes for any classes contained within the Caché Class Dictionary. These generated C++ classes communicate at runtime (using TCP/IP sockets) with their corresponding Caché class on a Caché server. This is illustrated in the following diagram:
C++ Client/Server Class Architecture
The basic mechanism works as follows:
The runtime architecture consists of the following:
Note:
The architecture of the Light C++ binding is quite different. It trades flexibility for speed by running all client and server operations on the same machine, using intraprocess communications instead of TCP/IP to exchange data between the C++ application and the Caché Object Server.
The Caché C++ Library
The Caché C++ binding's dynamic library of C++ classes implements the basic connection and caching mechanisms required to communicate with a Caché server.
The C++ components required to connect to Caché are contained within the C++ library file, which is located in the <cachesys>\dev\cpp\lib directory (see Default Caché Installation Directory in the Caché Installation Guide for the location of <cachesys> on your system). This directory contains different versions of the library that correspond to different build configurations for different platforms. A corresponding set of include files is located in the <cachesys>\dev\cpp\include subdirectory.
This library includes C++ versions of a number of the classes within the Caché class library, including %Persistent, %RegisteredObject, %SerialObject, the various Caché collection classes, and C++ versions of the various data type classes. In addition, the library contains the various classes used within a C++ application to manage communication with the Caché server.
The classes that are available for use in your C++ binding applications are listed and discussed in the following chapters:
Installation and Configuration
The Caché C++ binding software is not part of the standard Caché installation, but is offered as a option in the custom installation. For a list of the platforms that support the C++ Binding, see “Supported Client Platforms” in InterSystems Supported Platforms.
Caché C++ binding applications require a C++ compiler that supports the C++ standard library. When you compile, your path should include the following directories (see Default Caché Installation Directory in the Caché Installation Guide for the location of <cachesys> on your system):
    <cachesys>\bin
    <cachesys>\dev\cpp\lib
A compiled C++ binding application will be able to access existing Caché classes with no additional setup, and can run on client machines that do not have Caché installed.
If Caché is installed with level 3 ("locked down") security, %Service_Bindings must be enabled in order to run the Caché C++ Generator.
The Light C++ Binding has additional requirements (see Installing the Light C++ Binding).
Building the Caché C++ Binding from Source
In some special situations, it may be useful to build the Caché C++ Binding from source code. The source code is installed if you select the "C++ SDK" option during a custom install of Caché. Windows MSVC projects or UNIX® makefiles can be customized as desired to use different versions of compilers or standard libraries. On UNIX®, gmake is required. As shipped, the sources, projects, and makefiles are identical to those used to build the production version of the C++ binding, but they can be used, without modification, to rebuild with different gcc versions on Linux. This may be necessary, since C++ code built with different gcc versions is often not binary-compatible.
Configuring Microsoft Visual Studio 2008
The following instructions describe the procedure for configuring a Caché C++ binding project in Microsoft Visual Studio 2008 under Windows XP. Some details may be different in other environments.
Setting Windows Environment Variables
Before you configure a project, you must set some Windows environment variables. The procedure is as follows:
Configuring the Project
Open the Visual Studio 2008 Project References window:
Enable wchar_t and Run-Time Type Information (RTTI) support:
Specify the location of the C++ Binding header files:
Specify the location of the C++ Binding library directory:
Specify the location of the C++ Binding release library:
Specify the location of the C++ Binding debug library:
Specify the runtime library for Release code generation:
Specify the runtime library for Debug code generation:
Using the C++ Binding with ACE Libraries
When using C++ binding (regular or light) with ACE libraries on Windows, Caché header files must appear after ACE header files. This is because ACE headers include Microsoft winsock2.h, and the Caché C++ binding class headers include Microsoft windows.h. When both files are included, winsock2.h must appear before windows.h, or the MSVC compiler will fail due to definition conflicts.
Here is an example that includes ACE headers. Since Sample_Person.h and Sample_Address.h are Caché C++ Binding class headers, they must appear after all of the ACE headers:
#include "ace/OS_main.h"
#include "ace/streams.h"
#include "ace/Log_Msg.h"
#include "ace/SOCK_Acceptor.h"
#include "ace/INET_Addr.h"
#include "ace/Service_Config.h"

#include "CPP-acceptor.h"

ACE_RCSID (non_blocking,
    test_sock_acceptor,
    "test_sock_acceptor.cpp,v 4.11 2004/10/27 21:06:58 shuston Exp")

typedef Svc_Handler<ACE_SOCK_STREAM> SVC_HANDLER;
typedef IPC_Server<SVC_HANDLER, ACE_SOCK_ACCEPTOR> IPC_SERVER;

#include "Sample_Person.h"  // C++ binding projected class header
#include "Sample_Address.h"  // C++ binding projected class header
Installing the Light C++ Binding
The Light C++ Binding (LCB) is a special purpose subset of the Caché C++ Binding, and has some extra requirements. For a list of the platforms that support the Light C++ Binding, see “Supported Client Platforms” in InterSystems Supported Platforms.
Additional LCB Requirements
The design of LCB imposes the following extra requirements:
Note:
CACHEMGRDIR Deprecated
In previous releases, the required environment variable was CACHEMGRDIR, set to the <cache-root>/mgr directory rather than <cache-root>. Although this variable can still be used, it is deprecated. GLOBALS_HOME will be used instead of CACHEMGRDIR if both variables are set.
Installation on the Windows 64 bit Platform
The Light C++ Binding is available for the Windows 64 bit platform. The Caché installation for 64 bit Windows still installs a 32 bit version of the standard Caché C++ Binding, since this is required for Studio. To build 64 bit versions of the LCB sample applications, use the "win64 Release" or "win64 Debug" configurations in the MSVC project files for these applications.
In order to run debug versions of LCB applications, you will need to download the Microsoft Platform SDK, which contains 64 bit debug versions of the libraries msvcrtd.dll and msvcp60d.dll. On 64 bit systems, installing Microsoft Visual Studio only provides the 32 bit versions of these files. (This is a general issue for C++ development on 64 bit systems, not specific to Caché or to the Light C++ Binding.)
Running Trusted Applications on UNIX®
Light C++ Binding applications on UNIX® must be run either by root, or by a user belonging to the cacheusr group, unless the application has been made a "trusted application". The recommended approach for deployed applications is to make them trusted applications. When this is done, the application runs with cacheusr as the effective group, but any user who has execute access to the application's executable file can run it (where execute access is controlled in the usual UNIX® manner using chmod).
To make a trusted application, do the following:
Sample Programs
The standard Caché installation includes several short sample programs, located in the C++ samples directory, <cachesys>\dev\cpp\samples\ (see Default Caché Installation Directory in the Caché Installation Guide for the location of <cachesys> on your system). The following sample programs are available:
MS Visual Studio project files for these programs are available in:..\samples\msvc90
For UNIX® platforms, run_samples.sh can be used in Caché 2008.1 and later.
Required Proxy Classes
The samples.cpp program uses classes from the Sample package in the SAMPLES namespace, which is also part of the standard Caché installation. The following C++ proxy class files must be generated (see Generating Proxy Classes) for Sample.Person and Sample.Address if they are not already present in the main C++ samples directory:
The lcbdemo.cpp program uses classes from the User package in the SAMPLES namespace. The following C++ proxy class files must be generated for User.Person and User.testidkey2 if they are not already present in the main C++ samples directory: