This file contains instructions on running Applixware with the
Easysoft ODBC-ODBC Bridge. Easysoft have tested OOB with Applixware

[1] 4.4.1 (which used iODBC driver manager)
    as distributed with Office Suite 99
[2] 4.4.2
[3] 5.0 (beta and final release)
    5.0 uses the much more popular unixODBC driver manager.

Applixware 5.0
==============

Applixware 5.0 uses the unixODBC driver manager straight out of the
box.  As a result, setting up data sources with unixODBC for use with
OOB is all documented in the OOB manual (pdf and HTML) available from
ftp://ftp.easysoft.com/pub/docs/oob.

Please note that in Applixware Office 5.0, the included unixODBC
appears to have been built with --sysconfdir=/usr/local/etc so you
should symbolically link /usr/local/etc/odbc.ini to /etc/odbc.ini and
/usr/local/etc/odbcinst.ini to /etc/odbcinst.ini after installing OOB
and Applixware Office 5.0.

Some of the comments below for 4.4.1 and 4.4.2 apply.

Applixware 4.4.1 and 4.4.2
==========================

At the time of this release of the Easysoft ODBC-ODBC Bridge (OOB) the
version of the iODBC Driver Manager distributed with 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 Applixware 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

    NOTE: Instead of creating a separate odbc.ini file the OOB can use
    the same .odbc.ini file that iODBC uses; in case place the
    attributes for the [example] DSN under [example] in the .odbc.ini
    file.

    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.

[6] Easysoft found that after installing Applixware via the RPM's that
    the dynamic linker could not find libodbc.so (iODBC) because the
    /etc/ld.so.conf file did not mention
    /opt/applix/axdata/axshlib/lib. We added
    /opt/applix/axdata/axshlib/lib to /etc/ld.so.conf and reran
    /sbin/ldconfig to inform the dynamic linker of the path to
    libodbc.so.

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 data source
    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 data source
    from axdata of the form:

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

    The data source 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 data source
    from axdata of the form:

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

    The remote data source 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 LOGONUSER. If the latter, then recreate your remote
    data source 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
    characters (e.g. _) in an ODBC 3.0 data source, 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.









