UNIX: C++ Application Development

Printer-friendly version

This topic provides details about developing Objectivity/C++ applications on UNIX platforms. You should use this appendix in conjunction with the Objectivity/C++ and Objectivity/DDL books.

If you want to learn how to use various Objectivity/C++ features, consider downloading and running some of the sample C++ applications.

Linking Applications to Objectivity/DB

You can link C++ database applications to Objectivity/DB static or shared libraries.

Libraries for Static Linking

The following table shows Objectivity/DB static runtime libraries for C++ applications.

Note: Static libraries are no longer included with the Objectivity/DB installation. If you require static libraries, contact Objectivity Customer Support.

Table 1: Objectivity/DB Static Link Libraries (On Request Only)
Library File Description
liboo.a Objectivity/DB standard library.
liboo_adm.a Objectivity/DB administration library. Add this library to your link line before liboo.a if you are using Objectivity/C++ member functions to perform recovery operations.
liboo_dbg.a Debug version of the Objectivity/DB standard library. Add this library to your link line instead of liboo.a if you want to use debug mode or Objectivity/DB debugger tools. This library performs more runtime checking than liboo.a.

Static Link Rules

The following table summarizes link rules for linking with the standard Objectivity/DB static runtime library.

This table uses the following convention:

installDir Objectivity/DB installation directory—by default, /opt/Objectivity/version

Table 2: Static Link Rules
Architecture Link Rule
hpuxia64 installDir/lib/liboo.a -AA +DD64 -mt -lpthread -lnsl
linux86_64 installDir/lib/liboo.a-lnsl-pthread -ldl
linux86gcc3 installDir/lib/liboo.a -lnsl -pthread -ldl
solaris7 -LinstallDir/lib -Bstatic -loo -Bdynamic -library=stlport4 -lpthread -lrpcsvc -lnsl -lsocket -ldl -mt
solaris86_64 -LinstallDir/lib -Bstatic -loo -Bdynamic -library=stlport4 -lpthread -lrpcsvc -lnsl -lsocket -ldl -m64 -mt
sparc64a -LinstallDir/lib -Bstatic -loo -Bdynamic -library=stlport4 -lpthread -lrpcsvc -lnsl -lsocket -ldl -m64 -mt

a. If you are using version 5.7 or earlier of the Sun C++ compiler, you will need to specify the -xarch=v9 flag instead of the -m64 flag.

Linking to Shared Libraries

The names of Objectivity/DB shared libraries vary on different architectures and contain digits x.x corresponding to the current Objectivity/DB release. To link Objectivity/DB applications to the shared libraries on UNIX, choose a link rule depending on:

  • Whether you are linking applications for development or end-user deployment.
  • The architecture you are using—for example, solaris7.

If your application uses persistent collections or the C++ programming interface of other Objectivity products, you must add other libraries to your link line (see Linking to Additional Objectivity Products and Features).

Link Rules for Development Environments

The following table summarizes C++ UNIX shared library link rules for development environments.

This table uses the following convention:

installDir Objectivity/DB installation directory—by default, /opt/Objectivity/version
x.x Digits corresponding to the current Objectivity/DB release

Table 3: Shared Library Link Rules for Development
Architecture Link Rule
hpuxia64 -LinstallDir/lib -loo.x.x -AA +DD64 -mt -lpthread -lnsl
linux86_64 -LinstallDir/lib -Bdynamic -loo.x.x -Xlinker -pthread -ldl-rpath-link=installDir/lib
linux86gcc3 -LinstallDir/lib -Bdynamic -loo.x.x -pthread -ldl-rpath-link=installDir/lib
solaris7 -LinstallDir/lib -loo.x.x-library=stlport4 -mt
solaris86_64 -LinstallDir/lib -loo.x.x-library=stlport4 -mt -m64
sparc64a -LinstallDir/lib -loo.x.x-library=stlport4-mt -m64

a. If you are using version 5.7 or earlier of the Sun C++ compiler, you will need to specify the -xarch=v9 flag instead of the -m64 flag.

Link Rules for End-User Environments

The following table provides information for embedding the runtime shared-library search path so that you will be able to find Objectivity/DB libraries in the Installation directory at an end-user site.

Note: The options in this table should be used in addition to the options listed in Table 3 when linking applications for deployment.

This table uses the following convention:

installDir Objectivity/DB installation directory—by default, /opt/Objectivity/version
endUserInstallDir Installation directory at an end-user site

Table 4: Shared Library Link Rules for Deployment
Architecture Link Rule
hpuxia64 -Wl,+s -Wl,+bendUserInstallDir
linux86_64 -Xlinker -rpath-link=installDir/lib -Xlinker -rpath=endUserInstallDir
linux86gcc3 -Xlinker -rpath-link=installDir/lib -Xlinker -rpath=endUserInstallDir
solaris7 Define LD_RUN_PATH prior to compiling and linking.
solaris86_64 Define LD_RUN_PATH prior to compiling and linking.
sparc64 Define LD_RUN_PATH prior to compiling and linking.

Linking With Purify

If you are linking your application with Purify, you may want to suppress Objectivity/DB UMRs when you run your application. These UMRs are produced in error and can safely be ignored. To do so, add the following entries to your .purify file:

suppress umr write; …; onmWrite;
suppress umr write; …; onmSeekWrite;

Linking to Additional Objectivity Products and Features

When you are ready to deploy your application, you should use a command such as ldd to identify any required libraries.

If your database application uses the C++ programming interfaces of other Objectivity products, you might need to augment the link rules given in Table 3 and Table 4.

The following table shows products that require additional link lines (as well as products that are loaded automatically via the link to the Objectivity/DB shared library). The additional link lines should be added before the shared Objectivity/DB library.

Note: Shared library names vary on different architectures and may contain digits x.x corresponding to the current Objectivity/DB release.

Table 5: Objectivity Libraries
To Use Link to
In-process lock server (IPLS) Link to the Objectivity/DB shared library. The IPLS library is loaded automatically at runtime when needed.
Objectivity/DB Active Schema for C++ -looas.x.x

Link to the Objectivity/DB shared library.
Objectivity predicate query language Link to the Objectivity/DB shared library. The predicate query language library is loaded automatically at runtime when needed.
ooObjectQualifier to qualify objects, or predicate scans -looObjectQualification

Link to the Objectivity/DB shared library.
Parallel query feature Link to the Objectivity/DB shared library. The parallel query library is loaded automatically at runtime when needed.
Managed placement Link to the Objectivity/DB shared library.

If Your Application Uses Persistent Collections

If the persistent collections used by your application are all implemented with the Release 9.3 (or later) scalable collection structure (for example, ooTreeSetX), you should include the header file ooCollectionBase.h. No special linking is necessary, other than linking to the Objectivity/DB library.

If any of the collections used by your application are implemented with the pre-Release 9.3 scalable collection structure (for example, ooTreeSet), you must include the header file ooCollections.h. The following table lists the collection-specific shared libraries:

To Use Link to
Objectivity/C++ persistent collections -looco.x.x

Linking a Lock-Server Performance-Monitoring Program

The following table lists the libraries for linking a custom C++ program that monitors how your database applications interact with a running lock server. The information collected by such a program can help you analyze application performance (for more information, see Monitoring Lock-Server Performance).

Table 7: Linking a Lock-Server Performance-Monitoring Program
Link to Description
-loolspm.x.x Shared library on all other architectures

Using Makefiles

You can use a makefile to run the DDL processor and then compile and link your application with the DDL-generated header and implementation files. You can use the makefiles from the downloadable C++ sample applications as templates (see their included readme files). You can also refer to the makefiles in the samples directory in your installation hierarchy.

installDir/samples/cxx/helloWorld

Compiler Flags

In general, you should use the same compiler flags as those used in the sample makefiles. Note:

  • On thehpuxia64 architectures, you must use the -AA, -mt, and +DD64 compiler flags.
  • On the linux86_64 and linux86gcc3 architectures, you should avoid using the -Weffc++ and -Wnon-virtual-dtor options, because they will result in compiler warnings that cannot be fixed. (Alternatively, you can suppress these warnings by accessing the Objectivity/DB include directory with the -isystem option.)

Application Programming Issues

Signal Handling

The Objectivity/DB predefined signal handler catches the following UNIX signals: SIGINT, SIGQUIT, SIGILL, SIGABRT, SIGFPE, SIGBUS, SIGSEGV, SIGHUP, SIGTERM, SIGEMT, and SIGTRAP.

Stack Size for Multithreaded Applications

In a multithreaded application, you may need to increase the stack size for each thread that executes Objectivity/DB operations. This is because the default thread stack size on some platforms may be insufficient to accommodate an Objectivity context. A minimum of 1 megabyte is recommended.

File Descriptor Limit

When running multithreaded programs with large numbers of threads, your process may reach the file descriptor limit. When this limit is reached, Objectivity/C++ operations may fail because the process cannot obtain a file descriptor.

To eliminate such errors, you should increase the file descriptor limit. The csh and ksh commands for increasing the limit are shown in the following example. If you still experience errors, you should increase the limit incrementally.

Example

csh:

limit descriptors 256 

ksh:

ulimit -n 256    

Debugging an Application

While debugging an Objectivity/C++ application, you can:

You must prepare your application for debugging, as described in the following subsection. The remainder of this section describes how to print handles and persistent objects from the dbx debugger.

Note: Static libraries are no longer included with the Objectivity/DB installation. If you require static libraries, contact Objectivity Customer Support.

Preparing to Debug an Application

Before you can debug your Objectivity/C++ application, you must recompile your source code with the debug flag for your compiler (for example, -g), and relink your application to the Objectivity/DB library liboo_dbx.a.

Printing Handles

While using dbx, you can print a variable whose value is a handle. Doing so displays the object identifier of the persistent object that the handle references.

Example

Assume your application sets a handle variable oopvar to reference a persistent object whose object identifier is 2-2-25-144. To print the variable oopvar, you enter the following dbx debugger command:

print oopvar   

The variable oopvar is printed as follows:

oopvar = {
  _DB   = 2
  _OC   = 2
  _page = 25
  _slot = 144
}  

Printing Objects

While using the dbx debugger, you can print the contents of a persistent object from the object’s handle. The easiest way to do this is to use the ooprint convenience function. See "Debugging a Federated Database" in Objectivity/DB Administration.



 

Date: 
Monday, August 20, 2012
Product: 
Objectivity/DB
Version: 
11.0