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.
Obtaining the Easysoft ODBC-Oracle Driver
There are three ways to obtain the Easysoft ODBC-Oracle Driver:
- The Easysoft web site is available 24 hours a day at http://www.easysoft.com for downloads of definitive releases and documentation.
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.
- The Easysoft FTP server is available 24 hours a day at ftp://ftp.easysoft.com, containing upgrades, documentation and beta releases of Easysoft products, as well as definitive releases.
Change to the pub/oracle directory and then choose the platform release that you require.
- You can order Easysoft software on CD by email, telephone or post (see Contact Details).
What to install
The name of the Easysoft ODBC-Oracle Driver install file varies from platform to platform, but is of the form:
- odbc-oracle-x_y_z-platform.exe (Windows)
¯ OR ¯
- odbc-oracle-x.y.z-platform.tar (Unix)
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:
- a free time-limited trial license which gives you free and unrestricted use of the product for a limited period (usually 30 days).
- a full license if you have purchased the product. On purchasing the product you are given an authorization code which you should have to hand.
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 http://www.easysoft.com/sales/autolicense.phtmlin 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.
The Unix installation routine has the following requirements:
- The Bourne shell (or BASH) must either be named (or linked to) /bin/sh or the first line of the install file updated to the correct location.
- Various common Unix commands such as grep, awk, cut, ps, sed, cat, wc, uname, tr and find.
If any of these commands are missing they can be obtained from the Free Software Foundation (http://www.fsf.org).
- Depending on the platform, you will need up to 3Mb of free disk space for the installed programs and up to 3Mb temporary space for the installation files themselves.
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:
¯ OR ¯
If the distribution file has been bzip2ed (i.e. the filename ends in .bz2), then use:
¯ OR ¯
If the distribution file has been compressed (i.e. the filename ends in .Z), then use:
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
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:
- that you have the minimum set of Unix programs it requires
- the platform you are running
- any platform-specific components, such as the version of the C runtime library
11. Press <Enter> to continue.
The script checks the archive package, with three possible outcomes:
- The files are checked and they pass
- The files are checked and they fail
- The files are not checked because some component required for the check is not found
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.
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 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 http://www.unixodbc.org.
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:
- If there are multiple copies of unixODBC on your system already you will have to choose one of them. If you pick the wrong one (i.e. not the one your applications are linked with, or not the one your run-time linker uses) the Easysoft ODBC-Oracle Driver will not be visible to your applications until this is corrected.
- If you have built unixODBC yourself from sources you must make sure it has been configured correctly for use with your applications.
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:
- If you want a trial license, leave it blank and press <Enter>.
- If you want to install a purchased license, enter your authorization code and press <Enter>.
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.
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:
- Display the license_request.txt file (e.g. using cat license_request.txt) and note the site number. Now run a web browser and go to http://www.easysoft.com/sales/autolicense.phtml. Log in to Easysoft's web site. On the License Generator screen, choose the type of license you want, then enter your site number and click Continue. You can now close the web browser. You will shortly receive your license key(s) via email.
- Email the file license_request.txt to firstname.lastname@example.org. Your license key(s) will be emailed to you automatically.
- Email the file license_request.txt to email@example.com. A member of the Licensing Department will email the license keys(s) to you.
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:
- If unixODBC is installed, the Easysoft ODBC-Oracle Driver driver must be removed from its database.
- If the system has a dynamic linker (such as ld.so on Linux), the Easysoft ODBC-Oracle Driver directories must be removed from the dynamic linker search path (this may require root access, depending on the mechanism used by the platform).
- The Easysoft ODBC-Oracle Driver install directory tree must be removed (this requires the same privileges as the user who performed the installation, which is normally root).
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 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:
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.
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.