This document is intended to help you test the OOB client installation
using the provided demo application. You should also consult the OOB
FAQ in the OOB doc directory.

OOB client installed on a UNIX operating system
===============================================

Background
==========

The demo program is a small ODBC application linked directly with the
OOB ODBC client driver which is capable of connecting to remote ODBC
data sources on servers where the OOB Server is installed. The C code
for the demo program is included as an example in demo.c and you
should have a make file for your platform so you can build it
yourself.

The demo program is fairly limited and is only really intended to
prove your OOB installation is up and running. It currently has four
ODBC related facilities:

[1] test a connection to a remote ODBC data source by connecting and
    obtaining:

    [a] DBMS Name (this is the remote ODBC DBMS)
    [b] Driver Name (this will always be esoobclient)
    [c] Driver version (this is the OOB client ODBC driver version)

[2] you can run down the DSNs defined in your odbc.ini and test the
    connection to each of them in one go.

[3] if your machine is connected to the internet you can contact our
    demo OOB Server which has a MS SQL Server database containing some
    contact information.

[4] you can test the connection to any server where you have installed
    the OOB server by entering the connection information
    interactively.

We have prebuilt the demo program so you have an executable immediately
after installing the OOB client ODBC driver. You can however rebuild
demo.c yourself with the included make files or edit it and rebuild it
as you wish. See the section on rebuilding the demo program below.

Common Problems
===============

When I run the demo I get an error from the dynamic linker such as
---------------------------------------------------------------------
ld.so.1: ./demo: fatal: libesoobclient.so: can't open file: errno=2
-------------------------------------------------------------------
Killed
------

On some UNIX platforms you need to tell the dynamic linker where to
find the OOB client ODBC driver shared object and all the shared
objects it depends on. You usually do this by setting and exporting an
environment variable containing a colon separated list of paths where
the shared objects are found.

The paths you need to include are:

/usr/local/easysoft/oob/client
/usr/local/easysoft/lib

and optionally, if unixODBC is installed from the OOB distribution

/usr/local/easysoft/unixODBC/lib

The environment variable you set depends on the platform and it will be
one of:

LD_LIBRARY_PATH
LIBPATH
SHLIB_PATH

See the man page for your dynamic linker to find out which environment
variable you need to set (e.g. man ld.so or man ld). Most platforms
use LD_LIBRARY_PATH so you would do the following in the bourne shell:

LD_LIBRARY_PATH=/usr/local/easysoft/oob/client:/usr/local/easysoft/lib
export LD_LIBRARY_PATH

If you are using Linux or FreeBSD the dynamic linker consults a
configuration file which lists the places to look for shared objects
(e.g. /etc/ld.so.conf). The OOB install will have updated this file
for you so you should not get this problem.

When I run the test connection I get a failed to get hostname error
-------------------------------------------------------------------

[a] Examine the odbc.ini file in the examples directory and check the
    Server attribute. This should be the name or IP address of the
    server machine where the OOB Server is running. Check the spelling
    and domain name or IP address.

[b] If you have used a machine and/or domain name is this machine set up
    to resolve host names properly. Check by attempting to ping the
    Server attribute value.

    .e.g. ping demo.easysoft.com

    If you get an error then you may need to set up DNS properly or
    use the IP address instead.

    e.g. ping damo.easysoft.com
    ping: unknown host damo.easysoft.com

    Here the server was misspelt but:

    ping demo.easysoft.com
    ping: unknown host demo.easysoft.com

    Here the resolver (or /etc/hosts.conf) was not set up so there was
    no way to resolve demo.easysoft.com into an IP address.

When I run the test connection I get a connection refused error
---------------------------------------------------------------

The error will look similar to:

08001:1:4:[Easysoft ODBC (Client)]Client unable to establish connection
HY000:2:4:[Easysoft ODBC (Client)]Connection refused, connect(), after 5 attempts

The connection to the server machine was turned down by the operating
system on the server machine. The usual reason for this is that there
is no process on the server machine listening on the specified port.

[a] Check the odbc.ini file in the examples directory and look for the
    Server attribute. This should be the name (e.g. demo.easysoft.com)
    or IP address of the server machine. Is this correct?

[b] Have you installed the OOB Server on the machine named in [a]?

[c] Have you started the OOB Server on the machine name in [a]?

    For Windows 9x (and UNIX when the OOB Server is running
    standalone) you need to start the OOB Server manually.  For
    Windows 9X there is an item off the start menu to start the OOB
    Server up. For UNIX and the OOB Server running standalone (not the
    default configuration) you will need to execute "esoobserver
    standalone"

    In NT/2000 the OOB Server is a service which should have been
    started by the InstallShield installation. However, if you were
    told to reboot after you installed the OOB Server and you have not
    rebooted the OOB Server will not have been started yet -
    reboot. Go to control panel -> Services and look for the Easysoft
    ODBC-ODBC Bridge Server.  If it is not running start it.
    
    The default install of the OOB Server for UNIX installs the OOB as
    a service running under inetd. The installation should add entries
    to /etc/services and /etc/inetd.conf file and send the inetd
    process a signal telling it to reread its configuration. Check the
    services and inetd file for esoobserver entries and send a SIGHUP
    to inetd to make sure it has reread its configuration (see inetd
    man pages).

[d] Check the odbc.ini file in the examples directory and look for the
    Port attribute. This should probably be 8888 (the default for the
    OOB server) but it is [i] configurable during the OOB Server
    installation [ii] changeable post OOB Server installation.

    You can test the OOB Server is listening on a particular port by
    telnetting to that port (telnet server port).

    e.g. telnet demo.easysoft.com 8888

    You should see something like:

87FA9694x1:0:1998-1112-0000000001001:NT^02:4.0.1381^03:Intel^04:4^05:^06:

When I run the test connection I get an ODBC error
--------------------------------------------------

ODBC error diagnostics take the form of a state, a native error number,
component names in square brackets and then some message text.

e.g.
28000:1:1326:[Easysoft ODBC (Client)]Invalid authorization specification

Here the ODBC state is 28000, -1 is the native error number is 1326
and the error is reported by the OOB client. The demo program inserts
a number showing the order in which it got the errors as the second
number between the : separators. The ODBC state may be looked up in
the ODBC specification. If there are more than one set of square
brackets you should read them right to left where the component
reporting the error is in the rightmost [].

There is one exception to the [] rule which is illustrated above. Some
errors the OOB Server reports are before an ODBC connection has been
made. In this case the OOB Server may return an error but it will not
appear in the [] list (as above). In these cases the OOB Server will
set the native error to a number that is relevant for the reason of
failure and these may be looked up in the OOB FAQ. In the above case
1326 is Windows error saying the OOB Server failed to become the
LogonUser using LogonAuth as their password because the username or
password were incorrect.

The native error can be looked up in the documentation for the
component reporting the error.

e.g.

28000:1:18456:
[Easysoft ODBC (Server)][Microsoft][ODBC SQL Server Driver][SQL Server]
Login failed for user 'demo'.

Here SQL Server reports that the database username/password is invalid
for the database being connected to. You could look up 18456 in the SQL
Server documentation for further information.

One very common ODBC error is:

IM002:1:0:[Easysoft ODBC (Client)]
Data source not found and no default driver specified

This occurs if a complete DSN entry cannot be found and there is no
DEFAULT DSN in the odbc.ini file. Please see the FAQ for a list of
places OOB looks for your DSNs. Check the following:

[a] The DSN you are using exists in one of the odbc.ini files OOB
    examines. The OOB FAQ lists all those locations.

[b] The odbc.ini file containing your DSN is readable by you.

[c] Your DSN entry contains at least the following attributes:
 
    Server, Port, Transport, LogonUser, LogonAuth and TargetDSN

    Check the spelling of the attributes names.


Testing OOB ODBC client when you are not internet connected
===========================================================

If your client machine is not internet connected then you cannot test
it by connecting to our OOB Server. However, once you have installed
the OOB Server on one of your own machines you can test a connection
to that instead.

Before attempting this:

[a] Make sure the OOB Server is running on the server machine (see
    above). Note down the server name or IP address as you will use
    this with the OOB ODBC driver Server attribute.

[b] Create a SYSTEM DSN on the server machine which points to the DBMS
    you want to connect to. Note, this is NOT an OOB DSN e.g. if you
    are connecting to MS SQL Server then you create a MS SQL Server
    SYSTEM DSN. Note this DSN name down as you will use it with the
    OOB ODBC driver TargetDSN attribute. If this DSN needs a username
    and password to access it then note these down too and use them
    with the OOB ODBC driver TargetUser/TargetAuth attributes.

[c] Find out the name and password for an account on the machine where
    the OOB Server is running. You should be able to login at the
    terminal on the server machine with this username/password. You
    use this username/password with the LogonUser and LogonAuth OOB
    ODBC driver attributes.

Now start the demo program and select the option to "Test connection
to new database not in odbc.ini". When prompted enter the information
you gathered above. Note that each option has a default in square
brackets where the initial defaults are to connect to our demo server
(pressing enter at a prompt selects the default in square
brackets. You will need to enter something for at least the Server,
LogonUser, LogonAuth and TargetDSN attributes and perhaps also
TargetUser and TargetAuth.

The demo program should test the connection works.

If you select this option again the defaults are now what you entered
the last time.

Rebuilding the demo program
===========================

All the code for the demo program and the makefile that was used to
build it is included in the examples directory. In general the
makefile is named Makefile.<platform> where <platform> is the output
from uname -s. Some distributions contain a Makefile.<platform>_r make
file. If you have one of the those then you have downloaded a version
of the OOB ODBC driver whihc is thread-safe (thread-safe and
non-thread-safe distributions have been separated on some UNIX
platforms due to the problems using changing threads libraries).

You will need a C compiler and linker and make to build the demo (it
is possible to build the demo without make but you will need to
examined the make file and extract the individual cc lines).

To rebuild the demo program use:

make -f Makefile.<platform> demo

e.g. make -f Makefile.linux demo

Here, demo is the target you are asking make to build. If you omit the
demo target then all the examples are built.

There is also a additional target called "clean" which will remove all
the generated object and executable files. Bare in mind that if you
have not changed any of the C source then a make will not build
anything as make will decide everything is up to date. You need to do
a make clean to rebuild everything from scratch.

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      