2 Installation and Upgrading

This chapter provides an overview of installation and upgrading for Oracle C++ Call Interface (OCCI).

This chapter contains these topics:

Installing Oracle C++ Call Interface
Upgrading Considerations
Determining Client and Server Versions
Instant Client
Instant Client Light (English)

Installing Oracle C++ Call Interface

The Oracle C++ Call Interface 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.

Upgrading Considerations

Because of compiler restrictions due to virtual table ordering, you must recompile and relink all Oracle C++ Call Interface applications when upgrading for an earlier version of an Oracle Database. This applies both for minor and major releases.

Determining Client and Server Versions

When an application uses several separate codepaths that utilize different server versions or client patchsets, it can verify these options by checking the client and server versions of the current Connection. Use the getClientVersion(), getServerVersion(), and getServerVersionUString()

To determine the client version, the OCCI header files also define OCCI_MAJOR_VERSION and OCCI_MINOR_VERSION macros. illustrates one way to use these macros:

Example 2-1 How to Determine the Major Client Version and set Performance Features

#if (OCCI_MAJOR_VERSION > 9)
     env->setCacheSortedFlush(true); 
       // take the benefit of performance if available
#endif

Instant Client

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.

Benefits of Instant Client

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 OCCI. Other components such as shared libraries for network protocols, or security options, must be installed separately.

Installing Instant 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 10g Release 2 (10.2) library names are used; the number part of library names will change to remain consistent with future release numbers.

OCI Instant Client Data Shared Library (libociei.so on Linux and UNIX and oraociei10.dll on Windows); correct installation of this file determines if you are operating in Instant Client mode
Client Code Library (libclntsh.so.10.1 on Linux and UNIX and oci.dll on Windows)
Security Library (libnnz10.so on Linux and UNIX and orannzsbb10.dll on Windows)
OCCI Library (libocci.so.10.1 on Linux and UNIX and oraocci10.dll on Windows)

Oracle Technology Network

The Instant Client libraries are also available on the Oracle Technology Network (OTN) website at:

http://www.oracle.com/technology/tech/oci/instantclient/

If these four libraries are accessible through the directory on the OS 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 instantclient_10_2.
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, instantclient_10_2.

Instant Client SDK

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.
The Makefile demo.mk is provided to build the demos for Linux and UNIX. The instantclient_10_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, libclntsh.so and libocci.sh respectively, in the instantclient_10_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_10_2
ln -s libclntsh.so.10.1 libclntsh.so
ln -s libocci.so.10.1 libocci.so
```
The SDK also contains the Object Type Translator (OTT) utility and its classes to generate the application header files.

Complete Client Installation

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 $ORACLE_HOME/instantclient directory. All the other libraries can be copied from the $ORACLE_HOME/lib directory in a full Oracle installation.
On Windows, the oraociei10.dll library can be copied from the ORACLE_HOME\instantclient directory. All other Windows libraries can be copied from the ORACLE_HOME\bin directory. To use the Microsoft ODBC and OLEDB driver, ociw32.dll must also be copied from ORACLE_HOME\bin.

Oracle Universal Installer

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 instantclient_10_2.
Set the operating system shared library path environment variable to the directory from step 1. For example, on Linux or UNIX, set the LD_LIBRARY_PATH to instantclient_10_2. On Windows, set PATH to locate the instantclient_10_2 directory.

Instant Client CD

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 machine, do not place both the ORACLE_HOME/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 ORACLE_HOME/lib directory (for non-Instant Client operation) or Instant Client directory (for Instant Client operation) should be on the operating system Library Path variable.

Using Instant Client

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. In general, all OCCI functionality is available to an application being run in the Instant Client mode, except for server-side external procedures.

Patching Instant Client Shared Libraries on Unix

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.10.1 for Linux and UNIX. This information can be retrieved using the genezi utility:

genezi -v

If the genezi utility is not installed on the machine that deploys Instant Client, you can copy it from the ORACLE_HOME/bin directory of the ORACLE_HOME machine.

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 machine and unzip them.

Regenerating the Data Shared Library and Zip Files

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 the following two lines will create a new libociei.so file based on current file in ORACLE_HOME and place it in the ORACLE_HOME/rdbms/install/instantclient directory; the make target ilibociei will generate libociei.so:

mkdir -p $ORACLE_HOME/rdbms/install/instantclient/lightcd $ORACLE_HOME/rdbms/lib
make -f ins_rdbms.mk ilibociei

Note:

This location of the regenerated data shared library, libociei.so, is different from the original location of ORACLE_HOME/instantclient
This script will also create a directory for Instant Client Light (English)

Database Connection Names for Instant Client

All Oracle net naming methods that do not require use of ORACLE_HOME or TNS_ADMIN to locate configuration files such as tnsnames.ora or sqlnet.ora work in the Instant Client mode.

The connectString parameter in the createConnection() call can be specified in the following formats:

As an SQL Connect URL string, of the form:

//host:[port][/service name]

such as:

//myserver111:5521/bjava21

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 tnsnames.ora file.

If 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 $ORACLE_HOME/network/admin directory.

Naming methods that require TNS_ADMIN to locate configuration files continue to work if the TNS_ADMIN environment variable is set.

The 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 ORACLE_HOME.

The empty 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 four values described earlier.

Environment Variables for OCCI Instant Client

The 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 will always obtain 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.

Environment variables ORA_NLS33, ORA_NLS32, and ORA_NLS are ignored in the Instant Client mode.

In the Instant Client mode, if the ORA_TZFILE variable is not set, then the smaller, default, timezone.dat file from the Data Shared Library is used. If the larger timezlrg.dat file is to be used 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. That is, on Linux and UNIX:

setenv ORA_TZFILE timezlrg.dat

On Windows:

set ORA_TZFILE timezlrg.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.

If TNSNAMES entries are used, then TNS_ADMIN directory must contain the TNSNAMES configuration files. If TNS_ADMIN is not set, the ORACLE_HOME/network/admin directory must contain Oracle Net Services configuration files.

Instant Client Light (English)

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 oraociicus10.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 US7ASCII, WE8DEC, or one of the Unicode charactersets. 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.

Globalization Settings for Instant Client Light (English)

Instant Client Light (English) supports the following character sets:

Single-byte character sets include US7ASCII, WE8DEC, WE8MSWIN1252, and WE8ISO8859P1.
Unicode character sets include UTF8, AL16UTF16, and AL32UTF8.

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)

When setting NLS_LANG parameters, use the following:

American_territory.charset

where territory is any valid Territory that can be specified through NLS_LANG, and charset is one of the character sets already listed in this section.

Using Instant Client Light (English)

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 oraociicus10.dll on Windows. If neither is found, a full ORACLE_HOME installation is assumed.

Installing Instant Client Light (English)

There are three ways to install Instant Client Light (English): from Oracle Technology Network Download, through Client Admin Install, and through Oracle Universal Installer.

Note:

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.

Oracle Technology Network Download

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_10_2 directory is empty before unzipping the libraries. The downloadable package is at the following URL on OTN:

http://www.oracle.com/technology/tech/oci/instantclient/

Client Admin Install

Instead of copying the Instant Client Data Shared Library from the ORACLE_HOME/instantclient directory, use the Instant Client Light (English) Data Shared Library, libociicus.so for Linux and UNIX and oraociicus10.dlll for Windows, from the ORACLE_HOME/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.

Oracle Universal Installer

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 oraociicus10.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 ORACLE_HOME/instantclient/light directory. You must move it to the base directory of the installation, ORACLE_HOME/instantclient, and remove the Instant Client Data Shared Library already in that directory.

Example 2-2 Installing Instant Client Light (English) through Oracle Universal Installer

If the OUI has installed the Instant Client in my_oraic_10_2 directory on the LD_LIBRARY_PATH, then the following commands would ensure operation in the Instant Client Light (English) mode:

cd my_oraic_10_2
rm libociei.so
mv light/libociicus.so .

Note:

To avoid use of incompatible binary files, all Instant Client files should be copied and installed in an empty directory.