This file contains instructions on running Applixware with iODBC (as
distributed with Office Suite 99) and the Easysoft ODBC-ODBC Bridge.

At the time of this beta release of the Easysoft ODBC-ODBC Bridge
(OOB) the version of the iODBC Driver Manager distributed with Office
Suite 99 and Applixware is 2.12. However, iODBC-2.50 is now
available. If you want to use iODBC-2.50 see the notes later in this
file.

By default Applixware installs in /opt/applix. This document assumes
that Office Suite 99 was installed in the default directory. If this
is not the case then paths mentioned here will need to be changed to
reflect the different installation path.

By default, the Easysoft ODBC-ODBC Bridge is installed in /usr/local/easysoft.
If you have installed OOB in a different directory then paths mentioned here
will need to be changed to reflect the different installation path.

To access remote ODBC data sources from Office Suite 99 you should follow
these steps:

[1] Install the OOB server on the machine where your ODBC data source
    is located. e.g. if you want to access Microsoft SQL Server or Access
    data bases install the NT OOB Server on your NT machine.

[2] Define a data source on the machine where your have just installed
    the ODBC server. e.g. On NT start up the ODBC Data Source Administrator
    and define a system data source for the required data base.
    NOTE: it is important that the it is a SYSTEM data source on NT or
    the OOB Server may not be able to see it.

    Make a note of the DSN you choose at this step.

[3] Install the OOB client on the machine where Applixware is running.

    Make sure that the dynamic linker can locate the libesoobclient.so
    shared object. You can do this by running ldconfig in Linux or it's
    equivalent in other operating systems. By default, the OOB installation
    will add the path to the OOB client shared object for Linux (see the
    OOB installation notes for further information).

[4] You now need to create a .odbc.ini file in your home directory
    for the iODBC driver manager used by Office Suite 99. Here is an example:

[ODBC Data Sources]
example= oob test

[example]
Driver=/usr/local/easysoft/oob/client/libesoobclient.so

[ODBC]
InstallDir=/opt/applix/axdata/axshlib

    Be careful about using spaces as we have found iODBC-2.12 is a bit
    particular about spaces on the left of the assignments e.g.
    "example = oob test" appeared to cause SQLConnect to be called with
    a DSN of "example " with the trailing space. It is important that
    the line defining the "Driver" points to where the libesoobclient.so
    shared object is located. The Driver assignment above is correct for a
    default installation of the OOB. You should consult the iODBC
    documentation for further details on the format of the .odbc.ini file.

[5] Create an OOB client odbc.ini file in your home directory. An example
    is included with the OOB installation. You should ensure that the DSN
    defined in the OOB client odbc.ini is the same used above for iODBC.
    Here is an example:

    [example]
    TARGETDSN = the_remote_dsn
    SERVER = demo.easysoft.com
    TARGETUSER = db_username
    TARGETAUTH = db_password
    LOGONUSER = remote_username
    LOGONAUTH = remote_password
    TRANSPORT = tcpip
    PORT = 8888

    The TARGETDSN must be set to the name of the DSN on the remote machine.
    e.g. The name of the system DSN you created on an NT machine where
    your database is running. The SERVER attribute should be set to the name
    of the machine where you installed the OOB server and where your remote
    data source is defined. You can omit the TARGETUSER and TARGETAUTH if the
    database engine does not require them (OOB will set the UID and PWD in
    the connection string to the TARGETUSER and TARGETAUTH). The LOGONUSER
    and LOGONAUTH need to be the username and password of someone who can
    log in to the SERVER machine.

You should now be ready to try a test connection. Run up axdata, select
query->choose server and browse the ODBC data sources where you should see
your local example data source. If you select this DSN and then select
query->choose tables you should get a list of tables in your remote
data source. If you set query->auto-query you should see data from
your remote database.

Resolving Problems
==================

[1] When you browse the ODBC data sources from axdata there are none defined.

    You have either not defined any data sources or you have omitted to
    add each ODBC data source to the [ODBC Data Sources] section of
    the .odbc.ini file (see above for an example).

[2] You receive an error dialogue when connecting to the datasource from
    axdata of the form:

    IM003::[iODBC][Driver manager] Specified driver could not be loaded

    The ~/.odbc.ini file does not have a correct Driver entry for the
    the DSN you chose. Ensure that in the DSN you choose, there is a
    line like:

Driver=/usr/local/easysoft/oob/client/libesoobclient.so

    See the example above. You also need to ensure that the dynamic linker
    can locate the libesoobclient.so shared object. See the OOB installation
    notes.

[3] You receive an error dialogue when connecting to the datasource from
    axdata of the form:

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

    The datasource defined in the iODBC .odbc.ini file and which you selected
    in axdata does not exist in the OOB client's odbc.ini file. See the example
    above.

[4] You receive an error dialogue when connecting to the datasource from
    axdata of the form:

IM002::[Microsoft][ODBC Driver Manager] Data source name not found and no default driver specified

    The remote datasource specified in the OOB client's odbc.ini file by
    the attribute TARGETDSN could not be found on the server machine. The
    most likely cause of this is that the data source does not exist but it
    may exist as a USER DSN in which case the OOB Server may be unable to
    see it when logged in as the user specified by LOGINUSER. If the latter,
    then recreate your remote datasource as a SYSTEM DSN.
   
[5] Sometimes you may hit problems with AxData quoting names in
    catalog functions (e.g. SQLColumns) with either [a] the wrong
    quotes [b] or using quotes when they should not be used. You can
    instruct the OOB client to remove these quote for you by adding:

    Unquote_Catalog_Fns = 1

    to the DSN you are using in the odbc.ini file.

    This problem was reported to Applixware 16th March 1999 and
    assigned incident number 4469466.

[6] If you have column names or table names which contain special
    charcters (e.g. _) in an ODBC 3.0 datasource, you may find AXData
    cannot see them. This is because AXData is not aware of the
    SQL_ATTR_METADATA_ID statement attribute which by default treats
    some characters as special (e.g. wildcards). You can instruct the
    OOB client to automatically call SQLSetStmtAttr to set
    SQL_ATTR_METADATA_ID to SQL_TRUE and hence special character
    recognition is removed by adding:

    MetaData_ID_Identifier = 1

    to the DSN you are using in the odbc.ini file.

Using newer versions of the iODBC driver manager
================================================

At the time of this beta release of the ODBC-ODBC Bridge, Office Suite
99 came with iODBC-2.12. Newer versions of iODBC are now available
such as the 2.50 version which forms part of the FreeODBC
kit. Easysoft have tested iODBC-2.50 with Office Suite 99 but it is
beyond the scope of this document to describe how to install newer
versions of iODBC with Office Suite 99. We suggest you contact
Applixware or SuSE for further assistance.









