20 OCI Instant Client

Overview

The Instant Client feature makes it extremely easy to deploy OCI, OCCI, ODBC, and JDBC-OCI based customer applications by eliminating the need for an ORACLE_HOME. The storage space requirement of a JDBC OCI application running in Instant Client mode is significantly reduced compared to the same application running in a full client side installation. The Instant Client shared libraries only occupy about one-fourth the disk space of a full client installation.

Table 20-1 shows the Oracle client-side files required to deploy a JDBC OCI application:

Release 10.1 library names are used in the table. The number part of library names will change in future releases to agree with the release.

Benefits of Instant Client

The benefits of Instant Client are:

• Installation involves copying a small number of files.

• The Oracle client-side number of required files and the total disk storage are significantly reduced.

• There is no loss of functionality or performance for applications deployed in Instant Client mode.

• It is simple for independent software vendors to package applications.

JDBC OCI Instant Client Installation Process

The Instant Client libraries can be installed by choosing the Instant Client option from the Oracle Universal Installer. The Instant Client libraries can also be downloaded from the Oracle Technology Network (otn.oracle.com) Web site. The installation process is as simple as:

1. Downloading and installing the Instant Client shared libraries and Oracle JDBC class libraries to a directory such as instantclient.

2. Setting the OS shared library path environment variable to the directory from step 1. For example, on UNIX, set the LD_LIBRARY_PATH to instantclient. On Windows, set PATH to locate the instantclient directory.

3. Adding the full pathnames of the JDBC class libraries to the CLASSPATH environment variable; see "Check the Environment Variables" .

After completing the above steps you are ready to run the JDBC OCI application.

The JDBC OCI application operates in Instant Client mode when the OCI and JDBC shared libraries are accessible through the OS Library Path variable. 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 JDBC OCI (except for the tnsnames.ora file described later).

If you have done a complete client installation (by choosing the Admin option), the Instant Client shared libraries are also installed. The location of the Instant Client shared libraries and JDBC class libraries in a full client installation is:

On UNIX:

• libociei.so library is in $ORACLE_HOME/instantclient

• libclnstsh.so.10.1, libocijdbc10.so, and libnnz10.so are in $ORACLE_HOME/lib

• The JDBC class libraries are in $ORACLE_HOME/jdbc/lib

On Windows:

• oraociei10.dll library is in ORACLE_HOME\instantclient

• oci.dll, oraocijdbc10.dll, and orannzsbb10.dll are in ORACLE_HOME\bin

• The JDBC class libraries are in ORACLE_HOME\jdbc\lib

By copying the above files to a different directory, setting the OS shared library path to locate this directory, and adding the pathnames of the JDBC class libraries to the CLASSPATH, you can enable running the JDBC OCI application in Instant Client mode.

When to Use Instant Client

Instant Client is a deployment feature and should be used for running production applications. For development, a full installation is necessary to access demonstration programs and so on. In general, all JDBC OCI functionality is available to an application being run in the Instant Client mode, except that the Instant Client mode is for client-side operation only. Therefore, server-side external procedures cannot operate in the Instant Client mode.

Patching Instant Client Shared Libraries

Because Instant Client is a deployment feature, the emphasis has been on reducing the number and size of files (client footprint) required to run a JDBC OCI application. Hence all files needed to patch Instant Client shared libraries are not available in an Instant Client deployment. An ORACLE_HOME based full client installation is needed to patch the Instant Client shared libraries. The opatch utility will take care of patching the Instant Client shared libraries.

After patching the Instant Client shared libraries Oracle recommends generating the patch inventory information by executing the following command from the ORACLE_HOME/OPatch directory:

opatch lsinventory > opatchinv.out

The opatchinv.out file should be copied along with the patched Instant Client libraries to the deployment directory. The information in opatchinv.out will indicate all the patches that have been applied.

The opatch inventory information for Instant Client libraries is not needed on the Windows platform, so this step can be skipped on Windows.

Regeneration of Data Shared Library

The OCI Instant Client Data Shared Library (libociei.so) can be regenerated by performing the following steps in an Administrator Install of ORACLE_HOME:

cd $ORACLE_HOME/rdbms/lib
make -f ins_rdbms.mk ilibociei

A new version of libociei.so based on the current files in the ORACLE_HOME is then placed in the ORACLE_HOME/instantclient directory.

Regeneration of data shared library is not available on Windows platforms.

Database Connection Names for OCI 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. In particular, the connect string can be specified in the following formats:

• A Thin-style connect string of the form:

  host:port:service_name
  

  such as:

  url="jdbc:oracle:oci:@//example.com:5521:bjava21"
  
  

• A SQL Connect URL string of the form:

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

  such as:

  url="jdbc:oracle:oci:@//example.com:5521/bjava21
  
  

• As an Oracle Net keyword-value pair. For example:

  url="jdbc:oracle:oci:@(DESCRIPTION=(ADDRESS=(PROTOCOL=tcp) 
    (HOST=dlsun242) (PORT=5521))
    (CONNECT_DATA=(SERVICE_NAME=bjava21)))"
  
  

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

If the TNS_ADMIN environment variable is not set, and TNSNAMES entries such as inst1, and so on, 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.

Please note that the ORACLE_HOME variable in this case is only used for locating Oracle Net configuration files, and no other component of Client Code Library (OCI, NLS, and so on) uses the value of ORACLE_HOME.

The bequeath adapter or the empty connect strings are not supported. However, an alternate way to use the empty connect string is to set the TWO_TASK environment variable on UNIX, or the LOCAL variable on Windows, to either a tnsnames.ora entry or an Oracle Net keyword-value pair. If TWO_TASK or LOCAL is set to a tnsnames.ora entry, then the tnsnames.ora file must be able to be loaded by TNS_ADMIN or ORACLE_HOME setting.

Environment Variables for OCI Instant Client

The ORACLE_HOME environment variable no longer determines the location of NLS, CORE, and error message files. An OCI-only application should not require ORACLE_HOME to be set. However, if it is set, it does not have an impact on the OCI driver's operation. OCI 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. Even though ORACLE_HOME is not required to be set, if it is set, then it must be set to a valid operating system path name that identifies a directory.

Environment variables ORA_NLS33 and ORA_NLSPROFILES33 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 UNIX:

setenv ORA_TZFILE timezlrg.dat

On Windows:

set ORA_TZFILE timezlrg.dat

If the driver is not operating in the Instant Client mode (because the Data Shared Library is not available), then ORA_TZFILE variable, if set, names a complete path name as it does in previous Oracle releases.

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