docs.intersystems.com
Home  /  Application Development: Language Bindings and Gateways  /  Using C++ with InterSystems IRIS  /  The InterSystems IRIS C++ Binding


Using C++ with InterSystems IRIS
The InterSystems IRIS C++ Binding
[Back]  [Next] 
InterSystems: The power behind what matters   
Search:  


The InterSystems IRIS™ C++ binding provides a simple, direct way to use InterSystems IRIS objects within a C++ application. You can create C++ applications that work with the InterSystems IRIS 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 InterSystems IRIS does not include a C++ compiler or development environment.
C++ Binding Architecture
The InterSystems IRIS C++ Binding gives C++ applications a way to access and manipulate objects contained within an InterSystems IRIS server. These objects can be persistent objects stored within the InterSystems IRIS object database, or they can be transient objects that perform operations within an InterSystems IRIS server.
The InterSystems IRIS C++ Binding consists of the following components:
The InterSystems IRIS C++ Generator can create C++ client classes for any classes contained within the InterSystems IRIS Class Dictionary. These generated C++ classes communicate at runtime (using TCP/IP sockets) with their corresponding InterSystems IRIS class on an InterSystems IRIS 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 InterSystems IRIS Object Server.
The InterSystems IRIS C++ Library
The InterSystems IRIS C++ binding's dynamic library of C++ classes implements the basic connection and caching mechanisms required to communicate with an InterSystems IRIS server.
The C++ components required to connect to InterSystems IRIS are contained within the C++ library file, which is located in the <installdir>\dev\cpp\lib directory (see Default Installation Directory in the Installation Guide for the location of <installdir> 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 <installdir>\dev\cpp\include subdirectory.
This library includes C++ versions of a number of the classes within the InterSystems IRIS class library, including %Persistent, %RegisteredObject, %SerialObject, the various InterSystems IRIS 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 InterSystems IRIS 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 InterSystems IRIS C++ binding software is not part of the standard InterSystems IRIS 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 the online InterSystems Supported Platforms document for this release.
InterSystems IRIS 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 Installation Directory in the Installation Guide for the location of <installdir> on your system):
    <installdir>\bin
    <installdir>\dev\cpp\lib
A compiled C++ binding application will be able to access existing InterSystems IRIS classes with no additional setup, and can run on client machines that do not have InterSystems IRIS installed.
If InterSystems IRIS is installed with level 3 ("locked down") security, %Service_Bindings must be enabled in order to run the InterSystems IRIS C++ Generator.
The Light C++ Binding has additional requirements (see Installing the Light C++ Binding).
Building the InterSystems IRIS C++ Binding from Source
In some special situations, it may be useful to build the InterSystems IRIS C++ Binding from source code. The source code is installed if you select the "C++ SDK" option during a custom install of InterSystems IRIS. 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 an InterSystems IRIS 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, InterSystems IRIS header files must appear after ACE header files. This is because ACE headers include Microsoft winsock2.h, and the InterSystems IRIS 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 InterSystems IRIS 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 InterSystems IRIS C++ Binding, and has some extra requirements. For a list of the platforms that support the Light C++ Binding, see “Supported Client Platforms” in the online InterSystems Supported Platforms document for this release.
Additional LCB Requirements
The design of LCB imposes the following extra requirements:
Installation on the Windows 64 bit Platform
The Light C++ Binding is available for the Windows 64 bit platform. The InterSystems IRIS installation for 64 bit Windows still installs a 32 bit version of the standard InterSystems IRIS 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 InterSystems IRIS 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 following sample programs are available:
MS Visual Studio project files for these programs are available in:..\samples\msvc90
Required Proxy Classes
The samples.cpp program uses classes from the Sample package. 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: