Easysoft ODBC-Oracle Driver User Guide - Installation

Installing the Easysoft ODBC-Oracle Driver

This section explains how to install, license and remove the Easysoft ODBC-Oracle Driver on supported Windows and Unix platforms.

The Windows installation can be carried out by anyone with local administrator privileges for the target machine.

The Unix installation assumes you are, or have available for consultation, a system administrator.

Chapter Guide

Obtaining the Easysoft ODBC-Oracle Driver

There are three ways to obtain the Easysoft ODBC-Oracle Driver:

Select Download from the Easysoft ODBC-Oracle Driver section of the website and then choose the platform release that you require.

First time visitors must complete the new user form and click Register. Note that your personal Internet options may require you to login and click Continue if you have previously registered.

Change to the pub/oracle directory and then choose the platform release that you require.

What to install

The name of the Easysoft ODBC-Oracle Driver install file varies from platform to platform, but is of the form:

¯ OR ¯

where "x" is the major version number, "y" is the minor version number and "z" is the build index, which is incremented when fixes are applied to previous releases.

"platform" will vary depending on the operating system distribution you require and there are some variations of the form:

within specific Unix platforms, where "variation" refers to alternative versions available for a single platform.


Select the highest release available for your platform within your licensed major.minor version number (installing software of a different major.minor version number requires a new Easysoft license).

Unix filenames may also be suffixed with .gz for a "gzipped" archive, .bz2 for a "bzip2ed" archive, or .Z for a "compressed" archive.


If you download a Unix file in Windows, the browser may alter the filename. For example, if you download a .gz file it may not be obvious that the file is "gzipped". Use "filefilename" to find out the file type of the downloaded file.

You can now download a file and begin the installation process.


As long as you stop all running applications (under Windows), or any software either from Easysoft or using Easysoft drivers (under Unix), it is safe to reinstall or upgrade the Easysoft ODBC-Oracle Driver without uninstalling.

If you do uninstall, you should first back up any configuration data that you still need, as uninstalling some Easysoft products will result in this information being deleted (license details remain in place).

Refer to the section relevant to your platform to continue:

Installing on Windows

1.  Execute the file distribution that you downloaded in Obtaining the Easysoft ODBC-Oracle Driver.


Please shut down other Windows programs before installing. In particular, Microsoft Outlook can cause the installation routine to pause for several minutes when you start it.

There will be a short delay while setup prepares the wizard to guide you through the rest of the install procedure before the Welcome dialog box is displayed:

Figure 4: The Welcome dialog box

2.  Click Next when you have read the Welcome dialog box.

 The Information dialogue box is displayed:


Figure 5: The Information dialog box

3.  Click Next to continue

 The User Information dialog box is displayed:


Figure 6: The User Information dialog box

4.  Enter your name and the name of your company. Then click Next to continue.


The name and company that you enter here will become the defaults in the License Manager later on.

 The Choose Destination Location dialog box is displayed, where you are asked to choose where to install the Easysoft ODBC-Oracle Driver files:


Figure 7: The Choose Destination Location dialog box

5.  Click Next to install the application into the default directory location:

 C:\Program Files\Easysoft\Easysoft ODBC-Oracle Driver.

¯ OR ¯

 Click Browse and select an alternative directory location for the installation, before clicking Next.

 The Easysoft End User licensing details are displayed in the Software License Agreement dialog box:

Figure 8: The License Agreement dialog box

 You are required to accept the terms of the License Agreement before continuing.

6.  Click Next to continue.

 The Start Copying Files dialog box is displayed, containing a summary of the settings you have chosen:

Figure 9: The Start Copying Files dialog box

7.  Click Next.

 There is now a short wait while the relevant Easysoft ODBC-Oracle Driver components are copied and configured.

Licensing on Windows

The install program now starts the Easysoft License Manager (explained fully in the Licensing Guide).


Figure 10: The License Manager dialog box

 The following types of license are available:

8.  Enter your contact details.

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

 The Telephone and Facsimile fields are important if you require Easysoft to contact you by those methods.

 The E-Mail Address must be the same as the address used to register and download from the easysoft web site or you will be unable to obtain trial licenses.

9.  Click Request License.

 You are asked for a license type:

Figure 11: The License Type dialog box

 The next step depends on the type of license you want.

10.  For a trial license click Time Limited Trial and then click Next.

 The License Manager asks what software you are licensing:

Figure 12: Select the product you are licensing

 Select the Easysoft ODBC-Oracle Driverfrom the drop-down list and then click Next.

¯ OR ¯

 If you have obtained an authorization code for a purchased license, select Non-expiring License and then click Next. The License Manager requests your authorization code.

Figure 13: The Authorization Number dialog box

 Enter the authorization code and then click Next.

11.  The License Manager displays a summary of your details and allows you to choose the method of applying for your license:

Figure 14: The License Application dialog box

Choose On-line Request if your machine has a connection to the internet.

The License Manager then sends a request to the Easysoft license server to activate your license key automatically. This is the quickest method and results in your details being entered immediately into our support database. The whole process is automatic so you can proceed to step 12.


Only your license request identifier and contact details as they are displayed in the main License Manager screen are sent to Easysoft.

The remaining three options (Email Request, Print Request and View Request) are all methods to obtain a license if your machine is offline (i.e. does not have a connection to the internet).

Each of these methods involves providing Easysoft with information including your site number (a number unique to your machine) and then waiting to receive your license key.

Instead of emailing, faxing or telephoning your details to Easysoft, you can enter them directly onto the Easysoft web site and your license key will be emailed to you automatically.

To use this method, click View Request to display your site number, then go to a web browser. Choose the type of license you require, enter your site number, click Continue and the license key will be emailed to you.


You can copy your site number from the View Request dialog box using CTRL-C and then paste it into the License Generator by using CTRL-V.

When you receive the license key, you can activate it either by double-clicking the email attachment or by clicking Enter License on the License Manager main screen and pasting the license key into the dialog box.

12.  A message tells you how many licenses have been added..


If you use the Email Request option, the license key is emailed to the email address as displayed on the License Manager screen, not the from: address of your email.

For more information about licensing refer to the Licensing Guide.

13.  Click Finish in the License Manager to return to the install.

 The Setup Complete dialog box is displayed:

Figure 15: The Setup Wizard Complete dialog box

14.  If InstallShield couldn't replace shared Easysoft .dll or .exe files because they were in use, you will be prompted whether you want to restart your PC. If this happens, you must restart your PC before using the Easysoft ODBC-Oracle Driver.

15.  Click Finish.

 The installation is complete.

 You should have a new Easysoft ODBC-Oracle Driver program group with a link to this user guide.


Uninstalling on Windows

1.  Select Start > Settings > Control Panel and then double-click the Add/Remove Programs icon.

 A list is displayed of applications that can be automatically removed.

2.  Select Easysoft ODBC-Oracle Driver and click Add/Remove or Change/Remove).

3.  Click Yes to confirm that you wish to remove the Easysoft ODBC-Oracle Driver and all its components.

 The system begins to remove all the components. If shared components seem not to be required, you will be prompted to decide whether or not to delete them.


The Windows install/uninstall procedure incorporates a mechanism in the registry to determine whether or not shared files are still required by other programs. Sometimes this database can become out-of-date if a user deletes an application directly without using Add/Remove Programs or if the registry is `repaired' after a system crash.

4.  If you feel confident with the registry (i.e. your system has had relatively few programs installed and removed) you should click Yes or Yes to All to continue.

¯ OR ¯

 If you have any doubts (e.g. uninstall procedures have failed in the past) you should click No or No to All.

 The uninstall process removes the Easysoft ODBC-Oracle Driver components from your system.

5.  On completion, click OK to go back to the Control Panel Install/Uninstall window.

6.  The uninstall process is complete.

Any licenses you obtained for the Easysoft ODBC-Oracle Driver and other Easysoft products are held 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.

Installing on Unix

Although this section covers a range of platforms and the precise output may vary from system to system, the installation process is essentially the same.

Installation requirements

The Unix installation routine has the following requirements:

If any of these commands are missing they can be obtained from the Free Software Foundation (


1.  Log on to your Unix machine as the root user.

2.  Download the Easysoft ODBC-Oracle Driver (see Obtaining the Easysoft ODBC-Oracle Driver).

3.  Place the distribution file in a temporary directory on your Unix machine.

Extracting the installation files

4.  Change to the directory in which the distribution file resides.

5.  Uncompress the installation files from the distribution file:

 If the distribution file has been gzipped (i.e. the filename ends in .gz), then use:

 gunzip odbc-oracle-x.y.z-platform.tar.gz

¯ OR ¯

If the distribution file has been bzip2ed (i.e. the filename ends in .bz2), then use:

 bunzip2 odbc-oracle-x.y.z-platform.tar.bz2

¯ OR ¯

If the distribution file has been compressed (i.e. the filename ends in .Z), then use:

 uncompress odbc-oracle-x.y.z-platform.tar.Z

6.  You should now have an uncompressed tar file ending in a .tar extension and this is now ready for extraction:

 tar -xvf odbc-oracle-x.y.z-platform.tar

 The tar program creates a directory of the same name as the tar file (without the final .tar) containing further archives, checksum files, a script called install and a text file called INSTALL.txt.

 It also contains a versioned directory to ensure that any shared components already installed by other Easysoft products are only overwritten if those included in this distribution are newer.


If you do not wish to keep the original downloaded distribution file you can now delete it safely.

 Change into the newly-created odbc-oracle-x.y.z-platform directory.


Check through the INSTALL.txt file before continuing. It gives full installation instructions for the Unix-literate, and if you are confident in the use and administration of your system, you can follow the instructions in the INSTALL.txt file instead of working through the remainder of this section.

7.  There are copies of the license agreement file provided in the archive.


You must read and accept the terms of the license to use the software. The license text can be found in the file license.txt,be sure to understand the terms before continuing.

Beginning the Installation

8.  Type:



During the installation, you are asked to answer some questions. The default reponse is displayed in square brackets [], which you can press <Enter> to accept or you can choose any of the alternative responses shown in round brackets () by typing the required response and then pressing <Enter>.

Occasionally, the install program pauses to give you time to read the information displayed on screen. Press <Enter> to continue when you have read the current screen of information.

9.  If the installation locates a program which can display the license (e.g. your PAGER environment variable is set or 'more' or 'less' is found) then the license will be displayed and you will need to page to the end and quit the pager program. Once you have read and agree to the Easysoft License Agreement, type yes and then press <Enter> to continue.


You must type yes, not y, to continue.

10.  The script pauses to allow you to read its output so far. Up to this point it has checked the following:

11.  Press <Enter> to continue.

 The script checks the archive package, with three possible outcomes:

12.  If the check failed because of missing components, enter y to continue regardless or n to quit and investigate the missing components.

¯ OR ¯

 If the check was carried out and the files failed then the files have been damaged.


¯ OR ¯

 call the Easysoft support team (see Contact Details for more information).

 If the files passed the check or you continued then you are next asked for a directory in which to place the easysoft installation directory tree.

13.  Specify the directory into which the Easysoft ODBC-Oracle Driver is to be installed.

 The default is /usr/local, which would be the normal location to install software for system-wide use.

 If you wish to install the software in another directory then specify an alternative path here.

 If you have any other Easysoft products already installed, then choose the same directory that you chose for the other Easysoft product(s).

 The installation script will create a directory called easysoft under the directory you specify here, into which all Easysoft ODBC-Oracle Driver files will be placed

 For example, if you accept the default path of /usr/local, the files are installed into /usr/local/easysoft.



The installation script can accept a path to a directory that does not exist, provided a parent directory exists. For example, if the directory /usr/local exists on your machine, the script can accept the non-existent directory /usr/local/odbc and will create it, but will not create /usr/local/odbc/odbc-oracle. The script always creates an easysoft directory beneath the specified path.

14.  The script now creates the easysoft directory under the directory you specified. If your chosen directory does not exist, you will be asked whether or not the script should create it. Enter y or n.



If you are upgrading to a later major or minor release the installation will warn you that you will need a new license to use this release. If you have not got a license or authorisation code which matches this distribution you should abort the installation until you have obtained them.


 If the chosen directory already contains an easysoft directory, the script warns that you may be installing over a previous Easysoft ODBC-Oracle Driver installation (this can also arise if you have another Easysoft product installed).

 Normally you should continue with the installation to install into the existing easysoftdirectory. Enter y or n.

 If you chose a directory other than /usr/local the script creates a symbolic link /usr/local/easysoft, pointing to the easysoft directory in the path you specified, in order to ensure that licensing will work.

15.  Press <Enter> to continue.

Installing unixODBC

The Easysoft ODBC-Oracle Driver requires unixODBC to be installed and if unixODBC is not already present, the script offers to install the copy of the unixODBC driver manager contained in the Easysoft ODBC-Oracle Driver distribution.


The entire unixODBC source distribution may also be downloaded from and installed independently.

The unixODBC driver manager enables an ODBC application to load whichever driver is required to access the data source at runtime.


unixODBC is an open source project sponsored by Easysoft and other industry members. It is rapidly becoming the standard driver manager across the Unix data access community. Comprehensive documentation can be found at

 If unixODBC is already installed, the installation script can use your existing unixODBC, but you should bare in mind the following possible complications of doing this:

 Easysoft ODBC-Oracle Driver distributions contain matched builds of unixODBC and the Easysoft ODBC-Oracle Driver, so installing the incorporated unixODBC build is often the safest policy.

16.  Press <Enter> to continue and then choose whether to install unixODBC.

17.  If you do not wish to install the version of unixODBC included with this distribution, enter y and skip toLicensing on Unix.

¯ OR ¯

 If you wish to install unixODBC, enter n at the prompt.

18.  The script pauses at this point. Press <Enter> to continue.

 The script extracts the unixODBC files.


Depending on your platform this installation of the unixODBC driver manager may not contain the GUI components of unixODBC.

Licensing on Unix

19.  You are now asked if you want to obtain a license. Accept the default [y] to start the licensing procedure.

 A menu of options is displayed.

20.  Choose the option to license the Easysoft ODBC-Oracle Driver.

 You will then be asked to provide some contact information.

21.  Enter your Name.

22.  Enter your Company Name.

23.  Enter at least one of Email, Phone and Fax (preferably all three). If you are obtaining a license automatically over the internet then you must supply the email address you used to register on the Easysoft web site.

24.  At the Ref prompt, do either of the following:

25.  The License Manager displays a menu of licensing options.

 If you have an internet connection you should select 1, Automatic (this is the quickest and easiest method unless your firewall prevents the message from getting through).

¯ OR ¯

 If you do not have an internet connection, or the Automatic option fails, select option 2 to write the required information to a text file in the current working directory called license_request.txt, which you will then need to view to obtain a license.

26.  The License Manager displays the menu again. Select 0 to exit.


The View Existing Licenses option will not display any license you obtained during this License Manager session. You must quit the License Manager and allow the install script to finish applying the license.

 If you chose the automatic licensing method and licenses are retrieved, the licensing script outputs them to a file called licenses.out.

 If the install script detects possible new licenses in the file licenses.out it asks whether you want to add them to the license database.

27.  If you obtained licenses and you want to add them now, enter y.

¯ OR ¯

 If you did not obtain licenses, enter n.

¯ OR ¯

 If you do not see this message, then read on. You will need to complete the offline licensing procedure as explained in Completing the offline licensing procedure.

Configuring the Easysoft ODBC-Oracle Driver in unixODBC

 If unixODBC was installed as part of this installation, or unixODBC was found to be already installed, the script will offer to configure the Easysoft ODBC-Oracle Driver under unixODBC.

 This allows any ODBC application which uses the unixODBC driver manager to connect to data sources using the Easysoft ODBC-Oracle Driver.

 You are asked to the enter the details needed to create a data source for the Easysoft ODBC-Oracle Driver.

28.  Enter an Oracle® database name.

29.  Enter a user name and password.

30.  The installation needs unixODBC's odbcinst to install the Easysoft ODBC-Oracle Driver and data source.

 If the odbcinstprogram is not in its expected location, you are asked to provide the directory into which unixODBC was installed.

 If you do not know the answer, enter q to abandon the attempt to configure unixODBC and skip to Completing the offline licensing procedure.

¯ OR ¯

 If known, supply the unixODBC install path.

31.  The script checks whether the Easysoft ODBC-Oracle Driver has already been defined under unixODBC. If the unixODBC driver manager has already been configured for the Easysoft ODBC-Oracle Driver then a warning is given.


If unixODBC has been previously configured with the Easysoft ODBC-Oracle Driver then it will continue to access the Easysoft ODBC-Oracle Driver software from the directory in which it was originally installed.

If the current install directory is different then unixODBC will pick up the old version of the Easysoft ODBC-Oracle Driver, resulting in incorrect behavior.

32.  The script now offers to install the ODBC data source you provided details for into unixODBC as a system data source. Enter y to install this data source and unixODBC's odbcinst will be used to add the data source.


The messages "Target directory is /usr/lib" and "added to ODBC.INI" displayed whilst the odbcinst script is running are inaccurate and should be ignored.

¯ OR ¯

 enter n to skip and add your data source yourself.

33.  If the installation fails to install the Easysoft ODBC-Oracle Driver or the data source into unixODBC, refer to the unixODBC documentation for details of how to manually reconfigure the driver manager.


Comprehensive unixODBC documentation can be found at

The settings that the install script attempted to set can be found in the file unixODBC.template.

34.  A message informs you that the Easysoft ODBC-Oracle Driver has been installed.

Completing the offline licensing procedure

If at step 25 you chose to write the licensing information to a file, you still need to complete the licensing procedure before the Easysoft ODBC-Oracle Driver can be used.

The licensing information is written to the license_request.txtfile, which contains information including a site number (a number unique to your machine) that Easysoft requires before you can be issued with a license key.

1.  Do any one of the following:

2.  When you receive your license key(s), append them to the file /usr/local/easysoft/license/licenses, removing any LIC: prefixes.


The Easysoft license responder puts an attachment in its outgoing emails that allows Windows users to activate their licenses with a double-click. If you read your email in Windows, this attachment will be visible but it will not work for licensing Unix versions of the software.

 The Easysoft ODBC-Oracle Driver is now licensed and you can begin using it.

If you need further information about licensing, please refer to the Licensing Guide.

Uninstalling on Unix

To uninstall the Easysoft ODBC-Oracle Driver under Unix:

A step-by-step guide follows:

1.  Log in as root.

Removing from unixODBC

2.  Check whether the Easysoft ODBC-Oracle Driver is configured under unixODBC by typing:

 odbcinst -q -d

3.  If "Oracle®" is returned in the output then remove the Easysoft ODBC-Oracle Driver entry by typing:

 odbcinst -u -d -n Oracle®

 If a message is displayed about a reduced usage count, repeat this step until odbcinst states that the Easysoft ODBC-Oracle Driver has been removed.


If unixODBC is no longer required then the odbcinst.iniand odbc.ini files can be removed.

Removing from the dynamic linker

 Notify the dynamic linker that the shared objects are no longer available.


This information only applies to systems with the dynamic linker (normally only Linux).

4.  If the file /etc/ file exists, make a backup copy and open it.

5.  Remove the path to the Easysoft ODBC-Oracle Driver shared objects:


6.  If no other Easysoft software is in use then remove the path to the common Easysoft shared objects:


7.  If unixODBC is no longer required then remove the reference:


8.  Run /sbin/ldconfig so that the dynamic linker re-reads the file and will no longer search the removed paths.

Deleting the Software

 Finally, remove the software from the system hard drive.

9.  Change directory to:



 The system displays the current directory.

 Double-check that this is the directory under which you installed the Easysoft ODBC-Oracle Driver.


Be very careful issuing the rm -r command as root. rmdir will not remove directories that contain files, but rm -r will remove all subdirectories along with their contents. It is possible to destroy your system and/or lose all user files by removing the wrong directory.

10.  Remove the Easysoft ODBC-Oracle Driver installation directory:


 Check that you are in the right directory.

 rm -r Oracle®

 The system may ask you to confirm deletion for some files. You can confirm these as long as you are sure you are in the correct directory.


11.  If you have no other Easysoft products on your system and you are not using any copy of unixODBC that may be in this directory, then you can delete the easysoft directory too.

 cd ..

 rm -r easysoft

¯ OR ¯

 If there are other files in the directory tree (i.e. you have other Easysoft products installed) then you must not remove the easysoft directory, because it will contain your license keys and other important files.

12.  If you left the Easysoft ODBC-Oracle Driver distribution file on your system then you may wish to remove it at this point.

The uninstall process is complete.

Any licenses you obtain for the Easysoft ODBC-Oracle Driver and other Easysoft products are stored in the <InstallDir>/easysoft/license/licenses file.

After uninstalling the Easysoft ODBC-Oracle Driver, unless you have deleted this file, you will not need to relicense the product when you reinstall or upgrade.

However, for security purposes you may want to make a copy of <InstallDir>/easysoft/license/licenses before uninstalling.

Copyright Notice

Oracle is a registered trademark of Oracle Corporation and/or its affiliates.