Easysoft ODBC-Access Driver User's Guide - Installation
Installing the Easysoft ODBC-Access Driver
This chapter explains how to install, license and remove the Easysoft ODBC-Access Driver.
The installation instructions assume you are, or are able to consult with, a system administrator.
Obtaining the Easysoft ODBC-Access Driver
There are three ways to obtain the Easysoft ODBC-Access Driver:
- The Easysoft web site is available 24 hours a day at http://www.easysoft.com and lets you download product releases and documentation.
Choose Download from the Easysoft ODBC-Access Driver section of the web site and then choose the platform release that you require.
If you have not already done so, you will need to register at the web site to download Easysoft software.
- The Easysoft FTP site is available 24 hours a day at ftp://ftp.easysoft.com and lets you download free patches, upgrades, documentation and beta releases of Easysoft products, as well as definitive releases.
Change to the pub/access subdirectory and then choose the platform release that you require.
- You can order Easysoft software on CD. To do this, contact us by email, telephone or post.
What to Install
The name of the Easysoft ODBC-Access Driver distribution file varies from platform to platform. The file name format is:
where x is the major version number, y is the minor version number and z is the build index, which is incremented when minor changes are made.
platform depends on the operating system distribution you require. File names may have this format:
where platform-variation refers to alternative versions available for a single platform.
Select the highest release available for your platform within your licensed major version number (installing software with a different major version number requires a new Easysoft license).
Unix file names may also be suffixed with .gz for agzipped archive, .bz2 for a bzip2ed archive, or .Z for a compressed archive.
If you download a Unix file with a Windows browser, the browser may strip the file name extension. For example, if you download a .gz file and the browser strips the file name extension, it may not be obvious that the file is gzipped. Use filefilename to find out the file type of the downloaded file.
As long as you stop all Easysoft software first (or software that uses the Easysoft drivers), it is safe to reinstall or upgrade the Easysoft ODBC-Access 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).
Installing the Easysoft ODBC-Access Driver
These instructions show how to install the Easysoft ODBC-Access Driver on Unix platforms. Please read this section carefully before installing the Easysoft ODBC-Access Driver.
Before you Install
To install the Easysoft ODBC-Access Driver on Unix 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 Unix 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 will 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-Access Driver in /usr/local/easysoft.
- Install the Easysoft ODBC-Access 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-Access Driver elsewhere and set the EASYSOFT_ROOT environment variable.
For more information about setting the EASYSOFT_ROOT environment variable, see Post installation.
- An ODBC Driver Manager. Easysoft ODBC-Access 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-Access 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.
Easysoft recommend you install all components as the root user.
What you can Install
This distribution contains:
- The Easysoft ODBC-Access Driver.
- The unixODBC Driver Manager.
You will need an ODBC Driver Manager to use the Easysoft ODBC-Access Driver from your applications. The distribution therefore contains the unixODBC Driver Manager. Most (if not all) Unix applications and interfaces 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-Access 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 Driver Manager in the standard places. If you have installed it in a non-standard location, the installation script will prompt 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 will be 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 will try 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, see 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
This 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:
1. If you choose to install the Easysoft ODBC-Access 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 odbcinst.ini entry for the Easysoft ODBC-Access Driver will look similar to this:
Description = Easysoft ODBC-Access Driver
Driver = /usr/local/easysoft/access/lib/libesmdb.so
Setup = /usr/local/easysoft/access/lib/libesmdbS.so
Threading = 0
FileUsage = 1
DontDLClose = 1
UsageCount = 1
For information about removing these entries, see Uninstalling the Easysoft ODBC-Access Driver.
2. The installation script installs example data sources into unixODBC. The data sources will be added to your SYSTEM odbc.ini file. You can locate your SYSTEM odbc.ini file by using odbcinst -j. The data source for the standard driver will look similar to this:
Description = Easysoft ODBC-Access Driver
Driver = Easysoft ODBC-ACCESS
mdbfile = /path/to/data.mdb
readonly = yes
exclusive = no
ignore_rel = no
For information about removing these data sources, see Uninstalling the Easysoft ODBC-Access Driver.Easysoft ODBC-Access Driver
3. Dynamic Linker.
On operating systems where the dynamic linker has a file listing locations for shared objects, the installation script will attempt to add Easysoft ODBC-Access Driver shared object paths to this list. On Linux, this dynamic linker configuration file is usually /etc/ld.so.conf.
Reinstalling or Installing When You Already Have Other Easysoft Products Installed
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 will be 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 will see 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 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.
Gathering Information Required During the Installation
During the installation, you will be 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 platforms is a tar file. There are multiple copies of the same distribution with different levels of compression. You unpack the distribution in one of the following ways.
If the distribution file has been gzipped (.gz), use:
If the distribution file has been bzipped (.bz2), use:
If the distribution file has been compressed, (.Z), use:
You may have a distribution file which is not compressed at all (.tar). To extract the installation files from the tar file, use:
tar -xvf odbc-access-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 installation script and various other installation files.
Change directory into the directory created by unpacking the tar file.
License to Use
The End-User License Agreement is contained in the file license.txt. Be sure to understand the terms of the agreement before continuing, as you will be required to accept the license terms at the start of the installation.
Answering Questions During the Installation
Throughout the installation, you will be asked to answer some questions. In each case, the default choice will be displayed in square brackets and you need only press Enter to accept the default. If there are alternative responses, these will be shown in round brackets; to choose one of these, type the response and press Enter.
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
Before you run the installer, make sure you have read Installation. If you are considering running the installation as a non root user, make sure you also read:
To start the installation, run:
You will need to:
- Confirm your acceptance of the license agreement by typing "yes" or "no".
For more information about the license agreement, see License to Use.
- Supply the location where the software is to be installed. Easysoft recommend accepting the default installation path.
For more information, see Where to Install.
If you are upgrading, you will need a new license from Easysoft.
Locating or Installing unixODBC
Easysoft strongly recommend you use the unixODBC Driver Manager because:
- The installation script is designed to work with unixODBC and can automatically add Easysoft ODBC-Access Driver and data sources during the installation.
- Most ODBC-enabled applications and interfaces support unixODBC. The Easysoft ODBC-Access Driver and any data sources that you add during the installation will be 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-Access Driver running under unixODBC. It also means that if you find a problem in unixODBC, it is much easier for us to facilitate a fix.
The installation starts by searching for unixODBC. There are two possible outcomes here:
1. If the installation script finds unixODBC, the following message will be output:
Found unixODBC under /unixODBC_path
and it is versionn.n.n
2. If the installation script cannot 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 included.
The unixODBC in the Easysoft ODBC-Access Driver distribution is not built with the default options in unixODBC's configure line.
This means the default SYSTEM odbc.ini file where SYSTEM data sources 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 use system semaphores to keep track of used handles. Many systems do not have sufficient semaphore resources to keep track of used handles. In addition, the statistics are only available in the GUI ODBC Administrator.
This disables readline support in isql.
We disabled 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 enabling readline support makes isql unusable on these systems.
This installs unixODBC into /usr/local/easysoft/unixODBC.
Figure 1: Easysoft unixODBC
configure line options.
Installing the Easysoft ODBC-Access Driver
The Easysoft ODBC-Access Driver installation script:
- Installs the driver.
- Registers the driver with the unixODBC Driver Manager.
If the Easysoft ODBC-Access Driver is already registered with unixODBC, a warning will be displayed that lists the drivers unixODBC knows about. If you are installing the Easysoft ODBC-Access 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. unixODBC's odbcinst will not update these paths if a driver is already registered.
- Creates an example Easysoft ODBC-Access Driver data source.
If unixODBC is installed and you registered the Easysoft ODBC-Access Driver with unixODBC, an example data source will be added to your odbc.ini file.
If a data source called "ACCESS_SAMPLE" already exists, the existing data source will be displayed and you have the option to replace it.
The installation_path/easysoft/license/licshell program lets you obtain or list licenses.
Licenses are stored in the installation_path/easysoft/license/licenses file. 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-Access Driver license:
Would you like to request a Easysoft ODBC-Access 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, the installation runs the licshell script. The process of obtaining a license is best described in the Licensing Guide.
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, the License Client can create a license request file that you can mail or fax to Easysoft. You can also supply the details to us by telephone.
Start the License Client. The following menu is displayed:
 view existing license
[n] obtain a license for the desired product.
To obtain a license, select one of the options from  onwards for the product you are installing. The License Client will then run a program that generates a key that is 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-Access 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.
- Your telephone number (you need to specify this if you telephone us to request a license).
- Your fax number (you need to specify this if you fax the license request to us).
- A reference number. When applying for a trial license, just press Enter when prompted for a reference number. This field is used to enter a reference number that we will supply you for full (paid) licenses.
You will then be asked to specify how you want to obtain the license. The choices are:
 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.
 Write information to file so you can fax, telephone it
The license request is output to license_request.txt.
 Cancel this operation
If you choose to obtain the license automatically, the License Client will start a TCP/IP connection to license.easysoft.com on port 8884 and send the details you supplied and 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  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 , the license request is written to the file license_request.txt. You should then exit the License Client by choosing option  and complete the installation. After you have mailed, faxed or telephoned the license request to us, we will return a license key. Add this to the end of the file installation_path/easysoft/license/licenses.
If any warnings or errors are output during this process, please mail the output to firstname.lastname@example.org and we will correct the problem.
Supplied Documents and Examples
The last part of the installation runs a post install script that lists the resources available to you.
- The Easysoft ODBC-Access Driver documentation is installed in installation_path/easysoft/access/doc:
- The Easysoft ODBC-Access Driver manual in PDF format.
- The Easysoft ODBC-Access Driver EULA.
installation_path/easysoft/access/doc/CHANGES.txt lists all the changes in each version of the Easysoft ODBC-Access Driver.
There are also many resources at the Easysoft web site.
Post Installation Steps for non-root Installations
If you installed the Easysoft ODBC-Access Driver as a non-root user (not recommended), there may be some additional steps you will need to do manually:
1. If you attempt to install the Easysoft ODBC-Access 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 find out the location of the DRIVERS file then append the lines from the drv_template file to the odbcinst.ini file. (drv_template is in the directory where the distribution was untarred to).
2. 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.
3. On systems where the dynamic linker has a configuration file defining the locations where it looks for shared objects (Linux), you will need to add:
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.)
4. If you did not install the Easysoft ODBC-Access 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 will create /home/user/easysoftand 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.
5. If your system does not 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 amend this in a system file run whenever someone logs in such as /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.
Setting Dynamic Linker Search Paths
Your applications will be linked against an ODBC Driver Manager, which will load the ODBC Driver you require. The dynamic linker needs to know where to find the ODBC Driver Manager shared object. The ODBC Driver Manager will load the Easysoft ODBC-Access Driver, which is dependent on further common Easysoft shared objects; the dynamic linker needs to locate these too.
On operating systems where the dynamic linker has a file specifying locations for shared objects (Linux, for example), the installation will attempt to add paths under the path you provided at the start of the installation to the end of this list; no further action should be required. For more information, see Dynamic Linker..
On other Unix platforms, there are two methods of telling the dynamic linker where to look for shared objects:
1. You add the search paths to an environment variable and export it.
This method always works and overrides the second method, described below.
2. At build time, a run path is inserted into the executable or shared objects. On most System V systems, Easysoft distribute Easysoft ODBC-Access Driver shared objects with an embedded run path. The dynamic linker uses the run path to locate Easysoft ODBC-Access Driver shared object dependencies.
For the first method, the environment variable you need to set depends on the platform (refer to the platform documentation for ld(1), dlopen or ld.so(8)) .
|Environment Variable ||Platform|
System V based operating systems and Solaris.
Many platforms use this in addition to those listed above.
Figure 2: Dynamic linker search path environment variables.
To use the Easysoft ODBC-Access Driver, you need to add:
where installationdir is the directory in which you chose to install the Easysoft ODBC-Access Driver. If you accepted the default location, this is /usr/local.
An example of setting the environment path in the Bourne shell on Solaris is:
The exact command you need to set and export an environment variable depends on your shell.
If you installed the unixODBC Driver Manager included in the Easysoft ODBC-Access Driver distribution, you also need to add installationdir/easysoft/unixODBC/lib to the dynamic linker search path.
Uninstalling the Easysoft ODBC-Access Driver
There is no automated way to remove the Easysoft ODBC-Access Driver in this release. However, removal is quite simple. To do this, follow these instructions.
To uninstall the Easysoft ODBC-Access Driver
1. Change directory to installation_path/easysoft and delete the access directory. installation_path is the Easysoft ODBC-Access Driver installation directory, by default /usr/local.
2. 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.
3. If you were using unixODBC, the Easysoft ODBC-Access Driver entry needs to be removed from the odbcinst.ini file. To check whether the Easysoft ODBC-Access Driver is configured under unixODBC, use odbcinst -q -d. If the command output contains [Easysoft ODBC-ACCESS], uninstall the drivers from unixODBC by using:
odbcinst -u -d -n "Easysoft ODBC-ACCESS"
If a reduced usage count message is displayed, repeat this command until odbcinst reports that the drivers have been removed.
4. If you created any Easysoft ODBC-Access 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 Easysoft ODBC-Access.
5. Remove access_install.info from the installation_path/easysoft directory.