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

These instructions show how to install the Easysoft ODBC-ODBC Bridge
on UNIX platforms. For MAC OSX the OOB is distributed as a MAC package,
for Windows as an InstallShield package and QNX 6 as a QNX package
so you can simply double click on to install.

Contents:
1.0 Before You Install
 1.1 Requirements
 1.2 What you can install
 1.3 Where to install
 1.4 Changes made to your system
 1.5 Reinstalling or
     installing when you already have other Easysoft products installed
 1.6 Gathering information required during the installation
2.0 Installation
 2.1 Unpacking the distribution
 2.2 License to use
 2.3 Answering questions during the installation
 2.3 Running the installer
 2.4 Locating or installing unixODBC
 2.5 Installing the OOB Client
 2.6 Installing the OOB Server
 2.7 Licensing the OOB Server
3.0 Post Installation
 3.1 Supplied documents and examples
 3.2 Post installation steps for non-root installations
 3.3 Testing the OOB Server
 3.4 Testing the OOB Client

1.0 Before You Install
======================

1.1 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 22Mb of disk space
  free for the installed programs and up to 22Mb temporary space of
  the installation files themselves. If you install the unixODBC
  Driver Manager as well, these numbers increase by approximately
  1.5Mb.  Distributions not containing a GUI setup dialogue and QT are
  significantly smaller (usually 10Mb less).

o For Easysoft Licensing to work you must either install in
  /usr/local/easysoft or 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.

o An ODBC Driver Manager. OOB distributions contain the unixODBC
  Driver Manager but you can use an already installed unixODBC if you
  prefer.

o If you are only installing the client then you do not have to be the
  root user but if you are not then it will not be possible to register
  the OOB Client with unixODBC, install sample SYSTEM DSNs or update
  the dynamic linker entries (only some platforms). If you are not
  root this will have to be done manually later. You must be root to
  install the server properly.

  Easysoft recommend you install all OOB components as the root user.

1.2 What you can install
========================

This OOB distribution contains:

o the OOB Client
o the OOB Server
o the unixODBC Driver Manager (except on MAC OS X)

You may install the Client, the Server or both but most installations
will install the Client on one machine and the Server on another
machine. Note, that if you only want to access ODBC databases through
drivers on remote machines from this machine you only need the Client
on this machine and then the Server on the machine where your remote
ODBC driver is located.

If you have ODBC drivers on this machine (e.g. Easysoft's Tetra/CS3,
D-ISAM or Zortec ODBC drivers) which you want to access over the OOB
from other machines you should install the server too.

A few examples help to illustrate this:

1. Accessing MS SQL Server on Windows from a UNIX machine.

   You should install the OOB Client on the UNIX machine.
   You should install the OOB Server on a Windows machine which has
   a MS SQL Server ODBC Driver (it does not have to be the machine
   running MS SQL Server).

2. Accessing D-ISAM files on UNIX from Windows

   You should install the OOB Client on the Windows machine which needs
   access to your D-ISAM files.
   You should install the OOB Server on your UNIX machine. In this
   particular case you will need an ODBC driver for D-ISAM on your
   UNIX machine (like Easysoft Data Access for D-ISAM).

You will need an ODBC Driver Manager to use the OOB Client from your
applications or for the OOB Server to access your ODBC drivers on this
machine. OOB distributions contain the unixODBC Driver Manager (see
http://www.unixodbc.org). Most (if not all) UNIX applications and
interfaces (e.g. Perl DBD::ODBC, PHP, Python etc) support the unixODBC
Driver Manager.

You do not have to install the unixODBC Driver Manager in this
distribution as you can use an already installed unixODBC (whether
that was installed with another Easysoft product, from your Operating
System Vendor or even if you built it yourself). However, Easysoft
ensure the unixODBC distributed with Easysoft ODBC Drivers has been
tested with our drivers so we recommend you use it.

If you choose to use an already installed unixODBC Driver Manager the
installation script will attempt to locate it. The installation looks
in the standard places but if you have installed it in a non-standard
location you will need to provide that location to the installation
script when it prompts you. The installation primarily needs
unixODBC's odbcinst command to install drivers and any data sources.

1.3 Where to install
====================

This installation needs a location for the installed files. The default
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" e.g. if you pick the default of
/usr/local, the OOB will be installed in /usr/local/easysoft and
below.

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 your chosen
install path or as the install path itself.

1.4 Changes made to your system
===============================

This installation installs files in subdirectories of the path
requested at the start of the installation and depending on what is
installed a few changes may be made to your system as outlined below:

Client:

1. If you choose to install the OOB Client into unixODBC then
   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 will be in /usr/local/easysoft/unixODBC/bin) if you are
   using the unixODBC that comes with OOB.

   The entry for OOB will look similar to this:

   [OOB]
   Description = Easysoft ODBC-ODBC Bridge
   Driver = /usr/local/easysoft/oob/client/libesoobclient.so.1
   Setup = /usr/local/easysoft/oob/client/libesoobsetup.so
   UsageCount = 1

   On some platforms the OOB Client is distributed as two separate
   drivers, a thread-safe one requiring pthreads (OOB_r) and one which
   is not thread-safe (OOB) and does not require pthreads. If this
   distribution contains the thread-safe driver an additional driver
   will be added to your odbcinst.ini file:

   [OOB_r]
   Description = Easysoft ODBC-ODBC Bridge (MT)
   Driver = /usr/local/easysoft/oob/client/libesoobclient_r.so.1
   Setup = /usr/local/easysoft/oob/client/libesoobsetup.so
   UsageCount = 1

   See the UNINSTALL.txt file for ways to remove these drivers.

2. If you choose to add the demo data source to unixODBC an entry
   will be added to your SYSTEM odbc.ini file. You can locate your
   SYSTEM odbc.ini file using odbcinst -j. The entry will look similar
   to this:

   [demo]
   Driver          = OOB
   Description             = Easysoft ODBC-ODBC Bridge demo data source
   SERVERPORT              = demo.easysoft.com:8888
   TARGETDSN               = pubs
   LOGONUSER               = demo
   LOGONAUTH               = easysoft
   TargetUser              = demo
   TargetAuth              = easysoft

   See the uninstalling section for ways to remove this.

3. If you had an OOB Server already installed on a machine when you
   installed the OOB Client you would have been given the opportunity
   to test connection to that Server and enter all the details
   required to define this local data source tailored for your Server.

   Once the test is successful you will be asked to provide a data
   source name and whether you want this added to your SYSTEM odbc.ini
   file.  The entry added will look like the one above in (2).

Server:

1. If you installed the OOB Server and chose to run it under (x)inetd
   the installation will:

   a) add a service called esoobserver (or whatever you chose to call it)
      to your /etc/services file.
   b) update your inetd configuration. See the Uninstalling section for
      a description of which files are affected.

Client and Server:

1. Dynamic Linker.

   On operating systems where the dynamic linker has a file specifying
   locations for shared objects (Linux, FreeBSD) the installation will
   attempt to add paths under the path you provided at the start of
   the install to the end of this list.

   On Linux this is generally the file /etc/ld.so.conf.

   On FreeBSD this is generally the file /etc/defaults/rc.conf.

1.5 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
/usr/local/easysoft/lib.  When you run an installation the dates and
versions of these files will be compared with the same files in the
distribution and 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 because on some platforms,
files in use cannot be replaced. If a file cannot be updated you will
see a warning during the installation. You may review all warnings
after the installation in the 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 an OOB Server you will need a new license from
Easysoft to use the new Server.

1.6 Gathering information required during the installation
==========================================================

During the installation you will be prompted for various information.
Before installing you should determine:

o If you have unixODBC already installed and where it is installed.
  The install searches standard places like /usr and /usr/local but if
  you installed in a non-standard place and you don't install the unixODBC
  that comes with OOB you will need to know the location.

o If you install the OOB Client and you want to create a test data source
  and test it during the installation you will need:

  a) the name or IP address of the machine where the OOB Server is running.
  b) a username and password to logon to the operating system on the
     Server machine.
  c) the name of a SYSTEM data source on the server machine you want to
     connect to.
  d) a username and password (if required) to logon to the database engine
     defined in (c).

2.0 Installation
=============================

2.1 Unpacking the distribution
==============================

The OOB distribution for UNIX platforms except MAC OS X and QNX is
distributed as a tar file. There are multiple copies of the same
distribution with different levels of compression. You unpack the
distribution as follows.

If the distribution file has been gzipped (i.e. the filename ends
in .gz), then use:

gunzip odbc-odbc-bridge-x.y.z-platform.tar.gz

If the distribution file has been bzipped (i.e. the filename ends in
.bz2), then use:

bunzip2 odbc-odbc-bridge-x.y.z-platform.tar.bz2

If the distribution file has been compressed (i.e. the filename ends in .Z),
then use:

uncompress odbc-odbc-bridge-x.y.z-platform.tar.Z

You may have a distribution file which is not compressed at all (i.e.
the filename ends in .tar).

To extract the installation files from the tar file use:

tar -xvf odbc-odbc-bridge-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 install script and various other installation files.

Change directory into the directory created by unpacking the tar file.

2.2 License to use
==================

There are two license agreement files provided in the distribution;
one that applies if you are installing just the OOB Client, and another
that applies if you are installing the OOB Server or both the OOB
Client and Server. The license text can be found in the files
Client-License.txt and Server-Client-License.txt. Determine which
applies to you and be sure to understand the terms before continuing
as you will be required to accept the license terms at the start of
the installation.

2.3 Answering questions during the installation
===============================================

Throughout the installation you will 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 <Enter> 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 <Enter>.

e.g.
Do you want to continue? (y/n) [n]: 

The possible answers to this question are "y" or "n". The default when
you enter nothing and hit <Enter> is "n".

2.4 Running the installer
=========================

Before you run the installer make sure you have read section 1. If you
are considering running the installation as a non root user we suggest
you review this carefully as you will have to get a root user to
manually complete some parts of the installation afterwards. Easysoft
recommend installing as the root user (if you are concerned about the
changes that will be made to your system see 1.4 Changes made to your
system).

To start the installation run:

./install

You will need to:

o confirm your acceptance of the license agreement with "yes" or "no".
  See 2.2 License to use.
o enter a location where the software is to be installed. Easysoft recommend
  taking the default here. See 1.3 Where to install.

NOTE: If you are upgrading an OOB Server you will need a new license from
Easysoft.

The next step is 2.4 Locating or installing unixODBC.

2.4 Locating or installing unixODBC
===================================

Easysoft strongly recommend you use the unixODBC Driver Manager because:

o the installation is designed to work with unixODBC and can
  automatically add ODBC drivers and DSNs during the install.

o most applications and interfaces that can use ODBC know about
  unixODBC and so any new ODBC drivers or data sources you add with
  this installation will automatically become available to your
  applications and interfaces.

o unixODBC is currently maintained by Easysoft developer Nick Gorham.
  This means there is much greater experience with unixODBC within
  Easysoft and we will be able to provide better support for OOB
  running under unixODBC. It also means that if you find a problem in
  unixODBC it is much easier for us to facilitate a fix.

o The unixODBC package contains much more than a driver manager.  The
  aim of the unixODBC project is to provide all the ODBC functionality
  available on Windows for UNIX operating systems. The unixODBC
  package may be built with the QT libraries to allow GUI
  configuration of DSNs and drivers. It also contains the GUI
  DataManager program which may be used to explore your ODBC data.
  OOB contains the code and shared object which is used by unixODBC's
  GUI ODBCConfig utility to add/delete and configure OOB DSNs.

The installation will start by searching for an installed unixODBC.

There are two possible outcomes here:

1. If unixODBC is located a message will be output saying:

   Found unixODBC under /path_to_unixODBC
      and it is version n.n.n

2. unixODBC is not found.

   If unixODBC is not found in the standard places you will be asked
   whether you have it installed.
 
   If you have it installed you need to provide the argument given to
   unixODBC's configure as --prefix. i.e. if you built unixODBC with
   "configure --prefix=/usr/local/unixODBC" you enter
   "/usr/local/unixODBC". Generally the path required is the directory
   above where odbcinst is installed i.e. if odbcinst is in
   /opt/unixODBC/bin/odbcinst the required path is /opt/unixODBC.

   If you have not got unixODBC installed you should install the unixODBC
   included with OOB.

If you already have unixODBC installed you do not have to install the
unixODBC included with OOB but you might consider doing so if your
version is older than the one included with OOB.

The unixODBC in the OOB distribution is not built with the default
options in unixODBC's configure line:

o --prefix=/etc
  This means the default SYSTEM odbc.ini file where SYSTEM dsns are located
  will be /etc/odbc.ini.

o --enable-drivers=no
  This means other ODBC drivers that come with unixODBC are not installed.

o --enable-iconv=no
  This means unixODBC will not look for a libiconv. Warnings about not finding
  an iconv library were confusing our customers.

o --enable-stats=no
  Disables unixODBC statistics which uses system semaphores to keep track
  of used handles. Many machines do not have sufficient semaphore resources
  to keep track of statistics and they are only available in the GUI
  ODBC Administrator anyway.

o --enable-readline=no
  This disables readline support in isql.
  We disabled this because it ties isql to the version of libreadline
  on the machine we build on. We build on as old a version of the Operating
  System we can for upwards compatibility. Many newer Linux machines no longer
  come with the older readline libraries and so enabling readline support
  renders isql unusable.

o --prefix=/usr/local/easysoft/unixODBC
  This installs unixODBC into /usr/local/easysoft/unixODBC.

2.5 Installing the OOB Client
=============================

You need to install the OOB Client if you want to access remote ODBC
drivers (ODBC drivers on other machines) from this one. The OOB Client
installation comprises of:

o At the "Install ODBC-ODBC Bridge Client (y/n) [y]:" enter "y" to
  install the OOB Client.

o Register OOB Client ODBC Driver with the unixODBC Driver Manager

  If unixODBC is now installed (either installed by this installation
  or an existing copy was found) the OOB Client ODBC Driver can be
  registered as an ODBC driver with the unixODBC Driver Manager.

  Answering "y" to "Install OOB into unixODBC (y/n) [y]:" will add
  entries into unixODBC's odbcinst.ini file making the OOB Client
  available to your applications and interfaces (see 1.4 Changes made
  to your system).

  The default here is "y".

  If you already have the OOB Client registered with unixODBC you will
  see a warning that OOB is already registered and a list of the
  drivers unixODBC knows about. If you are installing OOB 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 as unixODBC's odbcinst will not update them
  if a driver is already registered.

o Creating an OOB demo data source in unixODBC

  If unixODBC is installed and you registered the OOB Client with
  unixODBC you will be asked if you want to add a demo data source to
  your odbc.ini file. This is an OOB Client data source which points
  to an OOB Server running on demo.easysoft.com. You can use this DSN
  to test the OOB Client if you do not install an OOB Server
  yourself.

  To use the demo data source this machine will need access to
  demo.easysoft.com through port 8888 (which may be disabled in your
  firewall). If this machine does not have access to the net or is
  blocked by a firewall then there is still no harm in installing this
  DSN as it is useful as an example when you are creating your own
  data sources.

  If you choose to install the OOB demo data source and a data source
  called "demo" already exists the existing demo data source will be
  displayed and you have the option to replace it.

o Test Connection to OOB Server

  If you have already installed the OOB Server on a machine you can
  now test the connection to it, display a list of tables and create a
  data source definition specific to your setup. Although the default
  is to perform the test you do not have to.

  The installation guides you through this process step by step using
  oobping at each stage to test connection to the OOB Server,
  operating system authentication, remote SYSTEM DSN existence and
  database authentication. If at any time you want to abort this test you
  can enter "q" at any prompt.

  Each successful step should display the output from the Server and then
  the OOB attributes required for that stage e.g.

-----
  Server (q=quit) : myserver
  Using /usr/local/easysoft/bin/oobpings -h myserver -t 8888
  ===============================================================
  Host: myserver, Port: 8888
  Attempting connection...OK
  Examining Server...
        OOB Server Version: 2.0.0
        OOB Server Name: OOB
  ===============================================================

  ServerPort = gambantein:8888
-----

  Here you entered, myserver as the name of the machine where the OOB
  Server is installed, oobping was used to connect to the Server which
  returned Server version 2 and name OOB and finally the OOB attribute
  (ServerPort) required for this stage is displayed.

  Subsequent steps add the operating system username/password, remote
  SYSTEM data source and database username/password until you have the
  complete OOB Client DSN to reproduce the connection.

  If you successfully connect to a remote SYSTEM DSN you can enter a
  name for this data source definition and it can be written to your
  system odbc.ini file.

  Finally, this data source can be used to obtain a list of tables from
  the remote database (unixODBC's isql will be used for this).

o Test Perl setup

  If the installation detects you have Perl installed it can run a series
  of tests on it, making recommendations for using ODBC in Perl. You do
  not have to perform this test and if you are not going to use Perl
  there is nothing to be gained.

2.6 Installing the OOB Server
=============================

You install the OOB Server on the machine where you have an ODBC
driver for the database you want to access. You need a license key to
use the OOB Server and one can be obtained during the installation
(see Licensing the OOB Server).

The OOB Server installation comprises of:

o At the "Install ODBC-ODBC Bridge Server (y/n) [n]:" enter "y" to
  install the OOB Server.

  All the server files will be installed.

o License

  "Would you like to request a OOB Server license now (y/n) [y]: "

  See 2.7 Licensing the OOB Server.

o Install services and {x}inetd entries

  By default the OOB Server runs under inetd or xinetd and needs an
  entry in your services file. You can run the OOB Server standalone without
  inetd but we recommend you start with an inetd setup.

  At the question "Do you wish to install the services and inetd
  entries? (y/n) [y]: " enter "y". If you enter "n" here then you will
  either have to set up the OOB Server under inetd yourself or run it
  standalone.

  The installation then attempts to find {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.

  You can see a list of changed files during the installation and
  further details are available in 1.4 Changes made to your system.

2.7 Licensing the OOB Server
============================

Only the OOB Server needs to be licensed.

The program /usr/local/easysoft/license/licshell is used to obtain
or list licenses.

Licenses are stored in the file /usr/local/easysoft/license/licenses.
After obtaining a license you should take a copy of this file in case
something happens to it.

If you decide to install the OOB Server then the installation will ask
you if you want to request an OOB Server license:

Would you like to request a OOB Server 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 to this the installation will run the licshell
script. The process of obtaining a license is best described in the
Licensing Guide and on the Easysoft web site.

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:

1. enter at http://www.easysoft.com/sales/autolicense.phtml to
   obtain your license.
2. mail, fax or telephone to Easysoft.

Obviously, option 1 is quickest if you have a web browser and access
to the Internet.

Once the License Client has started you are presented with a menu of
options which allow you to:

[0] exit
[1] view existing license
[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).

Once you have picked the product to license (ODBC-ODBC Bridge) you
need to supply:

[a] Your full name
[b] Your company name
[c] An email contact address. This (currently) MUST be the email
    address you registered on the Easysoft web site.
[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
   <Enter> 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:
    a) obtain your license at
       http://www.easysoft.com/support/licensing/trial_license.html

       -or-

       http://www.easysoft.com/support/licensing/full_license.html

    b) fax, telephone it.

    The license request is output to license_request.txt.
[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.



3.0 Post Installation
=====================

3.1 Supplied documents and examples
===================================

The last part of the installation runs a post install script which lists
resources available to you. 

o Included documentation is installed in /usr/local/easysoft/oob/doc
  > The OOB manual in PDF format
  > Various files detailing how to get ODBC access with various
    applications and interfaces.
  > Changes.txt - a list of all the changes in each OOB version.
  > FAQ.txt a text version of the OOB FAQ.
  > NEWS.txt - a list of significant releases
  > The client and server licenses
  > Various notes per operating system
  > example odbc.ini entries and descriptions of OOB-specific ODBC connection
    attributes in example_odbc.ini and DSN_definition.txt.
  > The OOB performance white paper.
o examples are installed in /usr/local/easysoft/oob/examples.
o Various Perl, PHP etc tutorials are installed in sub directories
  of /usr/local/easysoft/oob/doc.

There are many resources at the Easysoft web site.

3.2 Post installation steps for non-root installations
======================================================

If you installed the OOB Client as a non-root user (not recommended) then
there may be some manual steps you will need to perform:

[1] If you attempt to install the OOB Client under the unixODBC Driver
    Manager and you do not have write permission to unixODBC's
    odbcinst.ini file the OOB driver cannot be added.

    You can manually install the OOB Client driver under unixODBC by
    adding an entry to the odbcinst.ini file. Run odbcinst -j to
    ascertain the DRIVERS file then append the lines from the oob.tmpl
    (in the directory where the OOB distribution was untarred to) to
    the odbcinst.ini file.

[2] As in [1], no example dsns can be added into unixODBC if you do not
    have write permission to the SYSTEM odbc.ini file. Run odbcinst -j
    to ascertain the name of the "SYSTEM DATA SOURCES" file then
    add your DSNs.

[3] On machines where the dynamic linker has a configuration file
    defining the locations where it looks for shared objects (Linux/FreeBSD)
    you will need to add:

    <install_path>/easysoft/lib
    <install_path>/easysoft/unixODBC/lib

    The latter one is only required if you installed the unixODBC included
    with OOB. Sometimes after changing the dynamic linker configuration file
    you need to run a program to update the dynamic linker cache
    (e.g. /sbin/ldconfig on Linux).

[4] If you did not install OOB in the default location then you need to
    link /usr/local/easysoft to the easysoft directory in your chosen
    install path.

    e.g. If you installed in /home/martin the installation will create
    /home/martin/easysoft and you need to symbolically link 
    /usr/local/easysoft to /home/martin/easysoft:

    ln -s /home/martin/easysoft /usr/local/easysoft

[5] If your system does not have a dynamic linker configuration file you
    need to add the paths listed in [3] above 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 like
    /etc/profile.

    The environment variable differs per dynamic linker. Consult your
    ld or ld.so man page. It is usually:

    LD_LIBRARY_PATH, LIBPATH, LD_RUN_PATH or SHLIB_PATH.

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

The Client side of the OOB comes with an oobping program which can be
used to test connection to an OOB Server. There are two versions of
oobping in /usr/local/easysoft/bin. oobpings is statically linked and
should not require any libraries other than libc (this means you do
not have to set any dynamic linker paths). oobpingd is a dynamically
linked oobping (therefore smaller in size) which requires additional
libraries in /usr/local/easysoft/lib and
/usr/local/easysoft/oob/client). Generally speaking you should use
oobpings.

You can find full instructions on using oobping in the OOB manual,
in the OOB FAQ and a summary of usage options by simply running
oobpings with no arguments.

A short summary is included here:

1. cd /usr/local/easysoft/bin

2. To test an OOB Server is installed, running and listening on a
   specific port use:

   ./oobpings -h myserver -p 8888

   e.g.
  
   ./oobpings -h demo.easysoft.com -p 8888

   The -p 8888 is optional as by default the OOB Server uses port 8888.

3. to test as in (2) plus operating system authentication:

   ./oobpings -h demo.easysoft.com -p 8888 -u demo -p easysoft

4. to do a full test of an OOB Client DSN defined in your odbc.ini
   file use:

   ./oobpings -d "DSN=demo;"

   where "demo" is the name of your OOB Client DSN.

   You can also use oobping to test DSN-less connections by putting all
   the connection attributes in the -d argument e.g.

   ./oobpings -d 'LogonUser=demo;LogonAuth=easysoft;TargetDSN=pubs;UID=demo;PWD=easysoft;Server=demo.easysoft.com;Port=8888;'

3.4 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. You can use unixODBC's
command line isql program to test the OOB Client and issue SQL to your
database. OOB comes with an isql wrapper program called isql.sh
which will set up the dynamic linker before running isql.

The /usr/local/easysoft/oob/examples directory contains a number of
test applications and make files which may be used to try the OOB out.
Please consult the INSTALL.txt file in the examples directory.

