Getting started

This section shows you how to install the Easysoft ODBC-Oracle Driver and configure the ODBC data source that stores the connection details for your Oracle database. You’re then ready to work with Oracle data in your application.

Installing the Oracle client
Installing the Easysoft ODBC-Oracle Driver
Connecting to Oracle
Logging

Installing the Oracle client

The Easysoft ODBC-Oracle Driver uses the Oracle client software to access Oracle. Either the Instant Client or standard Oracle client must be installed on the same computer as the Easysoft ODBC-Oracle Driver.

Although the Easysoft ODBC-Oracle Driver is compatible with both Oracle clients, we recommend that you use our driver with the Instant Client.

If your application is 64-bit, download the 64-bit version of the client. If your application is 32-bit, download the 32-bit version of the client.

Use SQL*Plus, included in the client distribution to check that you can connect to your database. For example:

sqlplus system/p455w0rd@//localhost:1521/XE

If you’re unable to connect to Oracle with SQL*Plus, contact your Oracle Database Administrator. If you cannot access your Oracle database with SQL*Plus, you won’t be able to access the database with the Easysoft ODBC-Oracle Driver.

At the prompt, enter a SELECT statement to test that you can retrieve some data:

SELECT * FROM dual;

To exit SQL*Plus, enter exit.

Installing the Easysoft ODBC-Oracle Driver

Install the Easysoft ODBC-Oracle Driver on the computer where the application you want to connect to Oracle is running.

Installing on Linux or UNIX
Uninstalling on Linux or UNIX
Installing on Windows
Uninstalling on Windows

Installing on Linux or UNIX

The installation can be done by anyone with root access.

Download the Easysoft ODBC-Oracle Driver distribution for your client application platform.

If your client application is 64-bit, choose the 64-bit driver distribution from the Platforms list. If your client application is 32-bit, choose the 32-bit driver distribution from the Platforms list.
Copy the distribution to a temporary directory on the machine where the application you want to connect to Oracle is installed.
Unpack the distribution and cd into the resultant directory.
As root, run:
```
./install
```
Follow the onscreen instructions to progress through the installation.

Further information

Preinstallation requirements
What you can install
Where to install
Changes made to your system
Installing alongside other existing Easysoft product installations
Gathering information required during the installation
Unpacking the distribution
License to use
Answering questions during the installation
Running the installer
Locating or installing unixODBC
Installing the Easysoft ODBC driver
Licensing
Post installation steps for non-root installations

Preinstallation requirements

To install the Easysoft ODBC-Oracle Driver you need:

The Bourne shell in /bin/sh. If your Bourne shell is not located there, you may need to edit the first line of the installation script.
Various commonly used commands such as:
```
grep, awk, test, cut, ps, sed, cat, wc, uname, tr, find, echo, sum, head, tee, id
```
If you do not have any of these commands, they can usually be obtained from the Free Software Foundation. As the tee command does not work correctly on some systems, the distribution includes a tee replacement.
Depending on the platform, you’ll need up to 10 MB of temporary space for the installation files and up to 10 MB of free disk space for the installed programs. If you also install the unixODBC Driver Manager, these numbers increase by approximately 1.5 MB.
For Easysoft licensing to work, you must do one of the following:
- Install the Easysoft ODBC-Oracle Driver in /usr/local/easysoft.
- Install the Easysoft ODBC-Oracle Driver elsewhere and symbolically link /usr/local/easysoft to wherever you chose to install the software.
  
  The installation will do this automatically for you so long as you run the installation as someone with permission to create /usr/local/easysoft.
- Install the Easysoft ODBC-Oracle Driver elsewhere and set the EASYSOFT_ROOT environment variable. For more information about setting the EASYSOFT_ROOT environment variable, refer to Post installation steps for non-root installations.
An ODBC Driver Manager.

Easysoft ODBC-Oracle Driver distributions include the unixODBC Driver Manager.

You do not have to be the root user to install, but you will need permission to create a directory in the chosen installation path. Also, if you are not the root user, it may not be possible for the installation to:
1. Register the Easysoft ODBC-Oracle Driver with unixODBC.
2. Create the example data source in the SYSTEM odbc.ini file.
3. Update the dynamic linker entries (some platforms only).

If you are not root, these tasks will have to be done manually later.

We recommend that you install all components as the root user.

What you can install

This distribution contains:

The Easysoft ODBC-Oracle Driver.
The unixODBC Driver Manager.

You need an ODBC Driver Manager to use the Easysoft ODBC-Oracle Driver from your applications. The distribution therefore contains the unixODBC Driver Manager. Most (if not all) UNIX and Linux applications support the unixODBC Driver Manager. For example, Perl DBD::ODBC, PHP, Python, and so on.

You do not have to install the unixODBC Driver Manager included with this distribution. You can use an existing copy of unixODBC. For example, a version of unixODBC installed by another Easysoft product, a version obtained from your operating system vendor, or one that you built yourself. However, as Easysoft ensure that the unixODBC distributed with the Easysoft ODBC-Oracle Driver has been tested with that driver, we recommend you use it.

If you choose to use an existing unixODBC Driver Manager, the installation script will attempt to locate it. The installation script looks for the ODBC Driver Manager in the standard places. If you have installed it in a non-standard location, the installation script prompts you for the location. The installation primarily needs unixODBC’s odbcinst command to install drivers and data sources.

Where to install

This installation needs a location for the installed files. The default location is /usr/local.

At the start of the installation, you’re prompted for an installation path. All files are installed in a subdirectory of your specified path called easysoft. For example, if you accept the default location /usr/local, the product will be installed in /usr/local/easysoft and below.

If you choose a different installation path, the installation script tries to symbolically link /usr/local/easysoft to the easysoft subdirectory in your chosen location. This allows us to distribute binaries with built in dynamic linker run paths. If you are not root or the path /usr/local/easysoft already exists and is not a symbolic link, the installation will be unable to create the symbolic link. For information about how to correct this manually, refer to Post installation steps for non-root installations.

Note that you cannot license Easysoft products until either of the following is true:

/usr/local/easysoft exists either as a symbolic link to your chosen installation path or as the installation path itself.
You have set EASYSOFT_ROOT to installation_path/easysoft.

Changes made to your system

The installation script installs files in subdirectories of the path requested at the start of the installation. Depending on what is installed, a few changes may be made to your system:

If you choose to install the Easysoft ODBC-Oracle Driver into unixODBC, unixODBC’s odbcinst command will be run to add an entry to your odbcinst.ini file. You can locate this file with odbcinst -j. (odbcinst is in installation_path/easysoft/unixODBC/bin, if you are using the unixODBC included with this distribution.)
The installation script installs an example data source into unixODBC. This data source will be added to your SYSTEM odbc.ini file. You can locate your SYSTEM odbc.ini file by using odbcinst -j.
Dynamic linker. On operating systems where the dynamic linker has a file listing locations for shared objects (Linux and FreeBSD), the installation script will attempt to add paths under the path you provided at the start of the installation to the end of this list:
- On Linux, this is usually the file /etc/ld.so.conf.
- On FreeBSD this is usually the file /etc/defaults/rc.conf.

Installing alongside other existing Easysoft product installations

Each Easysoft distribution contains common files shared between Easysoft products. These shared objects are placed in installation_path/easysoft/lib. When you run the installation script, the dates and versions of these files are compared with the same files in the distribution. The files are only updated if the files being installed are newer or have a later version number.

You should ensure that nothing on your system is using Easysoft software before starting an installation. This is because on some platforms, files in use cannot be replaced. If a file cannot be updated, you get a warning during the installation. All warnings are written to a file called warnings in the directory you unpacked the distribution into.

If the installer detects you’re upgrading a product, the installer will suggest you delete the product directory to avoid having problems with files in use. An alternative is to rename the specified directory.

If you are upgrading, you will need a new license from Easysoft to use the new driver.

Gathering information required during the installation

During the installation, you’re prompted for various pieces of information. Before installing, you need to find out whether you have unixODBC already installed and where it is installed. The installation script searches standard places like /usr and /usr/local.

However, if you installed the Driver Manager in a non-standard place and you do not install the included unixODBC, you will need to know the location.

Unpacking the distribution

The distribution for UNIX and Linux platforms is a tar file. To extract the installation files from the tar file, use:

tar -xvf odbc-oracle-3.10.0-linux-x86-64-ul64.tar

This creates a directory with the same name as the tar file (without the .tar postfix) containing further archives, checksum files, an installation script, and various other installation files.

Change into the directory created by unpacking the tar file to run the installation script. For example:

# cd odbc-oracle-3.10.0-linux-x86-64-ul64

License to use

The end-user license agreement (EULA) is in the file license.txt. Be sure to understand the terms of the agreement before continuing, as you’re required to accept the license terms at the start of the installation.

Answering questions during the installation

Throughout the installation, you’re prompted to answer some questions. In each case, the default choice displays in square brackets and you need only press Enter to accept the default. If there are alternative responses, these are shown in round brackets; to choose one of these, type the response and press Enter.

For example:

Do you want to continue? (y/n) [n]:

The possible answers to this question are y or n. The default answer when you type nothing and press Enter is n.

Running the installer

If you are considering running the installation as a non-root user, we suggest you review this carefully as you will have to get a root user to manually complete some parts of the installation afterwards. We recommend installing as the root user. (If you’re concerned about the changes that will be made to your system, refer to Changes made to your system.)

To start the installation, run:

./install

You need to:

Confirm your acceptance of the license agreement by typing "yes" or "no". For more information about the license agreement, refer to License to use.
Supply the location where the software is to be installed.

We recommend accepting the default installation path.

For more information, refer to Where to install.

Locating or installing unixODBC

We strongly recommend you use the unixODBC Driver Manager because:

The installation script is designed to work with unixODBC and can automatically add Easysoft ODBC-Oracle Driver and data sources during the installation.
Most applications and interfaces that support ODBC are compatible with unixODBC. The Easysoft ODBC-Oracle Driver and any data sources that you add during the installation are automatically available to your applications and interfaces therefore.
The unixODBC project is currently led by Easysoft developer Nick Gorham. This means that there is a great deal of experience at Easysoft of unixODBC in general and of supporting the Easysoft ODBC-Oracle Driver running under unixODBC. It also means that if you find a problem in unixODBC, it’s much easier for us to facilitate a fix.

The installation starts by searching for unixODBC. There are two possible outcomes here:

If the installation script finds unixODBC, the following message displays:
```
Found unixODBC under path and it is version n.n.n
```
If the installation script can’t find unixODBC in the standard places, you will be asked whether you have it installed.

If unixODBC is installed, you need to provide the unixODBC installation path. Usually, the path required is the directory above where odbcinst is installed. For example, if odbcinst is in /opt/unixODBC/bin/odbcinst, the required path is /opt/unixODBC.

If unixODBC is not installed, you should install the unixODBC included with this distribution.

If you already have unixODBC installed, you do not have to install the unixODBC included with the distribution, but you might consider doing so if your version is older than the one we provide.

The unixODBC in the Easysoft ODBC-Oracle Driver distribution is not built with the default options in unixODBC’s configure line.

Option Description

Option	Description
`--prefix=/etc`	This means the default SYSTEM `odbc.ini` file where SYSTEM data sources are located is `/etc/odbc.ini`.
`--enable-drivers=no`	This means other ODBC drivers that come with unixODBC are not installed.
`--enable-iconv=no`	This means unixODBC does not look for libiconv. Warnings about not finding an iconv library were confusing our customers.
`--enable-stats=no`	Turns off unixODBC statistics, which use system semaphores to keep track of used handles. Many systems do not have sufficient semaphore resources to keep track of used handles.
`--enable-readline=no`	This turns off readline support in isql. We did this because it ties isql to the version of libreadline on the system we build on. We build on as old a version of the operating system as we can for forward compatibility. Many newer Linux systems no longer include the older readline libraries and so turning on readline support makes isql unusable on these systems.
`--prefix=/usr/local/easysoft/unixODBC`	This installs unixODBC into `/usr/local/easysoft/unixODBC`.

--prefix=/etc

This means the default SYSTEM odbc.ini file where SYSTEM data sources are located is /etc/odbc.ini.

--enable-drivers=no

This means other ODBC drivers that come with unixODBC are not installed.

--enable-iconv=no

This means unixODBC does not look for libiconv. Warnings about not finding an iconv library were confusing our customers.

--enable-stats=no

Turns off unixODBC statistics, which use system semaphores to keep track of used handles. Many systems do not have sufficient semaphore resources to keep track of used handles.

--enable-readline=no

This turns off readline support in isql. We did this because it ties isql to the version of libreadline on the system we build on. We build on as old a version of the operating system as we can for forward compatibility. Many newer Linux systems no longer include the older readline libraries and so turning on readline support makes isql unusable on these systems.

--prefix=/usr/local/easysoft/unixODBC

This installs unixODBC into /usr/local/easysoft/unixODBC.

Installing the Easysoft ODBC driver

The Easysoft ODBC-Oracle Driver installation script:

Installs the driver.
Registers the driver with the unixODBC Driver Manager.

If the Easysoft ODBC-Oracle Driver is already registered with unixODBC, a warning displays that lists the drivers unixODBC knows about. If you’re installing the Easysoft ODBC-Oracle Driver into a different directory than it was installed before, you need to edit your odbcinst.ini file after the installation and correct the Driver and Setup paths. unixODBC’s odbcinst doesn’t update these paths if a driver is already registered.
Creates an example Easysoft ODBC-Oracle Driver data source. If unixODBC is installed and you registered the Easysoft ODBC-Oracle Driver with unixODBC, the installation script adds example data source to your odbc.ini file.

Licensing

The installation_path/easysoft/license/licshell program lets you obtain or list licenses.

Licenses are stored in installation_path/easysoft/license/licenses.

After obtaining a license, you should make a backup copy of this file.

The installation script asks you if you want to request an Easysoft ODBC-Oracle Driver license:

Would you like to request a Easysoft ODBC-Oracle Driver license now (y/n) [y]:

You do not need to obtain a license during the installation, you can run licshell after the installation to obtain or view licenses.

If you answer y, the installation runs the licshell script.

To obtain a license automatically, you need to be connected to the Internet and allow outgoing connections to license.easysoft.com on port 8884. If you’re not connected to the Internet or don’t allow outgoing connections on port 8884, the License Client can create a license request file that you can email to us.

When you start the License Client, the following menu displays:

[0] exit
[1] view existing license
[n] obtain a license for the desired product.

To obtain a license, select one of the options from [2] onwards for the product you’re installing. The License Client then runs a program that generates a key that’s used to identify the product and operating system (we need this key to license you).

After you have chosen the product to license (Easysoft ODBC-Oracle Driver), you need to supply:

Your full name.
Your company name.
An email contact address. This must be the email address that you used when you registered on the Easysoft web site.
A reference number (also referred to as an authorization code). When applying for a trial license, press Enter when prompted for a reference number. This field only applies to full (paid) licenses.

You’re then asked to choose how you want to obtain the license.

The choices are:

[1] Automatically by contacting the Easysoft License Daemon

This requires a connection to the Internet and the ability to support an outgoing TCP/IP connection to license.easysoft.com on port 8884.
[2] Write information to file

The license request is output to license_request.txt.
[3] Cancel this operation

If you choose to obtain the license automatically, the License Client tries to open a TCP/IP connection to license.easysoft.com on port 8884 and send the details you supplied along with your machine number. No other data is sent. The data sent is transmitted as plain text, so if you want to avoid the possibility of this information being intercepted by someone else on the Internet, you should choose [2] and send the the request to us. The License daemon returns the license key, prints it to the screen and make it available to the installation script in the file licenses.out.

If you choose option [2], the license request is written to the file license_request.txt. You should then exit the License Client by choosing option [0] and complete the installation. After you have sent the license request to us, we’ll return a license key. Add this to the end of the file installation_path/easysoft/license/licenses.

Post installation steps for non-root installations

If you installed the Easysoft ODBC-Oracle Driver as a non-root user (not recommended), there may be some additional steps you need to do manually:

If you attempt to install the Easysoft ODBC-Oracle Driver under the unixODBC Driver Manager and you do not have write permission to unixODBC’s odbcinst.ini file, the driver can’t be added.

You can manually install the driver under unixODBC by adding an entry to the odbcinst.ini file. Run odbcinst -j to find out the location of the DRIVERS file then append the lines from drv_template file to odbcinst.ini. (drv_template is in the directory where the Easysoft distribution was untarred to.)
No example data sources can be added into unixODBC if you do not have write permission to the SYSTEM odbc.ini file. Run odbcinst -j to find out the location of the SYSTEM DATA SOURCES file then add your data sources to this file.
On systems where the dynamic linker has a configuration file defining the locations where it looks for shared objects (Linux and FreeBSD), you need to add:
```
installation_path/easysoft/lib
installation_path/easysoft/unixODBC/lib
```
The latter entry is only required if you installed the unixODBC included with this distribution. Sometimes, after changing the dynamic linker configuration file, you need to run a program to update the dynamic linker cache. (For example, /sbin/ldconfig on Linux.)
If you didn’t install the Easysoft ODBC-Oracle Driver in the default location, you need to do one of the following:
- Link /usr/local/easysoft to the easysoft directory in your chosen installation path.
  
  For example, if you installed in /home/user, the installation creates /home/user/easysoft and you need to symbolically link /usr/local/easysoft to /home/user/easysoft:
  ln -s /home/user/easysoft /usr/local/easysoft
- Set and export the EASYSOFT_ROOT environment variable to installation_path/easysoft.
If your system doesn’t have a dynamic linker configuration file, you need to add the paths listed in step 3 to whatever environment path the dynamic linker uses to locate shared objects. You may want to add these paths to a system file run whenever someone logs. For example, /etc/profile.

The environment variable depends on the dynamic linker. Refer to your ld or ld.so man page. It is usually:
```
LD_LIBRARY_PATH, LIBPATH, LD_RUN_PATH, or SHLIB_PATH.
```

Uninstalling on Linux or UNIX

There is no automated way to remove the Easysoft ODBC-Oracle Driver in this release. However, removal is quite simple. To do this:

Change directory to installation_path/easysoft and delete the product directory. installation_path is the Easysoft ODBC-Oracle Driver installation directory, by default /usr/local.
If you had to add this path to the dynamic linker search paths (for example, /etc/ld.so.conf on Linux), remove it. You may have to run a linker command such as /sbin/ldconfig to get the dynamic linker to reread its configuration file. Usually, this step can only be done by the root user.
If you were using unixODBC, the Easysoft ODBC-Oracle Driver entry needs to be removed from the odbcinst.ini file. To check whether the Easysoft ODBC-Oracle Driver is configured under unixODBC, use odbcinst -q -d. If the command output contains [ORACLE], uninstall the driver from unixODBC by using:
```
odbcinst -u -d -n ORACLE
```

If a reduced usage count message is displayed, repeat this command until odbcinst reports that the driver has been removed.

If you created any Easysoft ODBC-Oracle Driver data sources under unixODBC, you may want to delete these. To do this, first use odbcinst -j to locate USER and SYSTEM odbc.ini files. Then check those files for data sources that have the driver attribute set to ORACLE.
Remove the install.info for the Easysoft ODBC-Oracle Driver from the /usr/local/easysoft directory.

Installing on Windows

The Windows installation can be done by anyone with local administrator privileges.

Download the Easysoft ODBC-Oracle Driver installer.
Follow the onscreen instructions to progress through the installation wizard.

Updating files that are in use

To avoid rebooting your computer, the Easysoft ODBC-Oracle Driver installer prompts you when files that it needs to update are in use by another application or service. This frees the locked files and allows the installation to complete without a system restart. The installer uses the Restart Manager to locate the applications that are using files that need updating. These applications are displayed in the Files in Use dialog box. To avoid a system restart, choose Automatically close applications and attempt to restart them after setup is complete. The Easysoft ODBC-Oracle Driver installer then uses Restart Manager to try to stop and restart each application or service in the list. If possible, Restart Manager restores applications to the same state that they were in before it shut them down.

Licensing

By default, the installer starts the Easysoft License Manager, because you can’t use the Easysoft ODBC-Oracle Driver until you have a license. If you choose not to run Easysoft License Manager as part of the installation process, run License Manager from the Easysoft group in the Windows Start menu when you’re ready to license the Easysoft ODBC-Oracle Driver. These types of license are available:

A free time-limited trial license, which gives you free and unrestricted use of the product for a limited period (usually 14 days).
A full license if you have purchased the product. On purchasing the product you are given an authorization code, which you use to obtain a license.

To license the Easysoft ODBC-Oracle Driver:

In License Manager, enter your contact details.

You must complete the Name, E-Mail Address, and Company fields.

The e-mail address must be the same as the one used to register at the Easysoft web site. Otherwise, you won’t be able to obtain a trial license.
Choose Request License.

You’re prompted to choose a license type.
Do one of the following:
- For a trial license, choose Time Limited Trial, and then choose Next.
  -Or-
- For a purchased license, choose Non-expiring License, and then choose Next.
Choose your product from the drop-down list when prompted, and then choose Next.
For a purchased license, enter your authorization code when prompted, and then choose Next.
Choose how to get your license when prompted.
Do one of the following:
- Choose On-line Request if your machine is connected to the internet and can make outgoing connections to port 8884.
  With this method, License Manager automatically requests and then applies your license.
  -Or-
- Choose View Request. Then open a web browser and go to https://www.easysoft.com/support/licensing/trial_license.html or https://www.easysoft.com/support/licensing/full_license.html, as appropriate. In the web page, enter your machine number (labelled Number in the license request). For purchased licenses, you also need to enter your authorization code (labelled Ref in the license request).
  We’ll automatically email your license to the email address you supplied in License Manager.
  -Or-
- Choose Email Request to email your license request to our licensing team.
  Once we’ve processed you request, we’ll email your license to the email address you supplied in License Manager.
Close the License Manager windows and then choose Finish.

If you chose either View Request or Email Request, apply your license by double-clicking the email attachment when you get the license email from us. Alternatively, start License Manager from the Easysoft folder in the Windows Start menu. Then choose Enter License and paste the license in the space provided.

Once you’ve licensed the Easysoft ODBC-Oracle Driver, the installation is complete.

Repairing the installation

The installer can repair a broken Easysoft ODBC-Oracle Driver installation. For example, you can use the installer to restore missing Easysoft ODBC-Oracle Driver files or registry keys. To do this:

In the Windows Taskbar, enter Add or remove programs in the Windows Search box.
Select Easysoft ODBC-Oracle Driver in the list, and then choose Repair.

Uninstalling on Windows

This section explains how to remove the Easysoft ODBC-Oracle Driver from your system.

Removing Easysoft ODBC-Oracle Driver data sources

Easysoft ODBC-Oracle Driver data sources are not removed when you uninstall the Easysoft ODBC-Oracle Driver. You don’t therefore need to recreate your Easysoft ODBC-Oracle Driver data sources if you reinstall or upgrade. If you don’t want to keep your Easysoft ODBC-Oracle Driver data sources, use Microsoft ODBC Data Source Administrator to remove them, before uninstalling the Easysoft ODBC-Oracle Driver:

In the Windows Taskbar, enter Run in the Windows Search box.
In the Windows Run dialog box, enter:
```
odbcad32.exe
```
Locate your data source in either the User or System tab.
Select the data source from the list, and then choose Remove.

If the Remove button isn’t available, close ODBC Data Source Administrator, and then, in the Windows Run dialog box, enter:
```
%windir%\syswow64\odbcad32.exe
```
Repeat the previous two steps.

Removing the Easysoft ODBC-Oracle Driver

In the Windows Taskbar, enter Add or remove programs in the Windows Search box.
Select Easysoft ODBC-Oracle Driver in the list, and then choose Uninstall.

Easysoft product licenses are stored in the Windows registry. When you uninstall, your licenses are not removed, so you do not need to relicense the product if you reinstall or upgrade.

Connecting to Oracle

Applications that support ODBC interface with an ODBC Driver Manager, which is included with the operating system, and also the Easysoft ODBC driver distribution on some platforms. One of the jobs that the ODBC Driver Manager does is to manage ODBC data sources. A data source specifies which ODBC driver to load, which data store to connect to, and how to connect to it.

Before setting up a data source, you must have successfully installed the Easysoft ODBC-Oracle Driver.

Connecting from Linux or UNIX
Connecting from Windows

Connecting from Linux or UNIX

Setting the environment

If you’re using the Easysoft ODBC-Oracle Driver with the Instant Client, set LD_LIBRARY_PATH to point to the Instant Client directory. For example:

LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/lib/instantclient_23
export LD_LIBRARY_PATH

If you’re using the Easysoft ODBC-Oracle Driver with the standard Oracle client, set ORACLE_HOME to point to the client directory. For example:

ORACLE_HOME=/home/oracle/OraHome1
export ORACLE_HOME

If you’re using the standard Oracle client, set LD_LIBRARY_PATH to point to $ORACLE_HOME/lib. For example:

LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/home/oracle/OraHome1/lib
export LD_LIBRARY_PATH

On some platforms, you need to use SHLIB_PATH or LIBPATH rather than LD_LIBRARY_PATH.

Creating an ODBC data source

There are two ways to create a data source to your Oracle data:

Create a SYSTEM data source, which is available to anyone who logs on to the computer where the Easysoft ODBC-Oracle Driver is installed.

– Or –
Create a USER data source, which is only available to the user who is currently logged on to the computer where the Easysoft ODBC-Oracle Driver is installed.

By default, the Easysoft ODBC-Oracle Driver installation creates a sample SYSTEM data source named demo-oracle. If you’re using the unixODBC included in the Easysoft ODBC-Oracle Driver distribution, the SYSTEM odbc.ini file is in /etc.

If you built unixODBC yourself, or installed it from some other source, SYSTEM data sources are stored in the path specified with the configure option --sysconfdir=directory. If sysconfdir was not specified when unixODBC was configured and built, it defaults to /usr/local/etc.

If you accepted the default choices when installing the Oracle, USER data sources must be created and edited in $HOME/.odbc.ini.

Notes

To display the directory where unixODBC stores SYSTEM and USER data sources, type odbcinst -j.
By default, you must be logged in as root to edit a SYSTEM data source defined in /etc/odbc.ini.

You can either edit the sample data source or create new data sources.

Each section of the odbc.ini file starts with a data source name in square brackets [ ] followed by a number of attribute=value pairs.

The Driver attribute identifies the ODBC driver in the odbcinst.ini file to use for a data source. When the Easysoft ODBC-Oracle Driver is installed into unixODBC, it places a ORACLE entry into the odbcinst.ini file. You should always have Driver = ORACLE in your Easysoft ODBC-Oracle Driver data sources therefore.

To configure a Easysoft ODBC-Oracle Driver data source, in your odbc.ini file, you need to specify:

The Oracle database user name (User).
The Oracle database password (Password).
The SQL connect URL string (Database).

-Or-

If you’re using the standard Oracle client:
The tnsnames.ora service name for the database (Database).

Here’s an Instant Client example:

[demo-oracle]
Driver      = ORACLE
Database    = //testhost:1521/testdb
User        = system
Password    = p455w0rd

Here’s a standard client example:

[demo-oracle]
Driver      = ORACLE
Database    = testdb
User        = system
Password    = p455w0rd

The Easysoft ODBC-Oracle Driver must be able to find the following shared objects:

libodbcinst.so

By default, this is located in /usr/local/easysoft/unixODBC/lib/.
libeslicshr.so

By default, this is located in /usr/local/easysoft/lib/.
libessupp.so By default, this is located in /usr/local/easysoft/lib/.

You may need to set and export LD_LIBRARY_PATH, SHLIB_PATH, or LIBPATH (depending on your operating system and run-time linker) to include the directories where libodbcinst.so, libeslicshr.so, and libessupp.so are located.

The isql query tool lets you test your Easysoft ODBC-Oracle Driver data sources. To test the Easysoft ODBC-Oracle Driver connection:

Change directory into /usr/local/easysoft/unixODBC/bin.
Enter ./isql -v data_source, where data_source is the name of the target data source.
At the prompt, enter an SQL query. For example:
```
SQL> SELECT * FROM dual;
```
–Or–
Enter help to return a list of tables:
```
SQL> help
```

Some Easysoft ODBC-Oracle Driver distributions contain a diagnostic tool named checksys, which detects any configuration or environment problems and suggests corrective action. It’s located in the installation_dir/easysoft/oracle directory. For example:

cd /usr/local/easysoft/oracle
./checksys -d data_source

Connecting from Windows

Creating an ODBC data source

In the Windows Taskbar Search box, enter “Run”.

Do one of the following:

If your application is 64-bit, in the Run dialog box, enter:
```
odbcad32.exe
```
-Or-

If your application is 32-bit, in the Run dialog box, enter:

%windir%\syswow64\odbcad32.exe

If you’re not sure whether your application is 32-bit or 64-bit, start your application, then in Windows Task Manager check whether your application’s process name contains (32-bit). For example, the process name for the 32-bit version of Excel is Microsoft Excel (32-bit); the process name for the 64-bit version of Excel is Microsoft Excel. On older versions of Windows, 32-bit applications contain *32 in the process name rather than (32-bit).
For applications such as Oracle or SQL Server that run as a service, check the *Background processes* list rather than the Apps list in Task Manager.
If you’re running a programming language from within a Windows command-line shell (for example, Command or PowerShell), in your shell, run the .exe file for the programming language. For example, run perl, php, python, or node. In Task Manager, expand the process list for Windows Command Processor or Windows PowerShell, as appropriate, and check whether the process for your programming language contains (32-bit).

Do one of the following:
- To create a data source that only the user you’re currently logged in as can access, choose the User tab.
  If your application is a Windows service (for example, SQL Server or Oracle) creating a user data source won’t work, unless the service is running as the same user you’re logged in as.
- To create a data source that all users on this computer can access, choose the System tab.
Choose Add.
In the list of ODBC drivers, select Easysoft ODBC-Oracle Driver, and then choose Finish.
Complete the Easysoft ODBC-Oracle Driver configuration dialog box.
To find out how to do this, refer to the Connection attributes section.
To test the connection to Oracle, choose Test.
Note that this doesn’t test that the Easysoft ODBC-Oracle Driver is licensed. If you haven’t yet licensed the Easysoft ODBC-Oracle Driver, this ODBC data source won’t work with your application, even if the Test button succeeds.

Setting on Linux and UNIX

Your Easysoft ODBC-Oracle Driver data source in odbc.ini must contain these attributes if you’re using the Instant Client with the Easysoft ODBC-Oracle Driver:

The Oracle database user name (User).
The Oracle database password (Password).
The SQL connect URL string (Database).

-Or-

If you’re using the standard Oracle client:
The tnsnames.ora service name for the database (Database).

Here’s an Instant Client example:

[demo-oracle]
Driver      = ORACLE
Database    = //testhost:1521/testdb
User        = system
Password    = p455w0rd

Here’s a standard client example:

[demo-oracle]
Driver      = ORACLE
Database    = testdb
User        = system
Password    = p455w0rd

For more information about these mandatory attributes and other optional attributes, refer to this table:

Name Value

DSN

The name of the data source. You’ll need to specify this in your application. For example, your application may prompt you to choose this from a list of DSNs.

Description

Some applications display this to help users identify a particular data source.

Database

If you’re using the Instant Client, a SQL connect URL string. Use the following format:

//host:port/service-name

where host is the fully qualified domain name or IP address of the server on which the Oracle database is installed, port is the Oracle listener port or the alias name mapped to the port in the /etc/services file and service-name is the local net service name. For example, //my_host:1521/XE.

If you’re using the standard Oracle Client (or the Instant Client with a tnsnames.ora file by setting TNS_ADMIN), the logical name used to identify the Oracle target database. This is the local net service name defined in your tnsnames.ora file. For example, my_database.

User

The name of the user that’s supplied to Oracle to authenticate the connection.

Password

The password supplied to Oracle to authenticate the connection.

Note that passwords are case sensitive for new or modified accounts in Oracle 11 g and later.

MetaData_ID

When turned on (set to 1), the default value of the connection attribute SQL_ATTR_METADATA_ID is set to SQL_TRUE.

If SQL_TRUE, the string arguments of catalog functions are treated as identifiers. The case is not significant. For non-delimited strings, the driver removes any trailing spaces, and the string is folded to uppercase. For delimited strings, the driver removes leading and trailing spaces, and takes literally whatever is between the delimiters.

This attribute was introduced as a workaround for an issue in StarOffice. Setting this attribute can cause failures in applications that expect the default for SQL_ATTR_METADATA_ID to be SQL_FALSE.

By default, Metadata_Id is turned off.

Metadata_Dont_Change_Case

When turned on (set to 1), the Easysoft ODBC-Oracle Driver preserves the case of parameter values passed to metadata calls.

By default, Metadata_Dont_Change_Case is turned off.

VarcharTrimTrailingSpaces

When turned on (set to 1), the Easysoft ODBC-Oracle Driver trims trailing spaces from VARCHAR types when passed as bound parameters. If VarcharTrimTrailingSpaces is set to 1, trailing spaces are removed from the end of the data.

The default behaviour is to not trim spaces.

Metadata_Dont_Do_Schema

When turned on (set to 1), schema names are not returned by metadata calls. This is a workaround for some applications that do not handle schema names properly.

By default, Metadata_Dont_Do_Schema is turned off.

Use_Longs

When turned on (set to 1), information on LONG data types is returned in the result set from a SQLGetTypeInfo function call.

Restrictions with LONG data types in Oracle databases (such as only permitting one column per table to be defined) often cause errors to occur, and this attribute can be used to include LONG within the list of valid data types that can be used by an application.

The default for Use_Longs is off.

Enable_Synonyms

When turned on (set to 1), the Easysoft ODBC-Oracle Driver returns private synonyms for table names in metadata result sets.

By default, the driver return synonyms. If you don’t want synonyms, turn off Enable Synonyms. Including synonyms in metadata calls may greatly increase the size of metadata result sets for ODBC API calls such as SQLTables.

Enable_User_Catalog

When turned on, the Easysoft ODBC-Oracle Driver returns metadata for the current Oracle user only. Turning on Enable_User_Catalog reduces the number of rows returned by SQLTables calls.

When turned off, the driver returns metadata for all users. Note that many ODBC applications will never need this amount of catalog data.

By default, Enable_User_Catalog is turned on.

Describe_Param_As_Strings

Oracle doesn’t support describing parameters, so the Easysoft ODBC-Oracle Driver doesn’t support the SQLDescribeParam ODBC call. However, if Describe_Param_As_Strings is turned on, the Easysoft ODBC-Oracle Driver describes any parameters as VARCHARs.

By default, Describe_Param_As_Strings is turned off.

DBI_Long_Size

Any number you specify overrides the maximum size of a LONG column (in bytes).

Perl DBI tries to allocate a buffer the size of a LONG column and, as this is rather large, it can cause problems, which setting DBI_LONG_SIZE can resolve.

Connect_SQL

The SQL statement to run immediately after the Easysoft ODBC-Oracle Driver connects to the database.

No_LOBS

When turned on (set to 1), No_LOBS increases the performance of the Easysoft ODBC-Oracle Driver if there are no CLOB or BLOB data types in use. This is only applicable to Oracle version 8.1.7.

By default, No_LOBS is turned off.

No_Parse

When turned on (set to 1), No_Parse prevents the Easysoft ODBC-Oracle Driver from preparsing SQL (passed to SQLPrepare and SQLExecDirect) to convert ODBC escapes and parameter markers. Doing this results in a small speed increase but prevents your application from using ODBC escapes sequences and parameter markers.

OCI_Attr_Prefetch_Rows

The number of rows returned from a single "fetch" call made to the server.

For example, if OCI_Attr_Prefetch_Rows is set to 10 then 10 rows are fetched from the database server. The next call to SQLFetch doesn’t need to make a call to the server as the required rows are held by the client already. The default value is 10. Increasing this value can reduce the number of round trip network calls to the server needed to return result sets at the expense of greater memory use.

OCI_Attr_Prefetch_Memory

The number of bytes of memory used on the client to store records returned from a single SQLFetch call.

This controls the number of records returned, which will be the total required to fill the allocated memory area.

For example, if the available memory can store two rows then the next call to SQLFetch doesn’t need to make a call to the server, as the required row is held by the client already.

Stmt_Caching

This attribute enables Oracle statement caching. Oracle statement caching establishes and manages a cache of statements within a session. It improves performance by efficiently using prepared cursors on the Oracle server and eliminating repetitive statement parsing. To enable caching, set this attribute to the size of the required cache. The attribute value should specify the number of statements to cache. Setting the attribute to 0 turns statement caching off. For more information about Oracle statement caching, refer to your Oracle documentation. The default is no statement caching.

Fake_CLOB_Length

When connecting to Oracle 10 g or later from a Linux or UNIX platform, the Easysoft ODBC-Oracle Driver reports the length of BLOB, BFILE, and CLOB data types as 0. The driver does this because for these versions of Oracle, the maximum LOB size is 128 terabytes, which is too large a length for the ODBC API to handle.

To change this default behaviour, set Fake_CLOB_Length to 1. When turned on (set to 1), the Easysoft ODBC-Oracle Driver sets the length to the largest value that the integer used to report the length is capable of holding. (Note that this is the default behaviour for the Easysoft ODBC-Oracle Driver on Windows, which is not affected by FAKE_CLOB_LENGTH.)

By default, Fake_CLOB_Length is turned off.

Pull_Lobs_Locally

If your application crashes when selecting from multiple CLOB columns, try adding:

Pull_LOBS_Locally=1

to your ODBC data source or connection string. When set to 1, the Easysoft ODBC-Oracle Driver returns the entire contents of the CLOB data to an internally allocated buffer. This lets the Easysoft ODBC-Oracle Driver determine the byte length of the CLOB. This avoids the application from being given a short length when the character length for the data is not the same as the byte length.

By default, Pull_LOBS_Locally is turned off (set to 0).

OCI_UTF_Flag

When turned on (set to 1), the Easysoft ODBC-Oracle Driver does additional conversion when reading LOB data. The Easysoft ODBC-Oracle Driver does this to compensate for non-conformant OCILobRead behaviour when reading multibyte character data. When turned off (set to 0), the Easysoft ODBC-Oracle Driver assumes that the OCILobRead behaviour conforms to the Oracle documentation.

Setting OCI_UTF_Flag to 1 may provide a workaround if you experience problems when reading UTF-8 LOB data in parts (that is, the buffer size passed to SQLGetData is not large enough to hold the entire LOB) and you are using the Instant Client 11.1 or later.

By default, OCI_UTF_Flag is turned off.

With_Unicode

When turned on (set to 1), the Easysoft ODBC-Oracle Driver attempts to detect whether the national character set for the current environment is AL16UTF16. If this is the case, the Easysoft ODBC-Oracle Driver:

Describes NCHAR, NVARCHAR2, or NCLOB columns as SQL_WCHAR, SQL_WVARCHAR, and SQL_WLONGVARCHAR, when describing columns in a result set.
Transfers data as 16-bit Unicode when binding parameters, if the SQL data type is SQL_WCHAR, SQL_WVARCHAR, or SQL_WLONGVARCHAR.

If the column type is one of the above, the column is bound to the implementation row descriptor (IRD) expecting the length returned and bound size to be in units of twin bytes.

To check what national character set the Easysoft ODBC-Oracle Driver has detected, set With_Unicode to 1, turn on Easysoft ODBC-Oracle Driver logging by adding the entry:

LOG = /tmp/oracle.log

to your data source, and then run a query against a table containing a NCHAR, NVARCHAR2, or NCLOB column. Look in the log file for text similar to:

Looking at column of type 1 with charset_id of 2000 against al16utf16_csid = 2000

If the charset_id and al16utf16_csid values don’t match, setting With_Unicode will have no effect.

By default, With_Unicode is turned off.

Pool_Type

The type of pooling required. This can be SESSION or CONNECTION.

Pool_Scope

This can be ENV or GLOBAL. This either associates the pool with the ODBC environment or makes it a global resource.

Pool_Initial

The number of sessions or connections that are created when the pool is created.

Pool_Max

The maximum number of sessions or connections that the pool can contain.

Pool_Increment

The number that the session or connection count is incremented by.

Pool_Username

The database user name with which to authenticate the sessions or connections.

Pool_Password

The password for Pool_Username.

Pool_Database

This database for which the pools are created.

Pool_Connection_Class

Database Resident Connection Pooling (DRCP) guarantees that pooled servers are never shared across different users. Setting Pool_Connection_Class allows for further separation between the sessions of a given user by defining a connection class. A connection class lets different applications (connecting as the same database user) identify their sessions using a logical name that corresponds to the application. OCI then ensures that sessions belonging to a particular connection class are not shared outside of the connection class.

OCI supports a maximum connection class length of 1024 bytes. The asterisk character (*) is a special character and is not allowed in the connection class name.

Pool_Purity

Whether the application requests a brand new session or reuses a session from the DRCP pool.

To request a new session, set Pool_Purity to NEW. The other value Pool_Purity supports is SELF.

If you connect to a DRCP-enabled database server without setting Pool_Purity, sessions are reused. When reusing a session from the pool, the NLS attributes of the server take precedence over that of the client.

XA_Connection_String

The name of the database specified with the DB field in the xa_open string. For example, you specify a database named payroll with the following xa_open string clause:

DB=payroll

You also need to specify payroll as the value for the XA_Connection_String attribute:

XA_Connection_String=payroll

XA_Connection_String is only necessary if you’re using the Easysoft ODBC-Oracle Driver to connect to Oracle in the context of an XA transaction and the Transaction Manager specifies a named database in the xa_open string.

XaoswName

Sets the XA entry point for the Easysoft ODBC-Oracle Driver. Note that this is set in the odbcinst.ini file, which is normally located in /etc. The default value is xaosw.

Data_Type_Map

How the Easysoft ODBC-Oracle Driver maps Oracle data types onto ODBC data types. The available maps are NUMERIC (set the attribute to 0), DOUBLE (set the attribute to 1), BIGINT+DOUBLE (set the attribute to 2), and BIGINT+NUMERIC (set the attribute to 3).

The default for Data_Type_Map is 0.

Data type maps

Value	Oracle data type	ODBC data type
0	NUMBER ⇐ 4 digits	SQL_SMALLINT
NUMBER ⇐ 9 digits	SQL_INTEGER
NUMBER = n digits	SQL_NUMERIC
NUMBER = n,m digits	SQL_NUMERIC
1	NUMBER ⇐ 4 digits	SQL_SMALLINT
NUMBER ⇐ 9 digits	SQL_INTEGER
NUMBER = n digits	SQL_DOUBLE
NUMBER = n,m digits	SQL_DOUBLE
2	NUMBER ⇐ 4 digits	SQL_SMALLINT
NUMBER = n digits	SQL_INTEGER
NUMBER ⇐ 19 digits	SQL_BIGINT
NUMBER n,m digits	SQL_DOUBLE
3	NUMBER ⇐ 4 digits	SQL_SMALLINT
NUMBER ⇐ 9 digits	SQL_INTEGER
NUMBER ⇐ 19 digits	SQL_BIGINT
NUMBER >9 digits	SQL_NUMERIC

Value

Oracle data type

ODBC data type

NUMBER ⇐ 4 digits

SQL_SMALLINT

NUMBER ⇐ 9 digits

SQL_INTEGER

NUMBER = n digits

SQL_NUMERIC

NUMBER = n,m digits

SQL_NUMERIC

NUMBER ⇐ 4 digits

SQL_SMALLINT

NUMBER ⇐ 9 digits

SQL_INTEGER

NUMBER = n digits

SQL_DOUBLE

NUMBER = n,m digits

SQL_DOUBLE

NUMBER ⇐ 4 digits

SQL_SMALLINT

NUMBER = n digits

SQL_INTEGER

NUMBER ⇐ 19 digits

SQL_BIGINT

NUMBER n,m digits

SQL_DOUBLE

NUMBER ⇐ 4 digits

SQL_SMALLINT

NUMBER ⇐ 9 digits

SQL_INTEGER

NUMBER ⇐ 19 digits

SQL_BIGINT

NUMBER >9 digits

SQL_NUMERIC

Setting on Windows

The Easysoft ODBC-Oracle Driver data source configuration dialog box, accessible when you create or edit an Easysoft ODBC-Oracle Driver data source in ODBC Data Source Administrator lets you configure your data source.

For information about the data source attribute fields the dialog box contains, refer to this topic.

DSN-less connections

Some applications allow you to make an ODBC connection without configuring a data source. To do this, you supply a connection string that contains the ODBC driver name and other driver-specific attribute-value pairs.

Here’s an example Easysoft ODBC-Oracle Driver connection string:

DRIVER=ORACLE;DB=my_database;UID=system;PWD=p455w0rd;

For a list of the other attributes you can set in the connection string, refer to this section.

Logging

If you report an issue to us, we may ask you to turn on ODBC Driver Manager or Easysoft ODBC-Oracle Driver logging, to help us diagnose the cause of the issue.

To turn on logging, refer to the following sections.

If your application is a service (for example, Oracle or SQL Server), you may need to restart the service before enabling logging takes effect. To do this on Linux or UNIX, use service, systemctl, or a vendor-supplied script. To do this on Windows, use the Windows Services app.

ODBC Driver Manager logging on Linux or UNIX

For the unixODBC Driver Manager, add the following attributes to the [ODBC] section (create one if none exists) in odbcinst.ini.

Trace = Yes
TraceFile = /path/filename

For example:

[ODBC]
Trace = Yes
TraceFile = /tmp/sql.log

Ensure that the user who’s running the application to log has write permission to TraceFile (and to the directory containing it), otherwise no logging information will be produced.

Easysoft ODBC-Oracle Driver logging on Linux and UNIX

Driver manager trace files show all the ODBC calls an application makes, including their arguments and return values. Easysoft ODBC-Oracle Driver logging is specific to the Easysoft driver and is of most use when making a support call.

To turn on Easysoft ODBC-Oracle Driver logging, edit your ODBC data source in odbc.ini. For example:

[demo-oracle]
.
.
.
LOG = /tmp/easysoft-odbc-driver.log

The value shown in the example specifies a log file named /tmp/easysoft-odbc-driver.log. Ensure that the user who’s running the application to log has write permission to the log file (and to the directory containing it), otherwise no logging information will be produced.

ODBC Driver Manager logging on Windows

In the Windows Taskbar Search box, enter “Run”.

Do one of the following:

If your application is 64-bit, in the Run dialog box, enter:
```
odbcad32.exe
```
-Or-

If your application is 32-bit, in the Run dialog box, enter:

%windir%\syswow64\odbcad32.exe

Choose the Tracing tab.
Select Machine-Wide tracing for all identities.
Enter a log file name and path in the space provided. For example:
```
C:\Windows\Temp\SQL.log
```
Choose Start Tracing Now.

With SQL Server, you may get two Driver Manager log files, we need both. The first log file is in the folder that you specify in ODBC Data Source Administrator. The second file’s location is defined by SQL Server. Two possible locations are the top-level folder (for example, C:\SQL.log) or the SQL Server temporary folder (for example, C:\Users\MSSQL$SQLEXPRESS\AppData\Local\Temp\SQL.log). If the Driver Manager log file isn’t in these folders, search for it on the drive where SQL Server is installed.

Finding out what product version you have on Windows

If you have an issue with the Easysoft ODBC-Oracle Driver, we may ask you to tell us what your product version is. To find this out:

In the Windows Taskbar, enter “Add or remove programs” in the Windows Search box.
Select Easysoft ODBC-Oracle Driver in the list.

The product version displays below.