Getting Started

This chapter guides you through the procedures required to install and configure the Oracle Database ODBC driver.

The Oracle Database ODBC driver enables applications to connect to Oracle Database from a Windows client as well as a UNIX client that use Microsoft Open Database Connectivity (ODBC) API to read from and write to Oracle Databases.

The Oracle Database ODBC driver distribution kit consists of Dynamic Link Libraries and shared libraries (for UNIX platforms), help file (on Windows and UNIX platforms), a copy of the license, and this product description. To use an ODBC-enabled application, the following software is required in addition to the Oracle Database ODBC driver:

See Also: The OCI documentation in Oracle Call Interface Programmer’s Guide for more information about the OCI client and server software

Topics:

Summary of Steps

The summary of steps for installing and configuring the Oracle Database ODBC driver is as follows.

Linux and UNIX

  1. Confirm that the system requirements have been met for the installation.

  2. Download and install the Oracle Instant Client Basic or Light package.

  3. Download and install the unixODBC Driver Manager.

  4. Download and extract the Instant Client ODBC package into the Instant Client directory.

  5. Configure the path for the driver’s shared library and other environment variables.

  6. Configure the Oracle net services (TNS service name) using the Oracle Net Configuration Assistant (NETCA) tool.

  7. Run odbc_update_ini.sh from the Instant Client directory to configure the data source.

  8. Set globalization variables, if required for your locale.

Windows

  1. Confirm that the system requirements have been met for the installation.

  2. Download and install the Oracle Instant Client Basic or Light package.

  3. Download and extract the Instant Client ODBC package into the Instant Client directory.

  4. Run odbc_install.exe from the Instant Client directory.

  5. Configure the path for the driver’s shared library and other environment variables.

  6. Configure the Oracle net services (TNS service name) using the Oracle NETCA tool.

  7. Run ODBC Data Source Administrator to configure the data source.

Installation

This section guides you through the procedures required to install the Oracle Database ODBC driver.

Oracle’s Instant Client ODBC software is a standalone package that offers the full functionality of the Oracle Database ODBC driver (except the Oracle service for Microsoft Transaction Server) with a simple installation procedure.

The ODBC driver has Oracle’s standard client-server version interoperability (see Support Doc ID 207303.1). For example, Instant Client ODBC 19c can connect to Oracle Database 11.2, or later.

Topics:

System Requirements

Before installing the ODBC driver, verify that the hardware, the target operating system and server versions are compatible for use with the ODBC driver.

Topics:

Software Required

The Oracle Database ODBC driver was certified against the currently supported Windows and UNIX operating system versions, the most current release of Oracle Net Client and Oracle Universal Installer shipping with Oracle Database.

The Oracle Database ODBC driver was certified against the following versions of software:

Server Software Requirements

Oracle Database Server 12.2, or later, is the server software required to support ODBC-enabled applications that use the Oracle Database ODBC driver.

Hardware Required

The requirements for the Oracle Database ODBC driver system configuration for Windows and UNIX platforms.

The Oracle Database ODBC driver requires a system configuration that the certified Windows platforms as mentioned in Software Required supports, and on a few UNIX platforms, the hardware requirements are as documented in the Oracle Databse ODBC driver for UNIX Platforms Readme.

Installing Oracle Instant Client ODBC (Linux and UNIX)

  1. Install the unixODBC Driver Manager from unixODBC.org. To install the ODBC Driver Manager, first download .tar file from http://www.unixodbc.org/.

    See Also: Recommended unixODBC Driver Manager Versions for Linux and UNIX for more information about the recommended unixODBC Driver Manager versions

  2. Navigate to package from OTN to download Oracle Instant Client Basic or Basic Lite.

  3. Download the Instant Client ODBC package.

  4. Unzip the Instant Client package to the desired location, for example: /opt/oracle/instantclient_xx_yy, or use yum to install the RPM packages on Linux.

    See Also: Installing Oracle Instant Client for more information about installing Oracle Instant Client

  5. Unzip the ODBC package into the Instant Client folder, for example: /opt/oracle/instantclient_xx_yy, which is the same directory as the Basic or Basic Light package. Alternatively, if using the RPM package on Linux, install it with yum.

    • After the installation, set the environment variables, configure net services, and run odbc_update_ini.sh (from the Instant Client directory) to configure data sources.

      See Also: Configuration for more post-installation configuration steps.

    • Set any Oracle globalization variables required for your locale. For example, on Linux, you could set export NLS_LANG=JAPANESE_JAPAN.JA16EUC to work in the JA16EUC character in Japanese.

    See Also: Oracle Database Globalization Support Guide for more information.

Recommended unixODBC Driver Manager Versions for Linux and UNIX

For Instant Client 23ai:

Platform unixODBC Driver Manager Version
Linux 32bit, 64bit 2.3.14
Solaris SPARC64 32bit, 64bit 2.3.14
Solaris 32bit, 64bit 2.3.14
AIX 5L 32bit, 64bit 2.3.14
HP IA64 32bit, 64bit 2.3.14
z/Linux 31bit, 64bit 2.3.14

For Instant Client 21c:

Platform unixODBC Driver Manager Version
Linux 32bit, 64bit 2.3.4
Solaris SPARC64 32bit, 64bit 2.3.4
Solaris 32bit, 64bit 2.3.4
AIX 5L 32bit, 64bit 2.3.4
HP IA64 32bit, 64bit 2.3.4
z/Linux 31bit, 64bit 2.3.4

For Instant Client 18c and 19c:

Platform unixODBC Driver Manager Version
Linux 32bit, 64bit 2.3.4
Solaris SPARC64 32bit, 64bit 2.3.4
Solaris 32bit, 64bit 2.3.4
AIX 5L 32bit, 64bit 2.3.4
HP IA64 32bit, 64bit 2.3.4
z/Linux 31bit, 64bit 2.3.4

For Instant Client 12.1 and 12.2

Platform unixODBC Driver Manager Version
Linux 32bit, 64bit 2.3.4
Solaris SPARC64 32bit, 64bit 2.3.4
Solaris 32bit, 64bit 2.3.4
AIX 5L 32bit, 64bit 2.3.4
HP IA64 32bit, 64bit 2.3.4
z/Linux 31bit, 64bit 2.3.4

Installing Oracle Instant Client ODBC (Windows)

  1. Navigate to https://www.oracle.com/database/technologies/instant-client/microsoft-windows-32-downloads.html or https://www.oracle.com/database/technologies/instant-client/winx64-64-downloads.html

  2. Download and install the Instant Client Basic or Basic Light package.

  3. Download the Instant Client ODBC package.

  4. Unzip the Instant Client folder (instantclient_xx_yy) to the desired location. For example: C:\Users\app.

  5. Unzip the ODBC package and put the contents of the zip file: instantclient_xx_yy into the Instant Client folder (in the same directory as your Instant Client Basic or Basic Light package).

  6. Run odbc_install.exe from the Instant Client directory.

    This registers the ODBC driver with the ODBC Data Sources GUI.

  7. To install with Japanese language support, execute the command odbc_install.exe JA.

    After the installation, set the environment variables, configure net services, and configure the data sources.

    See Also: Configuration for more post-installation configuration steps.

Content of the Oracle Instant Client ODBC Package

Description Linux and UNIX Windows
Oracle Database ODBC driver shared library libsqora.so.XX.Y. For example libsqora.so.23.1 sqora32.dll
Installation file odbc_update_ini.sh odbc_install.exe, odbc_uninstall.exe
Oracle Database ODBC driver configuration dialog box (GUI) Not available sqoras32.dll, sqresus.dll, sqresja.dll
Help System help/ help/

Files Created by the Installation

The following table describes the files that are installed by the Oracle Database ODBC driver kit.

Table 1 Files Installed by the Oracle Database ODBC

Description File Name for Windows Installation File Name for UNIX Installation
Oracle ODBC Database Access DLL sqora32.dll libsqora.so.nn.n (where nn.n reflects a version number; for example, libsqora.so.23.1)
Oracle Database ODBC driver Setup DLL sqoras32.dll None
Oracle ODBC Resource DLL sqresus.dll None
Oracle ODBC Resource DLL for Japanese sqresja.dll None
Oracle Database ODBC driver message file oraodbcus.msb oraodbcus.msb
Oracle Database ODBC driver message file for Japanese oraodbcja.msb oraodbcja.msb
Oracle Database ODBC driver release notes Oracle AI Database ODBC Driver Release Notes Oracle AI Database ODBC Driver Release Notes
Oracle Database ODBC driver Instant Client Release Notes ODBC_IC_Readme_Win.html ODBC_IC_Readme_Unix.html
Oracle Database ODBC driver help file sqora.htm sqora.htm
Oracle Database ODBC driver help file for Japanese sqora.htm sqora.htm
Oracle Database ODBC driver Instant Client install script odbc_install.exe odbc_update_ini.sh
Oracle Database ODBC driver Instant Client uninstall script odbc_uninstall.exe None

Microsoft Driver Manager and Administrator Files

See the Microsoft ODBC 3.52 Software Development Kit and Programmer’s Reference for the list of files that are installed with Microsoft’s ODBC 3.52 Components.

The Microsoft ODBC components are packages in the Microsoft Data Access Component (MDAC) kit. The Oracle Database ODBC driver on Windows has been tested using MDAC version 2.8.

unixODBC Driver Manager and Administrator Files

See the unixODBC readme and INSTALL files for the list of files that are installed with unixODBC Driver Manager.

See Also:

Configuration

This section guides you through the procedures required to configure the Oracle Database ODBC driver.

Post installation, you must set environment variables for ODBC applications, configure network database services, and configure the data sources on Windows and UNIX platforms.

Use the Microsoft ODBC Administrator to configure your Oracle Database ODBC driver data sources on Windows. For more information, see the information about configuring the data source in Configuring the Data Source.

To configure the Oracle Database ODBC driver data source on a UNIX Client, see Configuration for UNIX Platforms.

Topics:

Environment Setup for ODBC Applications

An ODBC application must load the Oracle Instant Client ODBC driver’s shared library file to connect to Oracle Database. On Linux/Unix, the directory path of the shared library file libsqora.so.XX.Y (for example libsqora.so.19.1) should be set in the LD_LIBRARY_PATH environment variable, or in a platform equivalent. It can also be configured in /etc/ld.so.conf. On Windows, the directory path of the shared library file should be set in the PATH environment variable.

See Also:

Configuring Oracle Net Services

Before configuring the data source, you must configure network database services to ensure that there is an entry for each Transparent Network Substrate (TNS) Service Name. To do this, use the Oracle Net Configuration Assistant (NETCA) tool.

TNS service name is the location of the Oracle database from which the ODBC driver retrieves data.

Using NETCA, you can create an entry in the tnsnames.ora file for each TNS Service Name.

Note: NETCA is installed when you install Oracle Net Services.

See Also: Using Oracle Net Configuration Assistant to Configure Network Components in Oracle Database Net Services Administrator’s Guide for more information about using the NETCA tool.

Configuration for UNIX Platforms

Complete these post-installation configuration tasks for the Oracle Database ODBC driver on UNIX platforms.

  1. Run install-home/odbc/utl/odbc_update_ini.sh to configure the Oracle Database ODBC driver on UNIX.

    The utility odbc_update_ini.sh takes four command-line arguments:

    • arg-1: Complete path where unixODBC DM has been installed.

    • arg-2: Complete path of driver install location (optional); if this argument is not passed, the driver path is set to the directory from where the utility is run.

    • arg-3: Driver name (optional); if this argument is not passed, the driver name is set to the downloaded version.

    • arg-4: Data Source Name or DSN (optional); if no value is passed, the DSN is set to the downloaded version.

    See Also: Usage for detailed information about how to use odbc_update_ini.sh.

  2. Update and verify values of environment variables such as: PATH, LD_LIBRARY_PATH, LIBPATH, and TNS_ADMIN.

Usage

odbc_update_ini.sh <ODBCDM_Home> [<Install_Location> <Driver_Name> <DSN> <ODBCINI>]

Table 2 Parameter

Parameter Required/Optional Description
ODBCDM_Home Required unixODBC Driver Manager home directory path.
Install_Location Optional Oracle Instant Client directory path. The default path is the current directory.
Driver_Name Optional Driver name to identify the Oracle Database ODBC driver residing in current Oracle Instant Client home. The default name is like “Oracle 23ai ODBC driver.”
DSN Optional Sets ODBC Data Source Name (DSN). The default name is “OracleODBC-23ai.”
ODBCINI Optional Directory path of the .odbc.ini file. The default path is the user’s home directory, for example ~/.odbc.ini.

Configuration for Windows

Complete these post-installation configuration tasks for the Oracle Database ODBC driver on Windows.

Topics:

Configuring the Data Source

Note: The following configuration steps are for Windows users. Unix users must use the odbc_update_ini.sh file to create a Data Source Name (DSN).

After installing the Oracle Database ODBC driver and Configuring Oracle Net Services, and before using the Oracle Database ODBC driver, you must configure the data source.

Before an application can communicate with the data source, you must provide configuration information. The configuration information informs the Oracle Database ODBC driver as to which information you want to access.

The data source consists of the data that you want to access, its associated operating system, database management system, and network platform used to access the database management system. The data source for requests submitted by the Oracle Database ODBC driver is an Oracle Database and supports transports available under Oracle Net Services.

To configure or add an Oracle data source:

After you have installed the Oracle Database ODBC driver, use the ODBC Data Source Administrator to configure or add an Oracle data source for each of your Oracle Databases. the Oracle Database ODBC driver uses the information you enter when you add the data source to access the data. Follow these steps:

  1. From the start menu, select Programs, Administrative Tools, Data Sources (ODBC).

    In the ODBC Data Source Administrator dialog box, in the Drivers tab, a list of installed drivers is displayed. Ensure that the Drivers tab displays the Oracle Database ODBC driver that you just installed.

  2. On the System DSN tab, click Add to display the Create New Data Source dialog box.

  3. In the Create New Data Source dialog box, from the list of installed drivers, select the Oracle Database ODBC driver for which you want to set up a data source.

  4. Click Finish.

    The Oracle ODBC Driver Configuration dialog box is displayed. You must enter the DSN and TNS Service Name. You can provide the other information requested in the dialog box, or you can leave the fields blank and provide the information when you run the application.

  5. After you have entered the data, click OK or click Return.

You can change or delete a data source at any time. The following subtopics explain how to add, change, or delete a data source.

To modify an Oracle data source:

  1. From the start menu, select Programs, Administrative Tools, Data Sources(ODBC).

  2. In the ODBC Data Source Administrator dialog box, select the data source from the Data Sources list and click Configure.

    The Oracle ODBC Driver Configuration dialog box is displayed.

  3. In the Oracle ODBC Driver Configuration dialog box, modify the option values as necessary and click OK.

To delete an Oracle data source:

  1. From the start menu, select Programs, Administrative Tools, Data Sources(ODBC).

  2. In the ODBC Data Source Administrator dialog box, select the data source you want to delete from the Data Sources list.

  3. Click Remove, and then click Yes to confirm the deletion.

Oracle Database ODBC Driver Configuration Dialog Box

Note: The Oracle Database ODBC Driver Configuration dialog box is available only to Microsoft Windows users.

The following screenshot shows an example of the Oracle Database ODBC Driver Configuration dialog box.

Figure 1: Oracle ODBC Driver Configuration Dialog Box

Description of the illustration setup_app-2.gif

The following list is an explanation of the main setup options and fields found on the Oracle Database ODBC Driver Configuration dialog box shown in the preceding graphic. The tabs found on the lower half of this dialog box are described in the subsequent topics.

You must enter the DSN and the TNS Service Name. You can provide the other information requested in the dialog box or you can leave the fields blank and provide the information when you run the application.

In addition to the main setup options previously described, there is a Test Connection option available. The Test Connection option verifies whether the ODBC environment is configured properly, by connecting to the database specified by the DSN definition. When you click Test Connection, you are prompted for the username and password.

For an explanation of the options tabs found on the lower half of the Oracle Database ODBC Driver Configuration dialog box, click any of these links:

Application Options

The following screenshot shows an example of the Application options tab found on the Oracle ODBC Driver Configuration dialog box.

Figure 2: The Application Options Tab of the Oracle ODBC Driver Configuration Dialog Box

The following list is an explanation of the fields found on the Application options tab shown in the preceding graphic:

Note: There is an impact on performance each time a cursor is closed.

See Also: Oracle ODBC Driver Configuration Dialog Box for the main configuration setup options

Oracle Options

The following screenshot shows an example of the Oracle options tab found on the Oracle Database ODBC Driver Configuration dialog box.

Figure 3: The Oracle Options Tab of the Oracle ODBC Driver Configuration Dialog Box

The following list is an explanation of the fields found on the Oracle options tab shown in the preceding graphic:

Note: When LONG and LOB data types are present, the number of rows prefetched by the ODBC driver is not determined by the Fetch Buffer Size. The inclusion of the LONG and LOB data types minimizes the performance improvement and could result in excessive memory use. The ODBC driver disregards the Fetch Buffer Size and prefetches a set number of rows only in the presence of the LONG and LOB data types.

Note: Oracle Fail Safe is deprecated and it can be desupported and unavailable in a future release. Oracle recommends that you evaluate other single-node failover options, such as Oracle RAC One Node.

Note: See the Oracle Fail Safe and Oracle Parallel Server documentation on how to set up and use both of these products.

See Also: Oracle ODBC Driver Configuration Dialog Box for the main configuration setup options

Workarounds Options

The following screenshot shows an example of the Workarounds options tab found on the Oracle Database ODBC Driver Configuration dialog box.

Figure 4: The Workarounds Options Tab of the Oracle ODBC Driver Configuration Dialog Box

The following list is an explanation of the fields found on the Workarounds options tab shown in the preceding graphic:

See Also:

SQL Server Migration Options

The following screenshot shows an example of the SQL Server Migration options tab found on the Oracle ODBC Driver Configuration dialog box.

Figure 5: The SQL Server Migration Options Tab of the Oracle ODBC Driver Configuration Dialog Box

The fields of the SQL Server Migration options tab in the preceding graphic are:

See Also: Oracle ODBC Driver Configuration Dialog Box for the main configuration setup options

Reducing Lock Timeout

An Oracle server waits indefinitely for lock conflicts between transactions to be resolved. You can limit the amount of time that an Oracle server waits for locks to be resolved by setting the Oracle Database ODBC driver’s LockTimeOut entry in the oraodbc.ini file. The value you enter for the LockTimeOut parameter is the number of seconds after which an Oracle server times out if it cannot obtain the requested locks. In the following example, the Oracle server times out after 60 seconds:

[Oracle ODBC Driver Common]
LockTimeOut=60

Patching Oracle Instant Client ODBC

This section guides you through the procedures required to patch Oracle Instant Client ODBC.

Note: Back up the Oracle Database ODBC driver shared library and other files before patching them.

You must rebuild your Oracle Instant Client packages and libraries as part of the patching process.

Topics:

Patching Oracle Instant Client ODBC on Linux and UNIX Method 1

Patching the Instant Client ODBC driver on Linux/UNIX can be done by generating the Instant Client ODBC package and Basic or Basic Light package in a patched ORACLE_HOME. These new packages should then be unzipped into the Instant Client directory that needs to be patched. This method of patching is recommended.

See Also: Patching Oracle Instant Client explains the procedure for patching and generating Instant Client Basic and Basic Light packages and Instant Client ODBC.

Patching Oracle Instant Client ODBC on Linux and UNIX Method 2

Alternatively, to patch Oracle Instant Client ODBC Driver, copy the following files from a patched ORACLE_HOME:

Patching on Windows

You can patch Instant Client ODBC Driver on Windows only manually by copying the ODBC driver shared library files and supporting library files from a patched ORACLE_HOME or from an unpacked Oracle Database Bundle patch. These should be copied into the Instant Client directory. Generating an Instant Client ODBC package is not available on Windows.

The files that must be copied to the Instant Client directory:

Note: While copying from the Oracle Database Bundle patch, some of the aforementioned files may be missing. This implies that those files are unchanged and do not need to be patched.

Uninstallation

This section takes you through the steps required to uninstall the Oracle Database ODBC driver.

Topics:

Uninstalling Oracle Instant Client ODBC on Linux and UNIX

Use the following procedure to uninstall Oracle Instant Client ODBC on Linux and UNIX.

  1. Remove the Oracle Database ODBC driver entry from the odbcinst.ini file of the unixODBC Driver Manager.

    The default name of this entry is like: [Oracle 19c ODBC driver].

  2. Remove the DSN entry of the Oracle Database ODBC driver from odbc.ini.

    The default name of the DSN entry is like [OracleODBC-19c].

  3. Delete all files and directories in the Instant Client ODBC directory.

Uninstalling Oracle Instant Client ODBC on Windows

Use the following procedure to uninstall Instant Client ODBC on Windows.

  1. Remove the DSN associated with the Oracle Database ODBC driver in the ODBC Data Source Administrator (odbcad32) console.

  2. Execute the odbc_uninstall.exe file from the Instant Client ODBC directory.

  3. Delete all files and directories in the Instant Client ODBC directory.