Using SQLPlus and hsODBC with OOB to access remote ODBC drivers
===============================================================

This is just a skeleton document at present as Easysoft have not done
this themselves although we have helped customers do this, in
particular on Solaris.

hsODBC, Heterogeneous Services, allows the Oracle listener to connect
to ODBC drivers. You need to configure hsODBC to tell it the drivers
you have and where to find them. Once hsODBC is configured for OOB you
can use SQLPlus to connect to remote databases you have an ODBC driver
for (e.g. MS SQL Server).

Download the correct OOB distribution
=====================================

The Oracle listener is probably multi-threaded in your environment (it
certainly is on Solaris). For this reason you will have to make sure
you download the correct OOB distribution. You will need a thread-safe
distribution (these have "-mt" in the distribution name).

Do you need to use a driver manager?
====================================

All OOB distributions contain the unixODBC driver manager. You need to
decide if you are going to use the driver manager or not. Generally
speaking Easysoft always recommend using the driver manager as it
provides access to multiple ODBC drivers and provides support for
applications written to one ODBC version talking to drivers supporting
a different ODBC version.

If you elect to use the driver manager make sure you choose to install
it during the OOB installation process. The unixODBC driver manager
will be installed in /usr/local/easysoft/unixODBC.

Your decision to use the unixODBC driver manager or not affects how
you set up hsODBC.

Configuring hsODBC
==================

This area is where our information is a little sketchy at present.

You will need to edit your tnsnames.ora file to tell it about hsODBC.

You need to tell hsODBC where to find the ODBC driver. If using OOB
directly without the unixODBC driver manager you need to point hsODBC
at the shared object,
/usr/local/easysoft/oob/client/libesoobclient_r.so (this is the
thread-safe version of the OOB client). If you are using the unixODBC
driver manager you need to point hsODBC at
/usr/local/easysoft/unixODBC/lib/libodbc.so.

Creating your DSNs
==================

Whether you are using the unixODBC driver manager or not you need to
create a DSN in the /etc/odbc.ini file (see the various examples in
this directory).  User DSNs in .odbc.ini in your home account are not
usually usable in this scenario unless you use the home account of the
user your Oracle listener is running as.

A simple example is:

[dsn_name]
# driver tells unixODBC which driver entry to use from the /etc/odbcinst/ini
driver = OOB
# server is the name (or IP address) of where the OOB Server is running
server = ntserver
# port is where the OOB server is listening (8888 by default)
port = 8888
# targetdsn is the name of a system DSN you have set up for your particular
# database on the server machine.
targetdsn = ms_sql_server
# logonuser is a username of the server machine you will connect to the server
# as and password is this user's password. this user must be able to
# log in at the physical console of the server machine i.e. the user must 
# have an operating system account on that machine/domain.
logonuser = username
logonauth = password
# targetuser and targetauth are database usernames and password.
# your database may not require a login in which case omit these.
targetuser = sa
targetauth = password

There are other attributes but this is the minimum required.

Before starting the Oracle listener
===================================

Both the unixODBC driver manager and the OOB driver need additional
shared objects to be picked up at run time. How you tell your dynamic
linker where to look for shared objects varies by platform but it
usually involves setting an environment variable to a colon separated
list of paths where the shared objects can be found.

The paths you will need are:

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

Although not all of these paths are required for all possible
scenarios defining them all will work for all scenarios.

The environment variable to set depends on your platform. It is usually
LD_LIBRARY_PATH although on some platforms it is SHLIB_PATH (HP-UX)
or LIBPATH (some versions of AIX).

The environment variable needs to be set AND exported BEFORE starting the
Oracle listener.

For Solaris in the Bourne shell you need to set LD_LIBRARY_PATH and export
it as follows:

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

Now you can start the Oracle listener.
