This file contains information on linking the Easysoft ODBC-ODBC
server with an ODBC driver or driver manager.

The Easysoft ODBC-ODBC Bridge server is distributed as one archive
file, one executable file and four shared objects (this may differ
slightly between platforms depending on the extension for a shared
object).

esoobserver
libserver.a
libdate.so
  (sometimes libdate does not exist as the objects are in libsupport)
libessupp.so (was libsupport.so but renamed due to name clash)
libesrpc.so
libesextra.so (was libextra.so but renamed due to possible name clash)
libeslicshr.so
  (only in OOB post version 1.0.0.0)

Using a Driver Manager or ODBC driver which is a shared object
==============================================================

esoobserver is a binary requiring a libodbc shared object which is
either [1] a driver manager (e.g. unixODBC) or [2] an ODBC driver.  If
you have a driver manager installed (such as unixODBC in the OOB
distribution) then all you need to do is ensure that the driver
manager is called libodbc.<shared object extension> and the dynamic
linker can pick it up for you.

e.g. in Linux and using the unixODBC driver manager, /etc/ld.so.conf
will contain /usr/local/easysoft/unixODBC/lib so that if you type ldd
esoobserver the dynamic linker would say:

libodbc.so.1 => /usr/local/easysoft/unixODBC/lib/libodbc.so.1
libodbcinst.so.1 => /usr/local/easysoft/unixODBC/lib/libodbcinst.so.1
libesrpc.so => /usr/local/easysoft/lib/libesrpc.so
libesextra.so => /usr/local/easysoft/lib/libesextra.so
libeslicshr.so => /usr/local/easysoft/lib/libeslicshr.so
libcrypt.so.1 => /lib/libcrypt.so.1
libm.so.6 => /lib/libm.so.6
libdl.so.2 => /lib/libdl.so.2
libc.so.6 => /lib/libc.so.6
/lib/ld-linux.so.2 => /lib/ld-linux.so.2

On other UNIX platforms, the shell script
/usr/local/easysoft/oob/server/server is automatically created for you
by the installation to set the correct environment variables used by
the dynamic linker. This is how the Easysoft Tetra/CS3 and Zortec
products work out-of-the-box even though OOB and the driver are
separate products.

If you do not have a driver manager then we suggest you get hold of
unixODBC (either the build that is part of the OOB distribution or
build it yourself from the source at http://www.unixodbc.org). If you
have an ODBC driver and have good reason to ignore the advice above
then you need to make sure your ODBC driver is called
libodbc.<shared_object_extension> and follow the instructions for a
driver manager above.

Building with your own driver
=============================

If you use a driver manager none of the following is necessary and is
really here for historical reasons.

The libserver.a archive contains the actual server and requires a
driver containing all the ODBC 3.0 API and some of the ODBC 2.0 API
(although if you are using ODBC 3.0, the ODBC functions may simply be
stubs as they will not be used). You may link the above
libraries/objects together with a driver manager rather than an ODBC
driver.

Assuming your ODBC driver is in libmydriver.a (or libmydriver.[s]o) in
the current working directory you would link the OOB server with the
driver like this:

cc -o esoobserver -L. -L<install_path>/easysoft/lib \
                  -L<install_path>/easysoft/oob/server \
                  libserver.a -lessupp -lesrpc -lesextra -leslicshr \
                  -lmydriver

NOTE: 
libsupport was renamed libessupp and libextra renamed libesextra in
later distributions to avoid a name clash (so amend as necessary -
examine /usr/local/easysoft/lib).  libeslicshr is only in OOB in
versions post 1.0.0.0. If it does not exist in <install_path>/lib then
omit it.

If the driver is an ODBC 3.0 driver then you may have to provide stubs
for some ODBC 2.0 functions such as (SQLAllocEnv, SQLAllocConnect and
SQLAllocStmt) - see below.

The resultant executable (esoobserver) should be copied to the
oob/server subdirectory of the OOB installation directory. Here, there
is a small script ("server") which will be run by the inetd daemon
when an OOB client connects to the OOB server's port.

Using an ODBC 3.n driver with the OOB Server and without a Driver Manager
-------------------------------------------------------------------------

The OOB server is designed to work with or without a Driver Manager.
However, if you use the OOB server with an ODBC 3.n driver and choose
not to use a driver manager then you may need to add some stub
functions to your build for the ODBC 3.0 functions the OOB server
references.

Assuming you have just attempted to link the OOB Server with an ODBC
3.n driver you will probably get undefiend symbols for SQLAllocEnv,
SQLAllocConnect and SQLAllocStmt (or a combination thereof). The OOB
server will not actually use these functions when using ODBC 3.0 so it
is safe to add stub functions that do nothing at all except keep the
linker happy.

These functions should look like this:

SQLRETURN  SQL_API SQLAllocEnv(SQLHENV *EnvironmentHandle)
{
    return SQL_ERROR;
}

SQLRETURN  SQL_API SQLAllocConnect(SQLHENV EnvironmentHandle,
           SQLHDBC *ConnectionHandle)
{
    return SQL_ERROR;
}

SQLRETURN  SQL_API SQLAllocStmt(SQLHDBC ConnectionHandle,
           SQLHSTMT *StatementHandle)
{
    return SQL_ERROR;
}

You will probably have to add a #include from your driver to get the
definitions for SQLRETURN, SQL_ERROR etc (or alternatively use the
odbc.h header file that comes with the OOB client). You should then
compile this C source file and add it to the link line above.


