2 Installation and Upgrading

Determining the Oracle Client Version During Compilation

The OCCI header files define OCCI_MAJOR_VERSION and OCCI_MINOR_VERSION macros. Example 2-1 illustrates one way to use these macros:

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

Determining the Oracle Client and Server Versions at Runtime

During runtime, you can check both the client and server versions of the current Connection by using the getClientVersion(), getServerVersion(), and getServerVersionUString() methods.

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 Oracle Client.

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 11g Release 1 (11.1) 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 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)

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.

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.11.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 three 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/light
cd $ORACLE_HOME/rdbms/lib
make -f ins_rdbms.mk ilibociei

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.

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 oraociicus11.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.

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

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