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.
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 machine as the Easysoft ODBC-Oracle Driver.
Although the Easysoft ODBC-Oracle Driver is compatible with both Oracle clients, Easysoft recommend that you use our driver with the Instant Client. This is because the Instant Client:
Is available for Oracle 10g, Oracle 11g and Oracle Database XE and backwards-compatible with Oracle 8, Oracle 9i.
1. Log in at http//www.oracle.com.
If you have not yet done so, you need to register first. You need to be a registered Oracle user to download the Instant Client.
2. Choose the Instant Client for your database and client platform at:
http://www.oracle.com/technology/tech/oci/instantclient/index.html
Download the Basic and SQL*Plus Instant Client Packages.
These packages contain the Instant Client and a version of SQL*Plus that is compatible with the Instant Client. SQL*Plus lets you test that you can access Oracle with the Instant Client
.
On the machine from which you want to access Oracle, extract the Instant Client and SQL*Plus files
.
3. Change to the directory where you extracted SQL*Plus. Then use SQL*Plus to test that you can access Oracle:
sqlplus username/password@//machine_name:port/database_name
4. At the prompt, type a SELECT statement to test that you can retrieve some data:
For information about how to obtain the standard Oracle client, see:
http://www.easysoft.com/support/kb/kb00612.html
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.
The name of the Easysoft ODBC-Oracle Driver install file varies from platform to platform, but is of the form:
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.
You can now download a file and begin the installation process.
Refer to the section relevant to your platform to continue:
Follow the on screen instructions.
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.
On Windows Vista, the Easysoft ODBC-Oracle Driver 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 the Restart Manager to try to stop and restart each application or service in the list. If possible, the Restart Manager restores applications to the same state and with the same data that they were in before it shut them down.
On earlier versions of Windows, when the Files in Use dialog is displayed, manually shut down each application in the list and then click Retry to avoid a system restart.
The install program starts the Easysoft License Manager (documented in the Licensing Guide).
The following types of license are available:
1. 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.
You are asked for a license type:
The next step depends on the type of license you want.
3. For a trial license click Time Limited Trial and then click Next.
The License Manager asks what software you are licensing.
Select the Easysoft ODBC-Oracle Driver from the drop-down list and then click Next.
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.
Enter the authorization code and then click Next.
The License Manager displays a summary of your details and allows you to choose the method of applying for your license:
4. Choose On-line Request if your machine is connected to the internet and can make outgoing connections to port 8884
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 .
|
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 machine 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 at the Easysoft web site and your license key will be emailed to you automatically.
To use this method, click View Request, and then visit:
In the Licensing page, enter your machine number (and authorization code for purchased license), click Submit and your license key will be emailed to you
|
You can copy your machine 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.
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.
5. Click Finish in the License Manager.
You should have a new Easysoft ODBC-Oracle Driver program group with a link to this user guide.
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.
Easysoft ODBC-Oracle Driver data sources are not removed when you uninstall. You therefore do not need to recreate your Easysoft ODBC-Oracle Driver data sources if you reinstall or upgrade. If you do not want to keep your Easysoft ODBC-Oracle Driver data sources, use ODBC Administrator to remove them, before uninstalling the Easysoft ODBC-Oracle Driver.
1. In Control Panel, double-click Administrative Tools and then Data Sources (ODBC).
2. Select the data source in the ODBC Administrator and click the Remove button.
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.
These instructions show how to install the Easysoft ODBC-Oracle Driver on Unix and Linux platforms.
The installation script has a minimal set of requirements:
grep, awk, test, cut, ps, sed, cat, wc, uname, tr, find, echo, sum, head, tee, id
If you are missing any of these commands, they can generally be obtained from the Free Software Foundation (http://www.fsf.org). As some machines have a broken tee command, the distribution comes with a tee replacement.
a) Install in /usr/local/easysoft.
b) Install 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.
c) Install elsewhere and set the EASYSOFT_ROOT environment variable. See Post Installation.
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 (only some platforms).
If you are not root, these tasks will have to be done manually later. Easysoft recommend you install all components as the root user.
You will need an ODBC driver manager to use the driver from your applications. This distribution contains the unixODBC driver manager (see www.unixodbc.org). Most (if not all) Unix applications and interfaces (for example, Perl DBD::ODBC, PHP and Python) support the unixODBC driver manager.
You do not have to install the unixODBC driver manager in this distribution as you can use an already installed unixODBC (whether that was installed with another Easysoft product, from your operating system vendor or even if you built it yourself). However, Easysoft ensure the unixODBC distributed with Easysoft ODBC drivers has been tested with our drivers so we recommend you use it.
If you choose to use an already installed unixODBC driver manager the installation script will attempt to locate it. The installation looks in the standard places but if you have installed it in a non-standard location you will need to provide that location to the installation script when it prompts you. The installation primarily needs unixODBC's odbcinst command to install drivers and any data sources.
This installation needs a location for the installed files. The default is /usr/local.
At the start of the installation, you will be prompted for an installation path. All files are installed in a subdirectory of your specified path called "easysoft" For example, if you pick the default of /usr/local, the product will be installed in /usr/local/easysoft and below.
If you choose an install path different from the default, the installation will try to symbolically link /usr/local/easysoft to the easysoft in your chosen path. 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 this will fail (see later for how this may be corrected manually). You should note that you cannot license Easysoft products until either of the following is true:
This installation installs files in subdirectories of the path requested at the start of the installation and depending on what is installed a few changes may be made to your system as outlined below:
1. If you choose to install this 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 will be in install_path/easysoft/unixODBC/bin) if you are using the unixODBC in this distribution.
The entry for this driver will look similar to this:
Description = Easysoft ODBC-Oracle Driver
Driver = /usr/local/easysoft/oracle/libesoracle.so
Setup = /usr/local/easysoft/oracle/libesoraclesetup.so
Obviously, the paths depend on where you installed this software.
See Uninstalling on Unix for ways to remove this.
2. The installation installs an example data source into unixODBC. This entry will be added to your SYSTEM odbc.ini file. You can locate your SYSTEM odbc.ini file using odbcinst -j. The entry will look similar to this:
Database = //my_database_host:1521/my_database_service_name
If you are using the standard Oracle Client, the Database attribute value for this data source will look similar to this:
See Uninstalling on Unix for ways to remove this data source.
On operating systems where the dynamic linker has a file specifying locations for shared objects (Linux, FreeBSD), the installation will attempt to add paths under the path you provided at the start of the install to the end of this list.
On Linux, this is generally the file /etc/ld.so.conf.
On FreeBSD, this is generally the file /etc/defaults/rc.conf.
Each Easysoft distribution contains common files shared between Easysoft products. These shared objects are placed in install_path/easysoft/lib. When you run an installation, the dates and versions of these files will be compared with the same files in the distribution and 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 because on some platforms, files in use cannot be replaced. If a file cannot be updated, you will see a warning during the installation. You may review all warnings after the installation in the file called "warnings" in the directory you unpacked the distribution into.
If the installer detects you are 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.
During the installation you will be prompted for various information.
Before installing, you should determine:
The distribution for Unix platforms is distributed as a tar file. There are multiple copies of the same distribution with different levels of compression. You unpack the distribution as follows.
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
If the distribution file has been bzipped (i.e. the filename ends in .bz2), then use:
bunzip2 odbc-oracle-x.y.z-platform.tar.bz2
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
You may have a distribution file that is not compressed at all (i.e. the filename ends in .tar).
To extract the installation files from the tar file use:
tar -xvf odbc-oracle-x.y.z-platform.tar
This will create a directory with the same name as the tar file (without the .tar postfix) containing further archives, checksum files, an install script and various other installation files.
Change directory into the directory created by unpacking the tar file.
The license text can be found in the file license.txt and be sure to understand the terms before continuing, as you will be required to accept the license terms at the start of the installation.
Throughout the installation you will be asked to supply the answer to some questions. In each case the default will be displayed in square brackets and you need only press <Enter> to take the default. If there are alternative responses these will be shown in round brackets; to pick one of these type them 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 when you enter nothing and press <Enter> is "n".
Before you run the installer, make sure you have read Before you Install. 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. Easysoft recommend installing as the root user (if you are concerned about the changes that will be made to your system see Changes Made to your System).
To start the installation run:
|
If you are upgrading, you will need a new license from Easysoft. |
Easysoft strongly recommend you use the unixODBC driver manager because:
The installation will start by searching for an installed unixODBC.
There are two possible outcomes here:
1. If unixODBC is located a message will be output saying:
Found unixODBC under /path_to_unixODBC and it is version n.n.n
If unixODBC is not found in the standard places, you will be asked whether you have it installed.
If you have it installed, you need to provide the argument given to unixODBC's configure as --prefix. i.e. if you built unixODBC with "configure --prefix=/usr/local/unixODBC" you enter "/usr/local/unixODBC". Generally the path required is the directory above where odbcinst is installed i.e. if odbcinst is in /opt/unixODBC/bin/odbcinst the required path is /opt/unixODBC.
If you have not got unixODBC installed, you should install the unixODBC included with this distribution.
If you already have unixODBC installed, you do not have to install the include unixODBC but you might consider doing so if your version is older than the one included.
The unixODBC in this distribution is not built with the default options in unixODBC's configure line:
This means the default SYSTEM odbc.ini file where SYSTEM dsns are located will be /etc/odbc.ini.
This means other ODBC drivers that come with unixODBC are not installed.
This means unixODBC will not look for a libiconv. Warnings about not finding an iconv library were confusing our customers.
Disables unixODBC statistics which uses system semaphores to keep track of used handles. Many machines do not have sufficient semaphore resources to keep track of statistics and they are only available in the GUI ODBC Administrator anyway.
This disables readline support in isql. We disabled this because it ties isql to the version of libreadline on the machine we build on. We build on as old a version of the operating system we can for upwards compatibility. Many newer Linux machines no longer come with the older readline libraries and so enabling readline support renders isql unusable.
This installs unixODBC into /usr/local/easysoft/unixODBC.
The Easysoft ODBC-Oracle Driver installation comprises of:
If unixODBC is now installed (either installed by this installation or an existing copy was found) the Easysoft ODBC-Oracle Driver will be registered as an ODBC driver with the unixODBC driver manager.
If you already have the Easysoft ODBC-Oracle Driver registered with unixODBC, you will see a warning that it is already registered and a list of the drivers unixODBC knows about. If you are installing the Easysoft ODBC-Oracle Driver into a different directory than it was installed before, you will need to edit your odbcinst.ini file after the installation and correct the Driver and Setup paths as unixODBC's odbcinst will not update them if a driver is already registered.
If unixODBC is installed and you registered the Easysoft ODBC-Oracle Driver with unixODBC, an example data source will be added to your odbc.ini file.
If a data source called "ORACLE" already exists, the existing data source will be displayed and you have the option to replace it.
The program install_path/easysoft/license/licshell is used to obtain or list licenses.
Licenses are stored in the file install_path/easysoft/license/licenses. After obtaining a license, you should take a copy of this file in case something happens to it.
When you install, the installation will ask 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 yes to this, the installation will run the licshell script. The process of obtaining a license is best described in the Licensing Guide and on the Easysoft web site.
To obtain a license automatically, you will need to be connected to the Internet and allow outgoing connections to license.easysoft.com on port 8884. If you are not connected to the Internet or do not allow outgoing connections on port 8884 then the License Client can create a license request file which you can:
1. Enter in the License Request pages, accessible from the Licensing section of this web page: http://www.easysoft.com/support.
2. Mail, fax or telephone to Easysoft.
Obviously, option 1 is quickest if you have a web browser and access to the Internet.
Once the License Client has started you are presented with a menu of options which allow you to:
[n] obtain a license for the desired product.
Obviously, if you have not got any other Easysoft products licensed then option [1] will not show any existing licenses.
To obtain a license, select one of the options from [2] onwards for the product you are installing. The License Client will then run a program that was installed for that product which generates a key that is used to identify the product and operating system (we need this key to license you).
Once you have picked the product to license (Easysoft ODBC-Oracle Driver), you need to supply:
3. An email contact address. This (currently) must be the email address you registered on the Easysoft web site.
4. Your telephone number (you need to specify this if you telephone the license request to us).
5. Your fax number (you need to specify this if you fax the license request to us).
6. A reference number. When applying for a trial license just press <Enter> on this field as this field is used to enter a reference number we will supply you for full (paid) licenses.
You will then be asked for a method of obtaining the license where the choices are:
[1] Automatically by contacting the Easysoft License Daemon (this requires connection to the Internet and the ability to support an outgoing TCPIP connection to license.easysoft.com on port 8884).
[2] Write information to file so you can:
a) Obtain your license from the License Request pages on the Easysoft web site. (Accessible from the Licensing section of this web page: http://www.easysoft.com/support.)
The license request is output to license_request.txt.
If you choose to obtain the license automatically, the License Client will start a TCPIP connection to license.easysoft.com on port 8884 and send the details you entered at the prompts above and your machine number. No other data is sent. The data sent is transmitted as plain text so if you do not want this information possibly intercepted by someone else on the net you should choose [2] and telephone or fax the request to us. The License daemon will return the license key, print 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 and you should exit the License Client via option [0] and complete the installation. Once you have mailed, faxed or telephoned the license request to us we will return a license key which should add to the end of the file install_path/easysoft/license/licenses.
If during this process any warnings or errors are output, please mail the output to support@easysoft.com and we will rectify the problem.
The last part of the installation runs a post install script that lists resources available to you.
Included documentation is installed in install_path/easysoft/oracle/doc.
There are many resources at the Easysoft web site (http://www.easysoft.com).
If you installed the Easysoft ODBC-Oracle Driver as a non root user (not recommended), there may be some manual steps you will need to perform:
1. 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 cannot be added.
You can manually install the driver under unixODBC by adding an entry to the odbcinst.ini file. Run odbcinst -j to ascertain the DRIVERS file then append the lines from the drv_template file (in the directory where the distribution was untarred to) to the odbcinst.ini file.
2. As in step 1, no example dsns can be added into unixODBC if you do not have write permission to the SYSTEM odbc.ini file. Run odbcinst -j to ascertain the name of the "SYSTEM DATA SOURCES" file then add your DSNs.
3. On machines where the dynamic linker has a configuration file, defining the locations where it looks for shared objects (Linux/FreeBSD) you will need to add:
install_path/easysoft/unixODBC/lib
The latter one 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).
4. If you did not install the Easysoft ODBC-Oracle Driver in the default location, you need to do one of the following:
a) Link /usr/local/easysoft to the easysoft directory in your chosen install path. For example, if you installed in /home/martin the installation will create /home/martin/easysoft and you need to symbolically link /usr/local/easysoft to /home/martin/easysoft:
ln -s /home/martin/easysoft /usr/local/easysoft
b) Set and export the EASYSOFT_ROOT environment variable to install_path/easysoft
5. If your system does not have a dynamic linker configuration file, you need to add the paths listed in step 3 above to whatever environment path the dynamic linker uses to locate shared objects. You may want to amend this in a system file run whenever someone logs in like /etc/profile.
The environment variable differs per dynamic linker. Consult your ld or ld.so man page. It is usually:
LD_LIBRARY_PATH, LIBPATH, LD_RUN_PATH or SHLIB_PATH.
To uninstall the Easysoft ODBC-Oracle Driver under Unix:
2. Check whether the Easysoft ODBC-Oracle Driver is configured under unixODBC by typing:
3. If "ORACLE" is returned in the output then remove the Easysoft ODBC-Oracle Driver entry by typing:
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.ini and odbc.ini files can be removed. |
Notify the dynamic linker that the shared objects are no longer available.
|
This information only applies to systems with the ld.so dynamic linker (normally only Linux). |
4. If the file /etc/ld.so.conf 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:
<InstallDir>/easysoft/unixODBC
8. Run /sbin/ldconfig so that the dynamic linker re-reads the file and will no longer search the removed paths.
Finally, remove the software from the system hard drive.
The system displays the current directory.
Double-check that this is the directory under which you installed the Easysoft ODBC-Oracle Driver.
10. Remove the Easysoft ODBC-Oracle Driver installation directory:
Check that you are in the right directory.
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.
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.
© 1993 - 2024 Easysoft Limited. All rights reserved. Oracle® is a registered trademark of Oracle® Corporation and/or its affiliates. Other trademarks and registered trademarks appearing on easysoft.com are the property of their respective owners.
