This file contains notes on the ODBC-ODBC Bridge API and functions
where they differ or are enhanced from the ODBC 3.0 API.

SQLDrivers
==========

On non-Windows platforms SQLDrivers is implemented by the ODBC-ODBC
Bridge even though it is a driver manager function. This is primarily
for Perl DBD::ODBC 0.21 support. The ODBC-ODBC Bridge only returns
details about itself and no other drivers.

SQLDataSources
==============

On non-Windows platforms SQLDataSources is implemented by the
ODBC-ODBC Bridge even though it is a driver manager function. User
data sources are found in:

$ODBCINI
./odbc.ini
./.odbc.ini
~/odbc.ini
~/.odbc.ini

and system data sources in /etc/odbc.ini.

If you want to retrieve information about the remote data sources see
SQLBrowseConnect below.

SQLBrowseConnect
================

SQLBrowseConnect is a slightly uncomfortable API in the context of an
ODBC-ODBC bridge.

Normally, SQLBrowseConnect supports an iterative method of discovering
and enumerating the attributes and attribute values required to
connect to a data source. Each call to SQLBrowseConnect returns
successive levels of attributes and attribute values. When all levels
have been enumerated, a connection to the data source is completed and
a complete connection string is returned by SQLBrowseConnect.

This process works fine when SQLBrowseConnect is called for a driver
on the local machine but when you introduce a bridge there are in
effect two levels of browsing. The first level will browse the local
datasources (defined in your odbc.ini file or registry) but these
point to another real datasource on a remote machine.

For this release of the Easysoft ODBC-ODBC Bridge SQLBrowseConnect
only supports browsing the OOB data sources on the local machine so
you will be prompted for ODBC-ODBC Bridge attributes such as:

SERVER
TRANSPORT
PORT
LOGINUSER
LOGINAUTH
TARGETUSER
TARGETAUTH

Once sufficient attributes have been defined to allow a bridge
connection to the server, the server side of the OOB will return a
list of DSNs retrieved by calling SQLDataSources. The browse stops
here and so the remote datasource must already be set up with
sufficient information to allow a connection.

This implementation avoids complications with possible clashes of
attributes between the OOB and the remote ODBC driver which would make
it impossible to return a final connection string which allows a later
connection without browsing.

Extra functions
===============

The non-Windows version of the Easysoft ODBC-ODBC Bridge contains a
few extra functions which are not part of the ODBC API. These are
listed below:

[1] void *enumerate_dsns(void *, unsigned long type)
    where type is 0=user DSNs and 1=System DSNs.
    Call this function to enumerate the list of DSNs in the odbc.ini file.
    The return value is used in further calls to get_next_dsn(). The
    return value will be NULL if no DSNs can be found (e.g. if there is
    no odbc.ini file).

[2] dsn_details_t *get_next_dsn(void *)
    This function returns a pointer to a dsn_details_t which contains
    all the details of the next DSN. You should pass the value returned
    from enumerate_dsns() as a parameter.

A C header file defining these functions and the dsn_details_t
structure are included with non-Windows distributions as
extra.h. There is an example using these functions in the examples
directory called test_ini_dsns.c. Although present these functions are
nolonger required as OOB now supports SQLDataSources.

