4. Developing Client Software Components

4.1. Building a component against CORAL

In order to develop applications or software components based on CORAL one should have in the INCLUDE path the include directory of a CORAL installation and link against the RelationalAccess and CoralBase libraries. Moreover, since CORAL depends on SEAL for the definition of the 64-bit integer, and the its Exception class, one should also have in the INCLUDE path the include directories of a SEAL installation of the relevant version and link against the SealKernel, PluginManager and SealBase libraries.

A CORAL release x.y.z is installed under the afs directory

/afs/cern.ch/sw/lcg/app/releases/CORAL/CORAL_X_Y_Z
The INCLUDE path should contain the directory
/afs/cern.ch/sw/lcg/app/releases/CORAL/CORAL_X_Y_Z/include
and the libraries for a platform (operating system / compiler / compiler flag) PLATFORM under
/afs/cern.ch/sw/lcg/app/releases/CORAL/CORAL_X_Y_Z/PLATFORM/lib

This means that for a linux plaform the compile/link statement of a simple CORAL application should be something like the following:
g++ -o MyCoralApplication MyCoralApplication.cpp \
     -D_GNU_SOURCE -DGNU_SOURCE -fPIC -pthread -pipe -ansi -pedantic-errors \
     -I/afs/cern.ch/sw/lcg/app/releases/CORAL/CORAL_X_Y_Z/include \
     -I/afs/cern.ch/sw/lcg/app/releases/SEAL/SEAL_Xx_Yy_Zz/include \
     -I/afs/cern.ch/sw/lcg/app/releases/SEAL/SEAL_Xx_Yy_Zz/PLATFORM/include \
     -L/afs/cern.ch/sw/lcg/app/releases/CORAL/CORAL_X_Y_Z/PLATFORM/lib \
     -llcg_coral_RelationalAccess -llcg_coral_CoralBase \
     -L/afs/cern.ch/sw/lcg/app/releases/SEAL/SEAL_Xx_Yy_Zz/PLATFORM/lib \
     -llcg_SealKernel -llcg_PluginManager -llcg_SealBase \
     -luuid -lpcre -lnsl -lcrypt -ldl -Wl,-E

4.2. Setting up the run-time environment

In order to run an application which is using CORAL one should include in the LD_LIBRARY_PATH environment variable (the PATH variable for win32 platforms) the library directories of CORAL, SEAL, and of the external packages used either directly (eg. uuid) or at run-time when a plugin is loaded. For example the XML-based implementation plugins will require the shared libraries for XercesC, the Oracle plugin will require the Oracle instant client libraries, etc.

Moreover, in order for the system to know which plugins are available the SEAL_PLUGINS path environment variable should include the directories

/afs/cern.ch/sw/lcg/app/releases/CORAL/CORAL_X_Y_Z/PLATFORM/lib/modules
and
/afs/cern.ch/sw/lcg/app/releases/SEAL/SEAL_Xx_Yy_Zz/PLATFORM/lib/modules

For the development of new plugin implementations of the CORAL interfaces, one should append to the above environment variables the directories where the corresponding libraries and plugin definitions reside.

4.3. External dependencies and supported platforms

The currently supported platforms are:

  • slc3_ia32_gcc323_dbg
  • slc4_ia32_gcc34
  • slc4_ia32_gcc34_dbg
  • slc4_amd64_gcc34
  • slc4_amd64_gcc34_dbg
  • osx_ia32
  • osx_ia32_dbg
  • win32_vc71_dbg

The external dependencies are listed in the following table:

External packageVersionRequired byPlatform
SEAL1.9.3AllAll
Boost1.33.1SEALAll
uuid1.38SEALAll
pcre4.4SEALAll
rx1.5SEALwin32_vc71_dbg
XercesC2.7.0XMLLookupService, XMLAuthenticationServiceAll
Oracle (OCI)10.2.0.3-fullOracleAccessAll
SQLite3.4.0SQLiteAccessAll
MySQL5.0.18MySQLAccessAll
frontier_client2.7.4FrontierAccessAll but win32
expat1.95.8frontier_clientAll but win32
lfc1.6.5LFCLookupService, LFCReplicaServiceslc3_ia32_gcc323(_dbg)
vdt1.2.3_globusrls215blfcslc3_ia32_gcc323(_dbg)

4.4. Useful guidelines and programming tips

Here is a list of tips which address the most frequently encountered problems.

  • USE BIND VARIABLES WHEREVER YOU CAN.

    CORAL takes care for it automatically wherever this is possible, but whenever queries are issued it is up to the user to ensure that this is done.

  • Try to always define the output specification in a query. Since there is not a 1-1 mapping between C++ and SQL types one should not rely on the output C++ type as it is guessed by the backend.
  • Note that whenever specifying the type of a column variable in a table, the call is a hint to the relevant backend. The reasons are the same as for above.
  • Keep a pointer to an IConnectionProxy in your classes, and release it as soon as you are done with the underlying database.
  • Avoid "injecting" SQL through the CORAL API, since it may result to technology-specific code.