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 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 (not all
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

  If you are missing any of these commands they can generally be
  obtained from the Free Software Foundation.

o Depending on the platform, you will need up to 5Mb of disk space
  free for the installed programs and up to 2Mb 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 or
compressed. This should create a directory called
"odbc-odbc-bridge-p.q.r.s.os" (where p.q.r.s is the version and os is
the operating system name) 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.

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

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.

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

Once the installation has checked you have the necessary shell tools
it will autodetect the operating system and check 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 then some files outside the installation path
will be modified (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 this may be corrected manually).

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.

The installation will untar the common tar file. Then if you choose to
install the OOB client the client tar file will be untarred.

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.

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 installation then attempts to find your 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 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/server which will be run by inetd when the OOB
client connects to the specified port. Once this is complete the inetd
daemon is asked to reread the configuration files so it may listen on
the specified port on behalf of the OOB server.

On some platforms (e.g. Linux) there is one additional step which adds
an entry to the end of the dynamic linker configuration file
specifying the path of any shared objects installed.

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 some 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 a few 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 built a server executable or installed the OOB server on
an NT box then 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.0 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

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