This file contains instructions on running mxODBC with the Easysoft
ODBC-ODBC Bridge.

mxODBC is available at http://www.egenix.com/files/python/mxODBC.html.
From the web page:

"The mxODBC package provides a nearly 100% Python DB API compliant
interface to databases that are accessible via the ODBC API."

Contents:
o Tested Versions
o Building mxODBC against OOB
o Testing OOB with Python and mxODBC

Tested Versions
---------------

The Easysoft ODBC-ODBC Bridge (OOB) has been tested with:

o mxODBC-1.0.1 and mxODBC-pre1.0.2 with Python-1.5.1/1.5.2.
o mxODBC 2.0.6 and Python 2.3.3

Building mxODBC against OOB
---------------------------

These instructions are for UNIX users. Windows users can use the
OOB client ODBC driver like any other ODBC driver.

Marc-Andre Lemburg (author of mxODBC) has added a configuration
section to mxODBC specifically for OOB. This is a significant help in
building mxODBC against OOB. However, for recent versions of mxODBC
(2+) we strongly recommend building mxODBC with unixODBC support.

You should follow the installation instructions for mxODBC at the
web page above.

Here is an example using mxODBC 2.0.6:

Install OOB and the included unixODBC

Get egenix-mx-base-2.0.5.tar.gz, unpack and cd into the created dir.

Read README which says to do:

python setup.py install

Get egenix-mx-commercial-2.0.6.tar.gz, unpack and cd into the created dir.

Edit mxCOMMERCIAL.py and look for:

    packages[len(packages):] = [

        #
        # These are the subpackages which the installer will install.
        # If you want to disable installing one of the default
        # subpackages or would like to add a new subpackage, edit this
        # list accordingly and also add an Extension() entry in the list
        # of C extensions below. You should use the information from the
        # Setup file in the subpackage to modify the Extension() entry as
        # needed.
        #
        'mx.ODBC.iODBC',
        'mx.ODBC.unixODBC',

Delete the line containing 'mx.ODBC.iODBC'.

Look for the lines:

        Extension('mx.ODBC.iODBC.mxODBC',
                  ['mx/ODBC/iODBC/mxODBC.c',
                   'mx/ODBC/iODBC/mxSQLCodes.c'
                   ],
                  include_dirs=['mx/ODBC/iODBC',
                                '/usr/local/iODBC/include'],
                  define_macros=[('iODBC', None)],
                  library_dirs=['/usr/local/iODBC/lib'],
                  libraries=['iodbc']
                  ),

and delete them.

a) If you are using the unixODBC that comes with OOB:

  In :

        Extension('mx.ODBC.unixODBC.mxODBC',
                  ['mx/ODBC/unixODBC/mxODBC.c',
                   'mx/ODBC/unixODBC/mxSQLCodes.c'
                   ],
                  include_dirs=['mx/ODBC/unixODBC',
                                '/usr/local/unixODBC/include'],
                  define_macros=[('unixODBC', None)],
                  library_dirs=['/usr/local/unixODBC/lib'],
                  libraries=['odbc']
                  ),

  change all occurrances of "/usr/local/unixODBC" to
  "/usr/local/easysoft/unixODBC".

b) If you are using a copy of unixODBC you installed yourself then
   make sure include_dirs and library_dirs above are correct for
   where you installed unixODBC.

run python setup.py install (as per mxODBC's README)

Testing OOB with Python and mxODBC
==================================

Create a data source in the unixODBC's /etc/odbc.ini file and test
it with unixODBC's isql command to make sure it works.

For example, the data source below:

[testOOB]
Driver = OOB
Server = mywindowsserver
Port = 8888
Transport = tcpip
LogonUser = mywindowsusername
LogonAuth = mywindowspassword
TargetDSN = sqlserverdsn
TargetUser = sqlserverusername
TargetAuth = sqlserverpassword

defines an OOB client DSN called "testOOB" pointing to an OOB Server
on mywindowsserver where there is a MS SQL Server ODBC driver SYSTEM
DSN called sqlserverdsn. The LogonUser/LogonAuth are a valid windows
username/password to login to mywindowsserver and TargetUser/TargetAuth
are a valid SQL Server database login. The TargetUser/TargetAuth are
not required when running isql as you need to specify them on the command
line.

cd /usr/local/easysoft/unixODBC/bin

./isql -v testOOB sqlserverusername sqlserverpassword

This should connect and you'll get a prompt where you can type "help"
to get a list of tables. Just hit return on an empty prompt line to
exit.

Run python from the command line to get a python prompt. The session
below is an example.

# python
Python 2.3.3 (#1, Jan 22 2004, 11:19:32)
[GCC 2.95.2 19991024 (release)] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> import mx.ODBC.unixODBC as mx
>>> db = mx.DriverConnect('DSN=oobTest')
>>> c = db.cursor()
>>> c.tables()
-1
>>> res = c.fetchall()
>>> print res

This should print a list of tables in your database.

Please note that the syntax "import xxx as <something> is a relatively
new addition to Python (certainly in Python 2.3.3). If your Python
produces a syntax error for this omit the "as mx" and replace "mx."
with "mx.ODBC.unixODBC".
