Please read this carefully BEFORE installing the Easysoft ODBC Driver
for InterBase.

These instructions show how to install the Easysoft ODBC Driver for 
InterBase on UNIX platforms.

The driver requires an ODBC driver manager to be installed on your
system. Easysoft support the unixODBC driver manager
(http://www.unixodbc.org) but this driver can be used with other driver
managers. If you don't have a recognised ODBC driver manager on your
system this installation can install unixODBC for you. The
installation can also tell unixODBC about the driver and create sample
data sources for you.

PLEASE REMOVE AN OLD INSTALLATION TREE BEFORE reinstalling or
installing a new version in the same tree. See the file uninstall.txt
for instructions on how to do this.

After installing consult the documents in the easysoft/ojg/docs
directory before using the driver. In particular, read carefully the
document for your specific operating system.

Requirements
============

The installation script has a minimal set of requirements:

o Bourne shell in /bin/sh (if your Bourne shell is not located there you
  may need to edit the first line of the install file).

o 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 are missing any of these commands they can generally be
  obtained from the Free Software Foundation. As some machines have a
  broken tee command the distribution comes with a tee replacement.

o Depending on the platform, you will need up to 5Mb of disk space
  free for the installed programs and up to 5Mb temporary space of the
  installation files themselves. If you install the unixODBC Driver
  Manager as well, these numbers increase by approximately 1.5Mb.

o You need to be the root user for a successful install on most UNIX
  systems since dynamic linker configuration files and unixODBC
  odbc*.ini files tend to be only accessible by root and at a minimum
  a symbolic link from /usr/local/easysoft to where you installed the
  OJG is required. No files will be changed without asking first and
  copies are taken before alteration.

The installation process
========================

Untar the tar distribution file. On some platforms this is gzipped,
compressed or bzipped. This should create a directory called
"odbc-interbase-p.q.r-os-var" (where p.q.r is the version, os is the operating
system name and the optional var is a variation for that operating
system) containing some further tar files, some checksum files, this
INSTALL.txt file and an installation script ("install").


NOTE:

Make sure you read the license file, license.txt. Installing the
software on your machines shows your acceptance of the terms and
conditions in the License.

Throughout the installation you may 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 <return> 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 <return>.

You will need approximately 5 Mb of disk space to install all of the
driver.

Change into the created directory and run the install program with
./install.

You will be prompted to read the License file appropriate for your
installation and you must answer yes to accept the license.  If
you do not accept the license, then the installation will be aborted.

Once the installation has checked you have the necessary shell tools
it will autodetect the operating system and check any required
dependencies (e.g. version of the C runtime library). Next the install
checks the encapsulated tar package(s) by comparing them with a
checksum file (do not worry if the md5 checksum is not found as some
platforms do not come with md5sum). If this fails you will be given
the opportunity to abort the installation.

You will next be prompted for an installation path. All files are
installed in a subdirectory of your specified path called "easysoft"
e.g. if you pick the default of /usr/local, the driver will be installed
in /usr/local/easysoft and below. When installing the driver under an ODBC
driver manager some files outside the installation path will be
modified (but not without prompting you first - see later).

If you choose an install path different from the default then 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
/usr/local/easysoft exists either as a symbolic link to the real
install path or as the install path itself.

The driver is now distributed as 2 packaged tar files. These tar files
are for common/driver elements, and optionally the unixODBC Driver
Manager. The tar files are all untarred into subdirectories of
<install_path>/easysoft.

The installation procedure for the unixODBC driver manager will now
start. Your system will be searched for an existing unixODBC and if
one is found the location will be shown. If unixODBC is not found you
have the opportunity to tell the install script where to find it.  You
can use your installed unixODBC in preference to the one included with
this distribution. If unixODBC is not installed on your system the
install script will install it into <install_path>easysoft/unixODBC.

Note: Easysoft builds of unixODBC have sysconfdir set to /etc at build
time.

The installation will next untar the common/driver tar file. Some files
and shared objects are common to multiple Easysoft products. If files
shared between Easysoft products are included in the driver install the
installation will check to see if those files already exist or are
older. Only if these files do not exist or are older will the shared
files be installed. You may see messages like:

versioned shared file <filename> does not exist - installing

or

versioned shared file <file> is old - replacing

At this stage, some platforms (e.g. Linux, FreeBSD) need to have the
dynamic linker configuration file updated to add the paths to the OJG
shared objects. If this is the case, then the install will add paths
to the dynamic linker configuration file (e.g. /etc/ld.so.conf for
Linux) and ask the dynamic linker to re-read the configuration file
(e.g. /sbin/ldconfig for Linux). If the dynamic linker configuration
file already contains non existent paths you may see warnings that are
nothing to do with the driver install.

The installation will now install the driver under the unixODBC
Driver manager. Please watch the process carefully as the install uses
unixODBC's odbcinst command to install the driver. In particular you
should note:

[1] If you have had the driver installed in one path and reinstall with
    it in a different path then odbcinst will simply increase the
    driver usage count in unixODBC's odbcinst.ini file but NOT update
    the Driver attribute which points to the IB ODBC driver. You will
    have to do this manually after the installation.

[2] Ignore the text from odbcinst saying "Target directory is xxx".
    The target directory reported appears to have no relevance
    whatsoever.

A demo data source using the IB ODBC driver called IB_SAMPLE
will be added to unixODBC's system DSN list (usually
/etc/odbc.ini). This is only a sample and some attributes of the data
source will have to be edited after the install to match the InterBase
server you want to use connect the driver to.

The driver requires a license. There are currently two types of license.
Trial licenses last approximately one month and allow unlimited
connections to InterBase but they expire one month after a license is
obtained. Full licenses (available for purchase) are available with
unlimited concurrent connections. The installation will create the
<install_path>/license directory if it does not exist and also a
licenses template file in that directory.  You can obtain a trial
license or register a full license automatically during the
installation. When prompted to request an InterBase license, enter 'y' and
the Easysoft License Client program will be started for you.

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 mail, fax or telephone to Easysoft.

Once the License Client has started you are presented with a menu of
options which allow you to [0] exit, [1] view existing license [2]
show product list or [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 which is
used to identify the product and operating system (we need this key to
license you). NOTE, some products in the list may not be licensable
during the install, e.g. if you are installing the InterBase driver and do 
not have the Easysoft JDBC-ODBC Bridge installed then you cannot obtain a
license for the JDBC-ODBC Bridge (in this case the License Client will
probably output a warning that the siteinfo command for the chosen
product was not found). Assuming you have picked a product which is
installed (or in the process of being installed) then you need to
supply:

[a] Your full name
[b] Your company name
[c] An email contact address (you need to specify this if you email the
    license request to us).
[d] Your telephone number (you need to specify this if you telephone
    the license request to us).
[e] Your fax number (you need to specify this if you fax the license
    request to us).
[f] A reference number. When applying for a trial license just hit
   <return> 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 fax, telephone it (the
    license request is output to license_request.txt and you can
    telephone or fax this to Easysoft).
[3] Cancel request

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 site
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.

If you ran the License Client (above) the install script will detect
whether any licenses were automatically obtained and ask you if they
are to be installed in the <install_path>easysoft/license/licenses
file. You should answer y to this or the driver will not be licensed and
will not accept connections from ODBC applications. If you choose not
to have the licenses added to the licenses file then you can do this
manually later by copying the lines in licenses.out to
<install_path>/easysoft/license/licenses.

NOTE:
The shared objects installed are NOT stripped. You may strip them if
you wish but this may affect any support Easysoft can supply.

Post Installation
=================

After a typical installation the InterBase driver will be accessible in
/usr/local/easysoft/ib. The installation will also have installed:

o the unixODBC driver manager (or used your existing copy)
o installed the driver as an ODBC driver under unixODBC by adding an 
  entry to your odbcinst.ini file.
o installed a sample InterBase data source in your system odbc.ini.

NOTE: The unixODBC included with the driver has sysconfdir set to /etc. 
This means if you use the included unixODBC your odbcinst.ini and 
odbc.ini files (defining ODBC drivers and system DSNs) are in /etc. If you
built unixODBC yourself or are using a copy installed from RPM etc it
is more likely that sysconfdir was set to /usr/local/etc when unixODBC
was built. You can check by running odbcinst -j.

If you did not obtain a license during the installation you need to do
this now (you need to run /usr/local/easysoft/license/licshell and see
the license instructions above.

Currently the installation installs the InterBase driver in odbcinst.ini
with a default settings. e.g.

[INTERBASE]
Description    	= Easysoft InterBase ODBC Driver
Driver          = /usr/local/easysoft/ib/libibodbc.so
Setup           = /usr/local/easysoft/ib/libibodbc.so
FileUsage       = 1
DontDLClose     = 1

The sample ODBC data source called IB_SAMPLE is installed into
your system odbc.ini file. You need to edit this DSN or create a
different named one with the correct Database location, User, Password,
for your InterBase server. The sample one looks similar to this:

[IB_SAMPLE]
Driver          = INTERBASE
Description     = InterBase driver
Database        = server:employee.gdb
User            = sysdba
Password        = masterkey
With_Schema     = 0
Dialect         = 3
Charset         =
Role            =
Nowait          = 0
OldMetaData     = 0
ExecProc        = 0
DQueue          = 0
WithDefault     = 1

"Driver = INTERBASE" tells unixODBC which driver to use i.e. which entry in
odbcinst.ini file defines the ODBC driver.

"Database = server:employee.gdb" tells the driver where to connect to find
a running InterBase server, and the name of the databasr file to instruct the
server to open.

Testing the Driver
==================

To test the driver you need to complete all the processes above in the 
Post Installation section. In particular, you need to edit the sample DSN
or create a new one.

Once your DSN is defined you can use unixODBC's isql to try a connection.

e.g.

Suppose the DSN defined in odbc.ini is IB_SAMPLE and your InterBase
server needs a username and password of testuser/password then:

cd /usr/local/easysoft/unixODBC/bin (or wherever your unixODBC's isql is)
./isql -v IB_SAMPLE testuser password

If this connects you will get a prompt you can start typing SQL into
or just "help" to get a list of tables. Pressing <enter> on a new line
will exit isql.

Installation Warnings and Failures
==================================

There are a number of ways in which part of the installation may fail.
Here are a few minor problems and their resolution:

[1] If you attempt to install the driver under the unixODBC Driver
    Manager and you are not root you will probably get an error from
    odbcinst about a buffer too small. This is a bug in odbcinst. You
    must be root to perform this step. If it fails you will have to
    run odbcinst as root manually. See the unixODBC documentation.

[2] If you specify an installation path different from the default
    (/usr/local) then the installation script will attempt to link
    /usr/local/easysoft to <install_path>/easysoft. The install does
    this because some of the driver binaries are linked with a run path
    for the dynamic linker. The installation will only attempt to
    create this link if:

    [a] /usr/local/easysoft does not already exist.

    [b] /usr/local/easysoft already exists but is a symbolic link in
        which case you will be asked to confirm first.

    [c] if you specified a different install path from the default.

    If the installation cannot create the link then you may have to fix
    this yourself or define LD_LIBRARY_PATH/LD_RUN_PATH to contain the
    paths:

    <install_path>/easysoft/ib
    <install_path>/easysoft/lib
