Please read this carefully BEFORE installing the Easysoft ODBC-ODBC
Bridge.

These instructions show how to install the Easysoft ODBC-ODBC Bridge
on UNIX platforms.

You may install the client or both the client and server. Note, that
if you only want to access ODBC databases through drivers on remote
machines from this machine you only need the client. An example of
this would be running Apache/PHP linked with the ODBC-ODBC Client to
access a SQLServer database on a remote Windows machine.

If you have ODBC drivers on this machine (e.g. Easysoft's Tetra/CS3 or
Zortec ODBC drivers) which you want to access over the ODBC-ODBC
Bridge from other machines you should install the server too. You must
be root to install the server properly as it requires entries in your
services and inetd configuration files.

If you already have the unixODBC Driver Manager installed on your
machine this installation can install the OOB client under the
unixODBC DM automatically for you but you do not need to do this. This
installation may also contain the unixODBC Driver Manager (most
platforms). If it is included it can be automatically installed for you.

If you are installing the OOB Server to access ODBC drivers on this
machine from other machines via the OOB then Easysoft recommend you
install the unixODBC Driver Manager although you do not have to.

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/oob/docs
directory before using the ODBC-ODBC Bridge. 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 If you are only installing the client then you do not have to be the
  root user although on some platforms dynamic linker entries need to
  be added to a system files and if you are not root this will have to
  be done manually later. You must be root to install the server
  properly or the client under the unixODBC Driver Manager. Easysoft
  recommend you install all OOB components as the root user.

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

Untar the tar distribution file. On some platforms this is gzipped,
compressed or bzipped. This should create a directory called
"odbc-odbc-bridge-p.q.r.s.os{-mt}" (where p.q.r.s is the version, os
is the operating system name and the optional -mt stands for
multi-threaded or thread-safe) containing some further tar files, some
checksum files, this INSTALL file and an installation script
("install").


NOTE:

Make sure you read the license files. There are two licenses, one for
client only installations (Client-License.txt) and one for
client/server installations (Server-Client-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>.

If you are only installing the client side of the OOB, then it is only
necessary to be the root user if the directory to install in requires
root privilege, or if you want to install OOB under the unixODBC
Driver Manager. You will need approximately 5 Mb of disk space to
install both the client and server, the documentation and examples.

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 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 OOB will be installed
in /usr/local/easysoft and below. If you are also installing the
server side of the OOB or the OOB client under unixODBC then 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 OOB is now distributed as 3 or 4 packaged tar files. These tar
files are for common elements, the client, the server and optionally
the unixODBC Driver Manager. The tar files are all untarred into
subdirectories of <install_path>/easysoft.  You can consult
<install_path>/easysoft/oob/INVENTORY.txt for a description of all the
files installed.

If the distribution for your platform contains the unixODBC driver
manager you will now be asked whether you would like to install
it. Please read the notes in the installation prior to this question
as you do not have to install unixODBC. Generally speaking, you should
consider installing unixODBC if:

[1] You intend using ODBC drivers under an OOB Server running on this
    machine, i.e. you have multiple ODBC drivers on the machine you
    are installing on which you would like to access via the OOB.

[2] You already have other ODBC Drivers installed on this machine and
    your applications may want to access those drivers as well as the
    OOB ODBC driver.
    
[3] You intend using other Easysoft products in combination with OOB
    e.g. Easysoft Data Access for System Z or Tetra/CS3.

[4] You want to use the unixODBC GUI configuration tools to define
    DSNs.

If you chose to install unixODBC it is untarred in to the
<install_path>/easysoft/unixODBC directory. This build of unixODBC has
the sysconfdir set to /etc at build time so as to match the OOB client
which can also use /etc for system DSNs.

The installation will next untar the common tar file. Some files and
shared objects are common to multiple Easysoft products. If files
shared between Easysoft products are included in the OOB 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

Then if you choose to install the OOB client the client tar file will
be untarred. You need the OOB client to access remote ODBC drivers on
machines where you have installed the OOB Server.

At this stage, some platforms (e.g. Linux, FreeBSD) need to have the
dynamic linker configuration file updated to add the paths to the OOB
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 OOB install.

If you have installed the unixODBC package you can now choose to
install the OOB client as a driver under the unixODBC Driver manager.
The OOB client does not require a driver manager but if you have other
ODBC drivers running under the control of the unixODBC Driver Manager
then you should probably select yes. Generally speaking if you are
unsure, answer no here as the OOB client can be installed under
unixODBC after being installed anyway.

If you choose to install the OOB client ODBC driver under unixODBC
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 OOB client 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 OOB ODBC driver. You will
    have to do this manually after the instalaltion.

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

[3] You will be asked if you would like to create the demo data source
    using the OOB ODBC driver. If you answer yes, a data source called
    "demo" will be added to unixODBC's system DSN list (usually
    /etc/odbc.ini).  This demo data source points to an OOB Server
    running on one of Easysoft's machines so your machine will have to
    be internet connected to use it.

The remainder of the installation installs the OOB server and requires
the installer to be the root user. If you are not root the
installation will terminate now.

The OOB Server requires a license in order to accept ODBC connections
from the OOB client. There are currently two types of license.  Trial
licenses last approximately one month and allow unlimited connections
from OOB clients 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 OOB Server 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 ai.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 licencse [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, e.g. currently, option [2] for licensing
the ODBC-ODBC Bridge. 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 OOB 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 ai.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 ai.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 OOB Server will not be
licensed and will not accept connections from OOB clients. 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.

The installation then attempts to find your {x}inetd and services
configuration files. If these are located successfully it will check
there is no other service called "esoobserver" and no other service
using port 8888. If there is a conflict with either the service name
or port you will be given a chance to change (or overwrite) them in
which case you should pick any name you like for the service which is
not already in use and an unused port. Once the service name and port
are finalized, an entry will be added to the end of the {x}inetd and
service configuration files. The installation will show you which
files are being changed and which entries are being added. The final
part of defining the server environment is creating a script in
<install_path>/easysoft/oob/server which will be run by {x}inetd when
the OOB client connects to the specified port. Once this is complete
the {x}inetd daemon is asked to reread the configuration files so it
may listen on the specified port on behalf of the OOB server.

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

Testing the OOB server
======================

On a few platforms the OOB server is not distributed as a binary
because it needs an ODBC driver to be fully functional. It is not
possible to test the OOB server until it has been linked with an ODBC
driver and the final executable copied to
<install_path>easysoft/oob/server/esoobserver.  See the file BUILDING
for instructions on how to do this.

On most platforms the OOB Server is dynamically linked with libodbc in
which case libodbc may be any ODBC driver you have or a driver manager
such as the unixODBC DM. The Server archive file is also supplied in
case you would like to relink the server yourself.

If you have a running server you may telnet to the service
"esoobserver" on port 8888 (or if this was in use the server name or
port you specified during installation) to test the server is working
correctly:

telnet localhost esoobserver OR
telnet localhost 8888

(Substitute esoobserver and 8888 with the service name and port used
in the installation).

If the server is working correctly you should see a string like the
one below:

87FA9694x1:0:1998-1112-0000000001*01:Linux^02:2.2.1^03:i686^04:4^05:^06:™p^^]

The precise string depends on the OS the server is installed on and
the version of the ODBC-ODBC Bridge.

Once you have verified the server is starting you may connect to it from
any application linked with the OOB client (or any application dynamically
linked with the OOB client through a driver manager). See "Testing the
OOB client" below.

Testing the OOB client
======================

The OOB client is a shared object containing entry points for the full
ODBC 3.5 API, most of the ODBC 2.0 API (and a few others as well).
The OOB client only becomes functional when an application is linked
with it directly or via a driver manager. The examples directory
contains a number of test applications and make files which may be
used to try the ODBC-ODBC Bridge out with. Please consult the INSTALL
file in the examples directory.

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 OOB Client 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 OOB 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/oob/client
    <install_path>/easysoft/lib

    If you are using the OOB Server on the machine where the symbolic
    link could not be created there is no alternative but to create
    the symbolic link. Licensing in the OOB Server will not work
    without it.

[3] For Linux there are 2 distributions, glibc and libc5. It is
    important that you choose the correct version for you
    installation. The latest installation comes distributed with a
    small program called "testlib".  When installing for Linux, the
    installation runs testlib to see if it works correctly. The glibc
    version of OOB is distributed with a glibc linked version of
    testlib and the libc version of OOB is distributed with a libc5
    linked version of testlib. If testlib fails to run the
    installation will warn you that you are probably installing an
    incompatible version of OOB for your machine. In this case you
    should download the other distribution and install that.

    In a few cases we may not have any version of OOB compatible with
    your run time C library. One such case would be if you are still
    running an old version of glibc such as 2.0.6. In this case we
    recommend you upgrade your runtime C library.

Please remember that OOB clients and servers are matched according to
their major and minor version number. This means that an OOB client
from the 0.4.0.0 version will not talk to an OOB Server from the
0.6.0.0 version.  Here, the first 3 numbers are significant
i.e. 0.4.0.0 and 0.4.0.1 are OK.
