|Oracle® C++ Call Interface Programmer's Guide,
11g Release 2 (11.2)
Part Number E10764-01
This chapter provides an overview of installation and upgrading for Oracle C++ Call Interface (OCCI).
This chapter contains these topics:
OCCI is installed as part of the Oracle Database. To determine additional configuration requirements, you should refer to the Oracle Database Installation Guide and the Oracle Database Client Installation Guide that is specific to your platform.
To use the new features available in this release, you must recompile and relink all OCCI applications, including classes generated through the Object Type Translator Utility, when upgrading from an earlier Oracle Client release.
When an application uses several separate code paths with different server versions or client patchsets, you can verify these options both during compilation and at run time.
The OCCI header files define
OCCI_MINOR_VERSION macros. Example 2-1 illustrates one way to use these macros:
The Instant Client feature makes it extremely easy and fast to deploy OCCI based customer application by eliminating the need for
ORACLE_HOME. The storage space requirements are an additional benefit; Instant Client shared libraries occupy about one-fourth of the disk space required for a full client installation.
Installation involves copying only four files.
Storage space requirement for the client is minimal
No loss of functionality or performance exists for deployed applications
Simplified packaging with ISV applications
The OCCI Instant Client capability simplifies OCCI installation. Even though OCCI is independent of
ORACLE_HOME setting in the Instant Client mode, applications that rely on
ORACLE_HOME settings can continue operation by setting it to the appropriate value. The activation of the Instant Client mode is only dependent on the ability to load the Instant Client data shared library. In particular, this feature allows interoperability with Oracle applications that use
ORACLE_HOME for their data, but use a newer release of Oracle Client.
OCCI requires only four shared libraries (or dynamic link libraries, as they are called on some operating systems) to be loaded by the dynamic loader of the operating system. Oracle Database 11g Release 2 (11.2) library names are used; the number part of library names changes to remain consistent with future release numbers.
OCI Instant Client Data Shared Library (
libociei.so on Linux and UNIX and
oraociei11.dll on Windows); correct installation of this file determines if you are operating in Instant Client mode
Client Code Library (
libclntsh.so.11.1 on Linux and UNIX and
oci.dll on Windows)
Security Library (
libnnz11.so on Linux and UNIX and
orannzsbb11.dll on Windows)
OCCI Library (
libocci.so.11.1 on Linux and UNIX and
oraocci11.dll on Windows)
The Instant Client libraries are also available on the Oracle Technology Network (OTN) Web site at:
If these four libraries are accessible through the directory on the Operating System Library Path variable (
LD_LIBRARY_PATH on Linux and UNIX, and
PATH on Windows), then OCCI operates in the Instant Client mode. In this mode, there is no dependency on
ORACLE_HOME and none of the other code and data files provided in
ORACLE_HOME are needed by OCCI.
If you are installing Instant Client from the Oracle Technology Network,
Download and install the Instant Client libraries to an empty directory, such as
Set the operating system shared library path environment variable (
LD_LIBRARY_PATH on Linux and UNIX and
PATH on Windows) to the directory used in step 1,
Instant Client can also be downloaded as an SDK package. The SDK contains all necessary header files and a makefile for developing OCCI applications in an Instant Client environment. Once developed, these applications can be deployed in any client environment. The SDK has these additional features:
It contains C++ demonstration programs.
It includes libraries required to link applications on Windows, and a
Make.bat file is provided to build demos.
demo.mk is provided to build the demos for Linux and UNIX. The
instantclient_11_2 directory must be on the
LD_LIBRARY_PATH before linking the application. These programs require symbolic links for the Client Code Library and the OCCI library,
libocci.so respectively, in the
instantclient_11_2 directory. The demo Makefile,
demo.mk, generates these before the link step. These symbolic links can also be created in a shell script:
cd instantclient_11_2 ln -s libclntsh.so.11.1 libclntsh.so ln -s libocci.so.11.1 libocci.so
The SDK also contains the Object Type Translator (OTT) utility and its classes to generate the application header files.
If you performed a complete client installation by choosing the Admin option,
On Linux or UNIX platforms, the
libociei.so library can be copied from the
/instantclient directory. All the other libraries can be copied from the
/lib directory in a full Oracle installation.
On Windows, the
oraociei11.dll library can be copied from the
\instantclient directory. All other Windows libraries can be copied from the
\bin directory. To use the Microsoft ODBC and OLEDB driver,
ociw32.dll must also be copied from
If you did not install the database, you can install these libraries by choosing the Instant Client option from the Oracle Universal Installer. After completing these steps, you can begin running OCCI applications.
Install the Instant Client shared libraries to a directory such as
Set the operating system shared library path environment variable to the directory from step 1. For example, on Linux or UNIX, set the
instantclient_11_2. On Windows, set
PATH to locate the
You can also install Instant Client from the Instant Client CD. You must install Instant Client either in an empty directory or on a different system.
There should be only one set of Oracle libraries on the operating system Library Path variable; if you have several directories or copies of Instant Client libraries, only one directory should be on the operating system Library Path.
Similarly, if you also have an installation on an
ORACLE_HOME of the same system, do not place both the
/lib and Instant Client directory on the operating system Library Path, regardless of the order in which they appear on the Library Path. Only one of
/lib directory (for non-Instant Client operation) or Instant Client directory (for Instant Client operation) should be on the operating system Library Path variable.
The Instant Client feature is designed for running production applications. For development, use either the Instant Client SDK or a full installation to access OCCI header files, makefiles, demonstration programs, and so on.
This feature is not available on Windows platforms.
Because Instant Client is primarily a deployment feature, one of its design objectives is to reduce the number and size of necessary files. Therefore, Instant Client deployment does not include all files for patching shared libraries. You should use the
OPATCH utility on an
ORACLE_HOME-based full client to patch the Instant Client shared libraries. The
OPATCH utility stores the patching information of the
ORACLE_HOME installation in
libclntsh.so.11.1 for Linux and UNIX. This information can be retrieved using the
genezi utility is not installed on the system that deploys Instant Client, you can copy it from the
/bin directory of the
After applying the patch in an
ORACLE_HOME environment, copy the files listed in"Installing Instant Client" to the Instant Client directory. Instead of copying individual files, you can generate Instant Client
*.zip files, as described in "Regenerating the Data Shared Library and Zip Files". Then, instead of copying individual files, you can instead copy the zip files to the target system and unzip them.
This feature is not available on Windows platforms.
The Instant Client Data Shared Library,
libociei.so, can be regenerated in a Client Admin Install of
ORACLE_HOME. Executing Example 2-2 creates a new
libociei.so file based on current file in
ORACLE_HOME and place it in the
/rdbms/install/instantclient directory; the make target
This location of the regenerated data shared library,
libociei.so, is different from the original location of
All Oracle net naming methods that do not require use of
TNS_ADMIN to locate configuration files such as
sqlnet.ora work in the Instant Client mode.
connectString parameter in the createConnection() call can be specified in the following formats:
As an SQL Connect URL string, of the form:
As an Oracle Net keyword-value pair. For example:
(DESCRIPTION=(ADDRESS=(PROTOCOL=tcp) (HOST=myserver111) (PORT=5521)) (CONNECT_DATA=(SERVICE_NAME=bjava21)))
As a connection name that is resolved through Directory Naming when the site is configured for LDAP server discovery.
As an entry in the
TNS_ADMIN environment variable is not set, and
TNSNAMES entries such as
inst1 are used, then the
ORACLE_HOME variable must be set and the configuration files are expected to be in the
Naming methods that require
TNS_ADMIN to locate configuration files continue to work if the
TNS_ADMIN environment variable is set.
ORACLE_HOME variable in this case is only used for locating Oracle Net configuration files, and no other component of OCCI Client Code Library uses the value of
connectString parameter of createConnection() is supported by setting the environment variable (
TWO_TASK on Linux and UNIX, and
LOCAL on Windows) to one of the values described earlier.
See Also:Oracle Database Net Services Administrator's Guide for more information on the connect descriptor.
ORACLE_HOME environment variable no longer determines the location of Globalization Support, CORE, and error message files. An OCCI-only application should not require
ORACLE_HOME to be set. However, if it is set, it does not have an impact on OCCI's operation. OCCI always obtains its data from the Data Shared Library. If the Data Shared Library is not available, only then is
ORACLE_HOME used and a full client installation is assumed. When set,
ORACLE_HOME should be a valid operating system path name that identifies a directory.
ORA_NLS are ignored in the Instant Client mode.
In the Instant Client mode, if the
ORA_TZFILE variable is not set, then the larger, default,
.dat file (where
n is the version number of the file) from the Data Shared Library is used. If using the smaller
.dat file from the Data Shared Library, then set the
ORA_TZFILE environment variable to the name of the file without any absolute or relative path names, as shown in Example 2-3.
Example 2-3 How to set the ORA_TZFILE Environment Variable
On Linux and UNIX:
setenv ORA_TZFILE timezone_n.dat
set ORA_TZFILE timezone_n.dat
If OCCI is not operating in the Instant Client mode because the Data Shared Library is not available, the
ORA_TZFILE variable, if set, names a complete path name.
TNSNAMES entries are used, then
TNS_ADMIN directory must contain the
TNSNAMES configuration files. If
TNS_ADMIN is not set, the
/network/admin directory must contain Oracle Net Services configuration files.
Instant Client Light (English) further reduces installation space requirements of the client installation over Instant Client by another 63 MB. Specifically, the installation of the Instant Client Light (English) shared library,
libociicus.so on Linux and UNIX and
oraociicus11.dll for Windows, occupies 4 MB on UNIX platforms, when the full Instant Client shared library, libociei.so, occupies 67 MB of disk space.
Instant Client Light (English), as the name implies, is geared toward applications that require English-only error messages and use either
WE8DEC, or a Unicode characterset. Instant Client Light (English) also has no restrictions on the
TERRITORY field of the
NLS_LANG setting. As a result, applications that meet these characterset and territory criteria can significantly reduce its footprint if they operate in the Instant Client Light (English) environment.
Single-byte character sets include
Unicode character sets include
Instant Client Light (English) returns an error message if the application attempts to use a character set or a national character set not listed here, either on the client or on the database. The possible error messages, listed here, are only available in English:
ORA-12734 Instant Client Light: unsupported client national character set (NLS_LANG value set)
ORA-12735 Instant Client Light: unsupported client character set (NLS_LANG value set)
ORA-12736 Instant Client Light: unsupported server national character set (NLS_LANG value set)
ORA-12737 Instant Client Light: unsupported server character set (NLS_LANG value set)
NLS_LANG parameters, use the following:
territory is any valid Territory that can be specified through
charset is a character set listed in this section.
See Also:Oracle Database Globalization Support Guide for more information about NLS settings.
To determine whether to operate in the Instant Client mode, OCCI applications look for the Data Shared Library on the
LD_LIBRARY_PATH for Linux and UNIX and
PATH on Windows. If this library is not found, OCCI attempts to load the Instant Client Light (English) Data Shared Library,
libociicus.so for Linux and UNIX and
oraociicus11.dll on Windows. If neither is found, a full
ORACLE_HOME installation is assumed.
Note that all Instant Client and Instant Client Light (English) files should always be copied or installed into an empty directory to ensure that there are no incompatible binaries in the final installation
When installing Instant Client Light (English) from Oracle Technology Network (OTN), download and unzip the
basiclite.zip package instead of the usual
basic.zip package. You must ensure that the
instantclient_11_2 directory is empty before unzipping the libraries. The downloadable package is at the following URL on OTN:
Instead of copying the Instant Client Data Shared Library from the
/instantclient directory, use the Instant Client Light (English) Data Shared Library,
libociicus.so for Linux and UNIX and oraociicus11.dlll for Windows, from the
/instantclient/light directory. In other words, the Instant Client directory on the
LD_LIBRARY_PATH for Linux and UNIX and
PATH for Windows should contain the smaller Instant Client Light (English) Data Shared Libraries.
If the Instant Client option is selected from the Oracle Universal Installer (OUI), the full Instant Client is installed by default, but the libraries for Instant Client Light (English) are also installed. To operate in Instant Client Light (English) mode, the Instant Client Light (English) Data Shared Library must replace the Instant Client library. Therefore, you must place libociicus.so on the
LD_LIBRARY_PATH for Linux and UNIX, and
oraociicus11.dll on the
PATH for Windows. This design ensures that the Instant Client Light (English) is not enabled by default.
The Instant Client Light (English) Data Shared Library is initially placed in the
/instantclient/light directory. You must move it to the base directory of the installation,
/instantclient, and remove the Instant Client Data Shared Library in that directory.
Example 2-4 Installing Instant Client Light (English) through Oracle Universal Installer
If the OUI has installed the Instant Client in
my_oraic_11_1 directory on the
LD_LIBRARY_PATH, then the following commands would ensure operation in the Instant Client Light (English) mode. Note that to avoid use of incompatible binary files, all Instant Client files should be copied and installed in an empty directory.
cd my_oraic_11_1 rm libociei.so mv light/libociicus.so .
The Oracle Database 11gR1 release includes OCCI libraries for developing applications with Microsoft Visual C++ version 8.0 (.NET 2005) Microsoft Visual C++ version 7.1 (.NET 2003). Microsoft Visual C++ version 7.0 is no longer supported.
Microsoft Visual C++ version 7.1 libraries are installed in the following default locations:
Copies of these two files are also installed under the directory:
The Microsoft Visual C++ 8.0-specific version of the libraries is installed under:
Applications should link with the appropriate OCCI library. You must ensure that the corresponding DLL is located in the Windows system PATH.
Applications that link to
MSVCRTD.DLL, a debug version of Microsoft C-Runtime,
/MDd compiler flag, should link with these specific OCCI libraries:
All Instant Client packages contain the version of the OCCI DLL that is compatible with Microsoft Visual C++ version 7.1.