Please read this carefully BEFORE installing The Easysoft XML-ODBC
Server.

These instructions show how to install The Easysoft XML-ODBC Server on
UNIX platforms. For other platforms see the XML-ODBC Server manual.

This distribution contains 4 components:

common
  items common to all other components in this distribution and
  documentation
sample clients
  working clients in C, Perl, PHP, Java etc for the XML-ODBC server.
unixODBC
  the unixODBC driver manager and utilities
Server
  the XML-ODBC Server

You may install the sample clients or both the clients and the
server. Note, that if you only want to access ODBC databases through
drivers on remote machines from this machine you only need the sample
clients.

If you have ODBC drivers on this machine (e.g. Easysoft's Tetra/CS3 or
Zortec ODBC drivers) which you want to access from other machines you
should install the server too. You must be root to install the server
properly as it requires entries in your services and inetd
configuration files.

If you already have the unixODBC Driver Manager installed on your
machine the installation of the XML-ODBC Server can automatically make
use of it. This installation contains the unixODBC Driver Manager and
it is strongly recommended that you install this copy as we have
tested it with the XML-ODBC Server. Note versions of unixODBC prior to
2.2.2 have problems with UNICODE which will prevent XML-ODBC working
properly.

PLEASE REMOVE AN OLD INSTALLATION TREE BEFORE reinstalling or
installing a new version in the same tree. See the file uninstall.txt
for instructions on how to do this.

After installing consult the documents in the easysoft/xml-odbc/doc
directory before using Easysoft XML-ODBC. In particular, read
carefully the document for your specific operating system.

Requirements
============

The installation script has a minimal set of requirements:

o Bourne shell in /bin/sh (if your Bourne shell is not located there you
  may need to edit the first line of the install file).

o Various commonly used UNIX commands such as:

  grep, awk, test, cut, ps, sed, cat, wc, uname, tr, find, echo, sum, head,
  tee, id

  If you are missing any of these commands they can generally be
  obtained from the Free Software Foundation. As some machines have a
  broken tee command the distribution comes with a tee replacement.

o Depending on the platform, you will need up to 5Mb of disk space
  free for the installed programs and up to 5Mb temporary space of the
  installation files themselves. If you install the unixODBC Driver Manager
  as well, these numbers increase by approximately 3Mb.

o If you are only installing the sample clients then you do not have
  to be the root user. You must be root to install the server
  properly. Easysoft recommend you install all the XML-ODBC components
  as the root user.

The installation process
========================

Untar the tar distribution file. On some platforms this is gzipped,
compressed or bzipped. This should create a directory called
"xml-odbc-p.q.r.os{-mt}" (where p.q.r is the version, os
is the operating system name and the optional -mt stands for
multi-threaded or thread-safe) containing some further tar files, some
checksum files, this INSTALL.txt file and an installation script
("install").


NOTE:

Make sure you read the license files. There are two licenses, one for
client only installations (Client-License.txt) and one for
client/server installations (Server-Client-License.txt).  Installing
the software on your machines shows your acceptance of the terms and
conditions in the License.

Throughout the installation you may be asked to supply the answer to
some questions. In each case the default will be displayed in square
brackets and you need only press <return> to take the default.  If
there are alternative responses these will be shown in round brackets;
to pick one of these type them and press <return>.

If you are only installing the sample clients, then it is only
necessary to be the root user if the directory to install in requires
root privilege. You will need approximately 5 Mb of disk space to
install both the sample clients and server, the documentation and
examples.

Change into the created directory and run the install program with
./install.

You will be prompted to read the License file appropriate for your
installation and you must answer yes to to accept the license.  If
you do not accept the license, then the installation will be aborted.

Once the installation has checked you have the necessary shell tools
it will auto detect the operating system and check any required
dependencies (e.g. version of the C runtime library). Next the install
checks the encapsulated tar package(s) by comparing them with a
checksum file (do not worry if the md5 checksum is not found as some
platforms do not come with md5sum). If this fails you will be given
the opportunity to abort the installation.

You will next be prompted for an installation path. All files are
installed in a subdirectory of your specified path called "easysoft"
e.g. if you pick the default of /usr/local, XML-ODBC will be installed
in /usr/local/easysoft and below. If you are also installing the
server side of XML-ODBC then some files outside the installation path
will be modified (but not without prompting you first - see later).

If you choose an install path different from the default then the
installation will try to symbolically link /usr/local/easysoft to the
easysoft in your chosen path. This allows us to distribute binaries
with built in dynamic linker run paths. If you are not root or the
path /usr/local/easysoft already exists and is not a symbolic link
this will fail (see later for how this may be corrected manually).
You should note that you cannot license Easysoft products until
/usr/local/easysoft exists either as a symbolic link to the real
install path or as the install path itself.

XML-ODBC is distributed as 4 packaged tar files. These tar files are
for common elements, the clients, the server and optionally the
unixODBC Driver Manager. The tar files are all untarred into
subdirectories of <install_path>/easysoft.  You can consult
<install_path>/easysoft/xml-odbc/INVENTORY.txt for a description of
all the files installed.

If the distribution for your platform contains the unixODBC driver
manager you will now be asked whether you would like to install
it. Please read the notes in the installation prior to this question
as you do not have to install unixODBC. Generally speaking, you should
install the unixODBC driver manager if you install the XML-ODBC
Server.

If you chose to install unixODBC it is untarred in to the
<install_path>/easysoft/unixODBC directory. This build of unixODBC has
the sysconfdir set to /etc at build time so system DSNs must be placed
in /etc/odbc.ini.

The installation will next untar the common tar file. Some files and
shared objects are common to multiple Easysoft products. If files
shared between Easysoft products are included in the XML-ODBC install
the installation will check to see if those files already exist or are
older. Only if these files do not exist or are older will the shared
files be installed. You may see messages like:

versioned shared file <filename> does not exist - installing

or

versioned shared file <file> is old - replacing

Then if you choose to install the sample clients the client tar file
will be untarred. You need the sample clients to access remote ODBC
drivers on machines where you have installed the XML-ODBC Server.

The remainder of the installation installs the XML-ODBC server and
requires the installer to be the root user. If you are not root the
installation will terminate now.

The XML-ODBC Server requires a license in order to accept connections
from the clients. There are currently two types of license.  Trial
licenses last approximately one month and allow unlimited connections
from clients but they expire one month after a license is
obtained. Full licenses (available for purchase) are available with
unlimited concurrent connections. The installation will create the
<install_path>/license directory if it does not exist and also a
licenses template file in that directory.  You can obtain a trial
license or register a full license automatically during the
installation. When prompted to request an XML-ODBC Server license, enter
'y' and the Easysoft License Client program will be started for you.

To obtain a license automatically you will need to be connected to the
Internet and allow outgoing connections to license.easysoft.com on port
8884.  If you are not connected to the Internet or do not allow
outgoing connections on port 8884 then the License Client can create a
license request file which you can mail, fax or telephone to Easysoft.

Once the License Client has started you are presented with a menu of
options which allow you to [0] exit, [1] view existing license [2]
show product list or [n] obtain a license for the desired
product. Obviously, if you have not got any other Easysoft products
licensed then option [1] will not show any existing licenses. To
obtain a license select one of the options from [2] onwards for the
product you are installing. The License Client will then run a program
that was installed for that product which generates a key which is
used to identify the product and operating system (we need this key to
license you). NOTE, some products in the list may not be licensable
during the install, e.g. if you are installing XML-ODBC and do not
have the Easysoft JDBC-ODBC Bridge installed then you cannot obtain a
license for the JDBC-ODBC Bridge (in this case the License Client will
probably output a warning that the siteinfo command for the chosen
product was not found). Assuming you have picked a product which is
installed (or in the process of being installed) then you need to
supply:

[a] Your full name
[b] Your company name
[c] An email contact address (you need to specify this if you email the
    license request to us).
[d] Your telephone number (you need to specify this if you telephone
    the license request to us).
[e] Your fax number (you need to specify this if you fax the license
    request to us).
[f] A reference number. When applying for a trial license just hit
   <return> on this field as this field is used to enter a reference
   number we will supply you for full (paid) licenses.

You will then be asked for a method of obtaining the license where the
choices are:

[1] Automatically by contacting the Easysoft License Daemon
    (this requires connection to the Internet and the ability to support
     an outgoing TCPIP connection to ai.easysoft.com on port 8884).
[2] Write information to file so you can fax, telephone it
    (the license request is output to license_request.txt and you can
     telephone or fax this to Easysoft).
[3] Cancel request

If you choose to obtain the license automatically, the License Client
will start a TCPIP connection to license.easysoft.com on port 8884 and
send the details you entered at the prompts above and your site
number.  No other data is sent. The data sent is transmitted as plain
text so if you do not want this information possibly intercepted by
someone else on the net you should choose [2] and telephone or fax the
request to us.  The License daemon will return the license key, print
it to the screen and make it available to the installation script in
the file licenses.out.

If you choose option [2] the license request is written to the file
license_request.txt and you should exit the License Client via option
[0] and complete the installation. Once you have mailed, faxed or
telephoned the license request to us we will return a license key
which should add to the end of the file
<install_path>/easysoft/license/licenses.

If during this process any warnings or errors are output please mail
the output to support@easysoft.com and we will rectify the problem.

If you ran the License Client (above) the install script will detect
whether any licenses were automatically obtained and ask you if they
are to be installed in the <install_path>easysoft/license/licenses
file. You should answer y to this or the XML-ODBC Server will not be
licensed and will not accept connections from clients. If you choose
not to have the licenses added to the licenses file then you can do
this manually later by copying the lines in licenses.out to
<install_path>/easysoft/license/licenses.

At this stage, some platforms (e.g. Linux, FreeBSD) need to have the
dynamic linker configuration file updated to add the paths to the
XML-ODBC shared objects. If this is the case, then the install will
add paths to the dynamic linker configuration file
(e.g. /etc/ld.so.conf for Linux) and ask the dynamic linker to re-read
the configuration file (e.g. /sbin/ldconfig for Linux). If the dynamic
linker configuration file already contains non existent paths you may
see warnings that are nothing to do with this install.

The installation then attempts to find your {x}inetd and services
configuration files. If these are located successfully it will check
there is no other service called "esxmlodbcserver" and no other
service using port 8895. If there is a conflict with either the
service name or port you will be given a chance to change (or
overwrite) them in which case you should pick any name you like for
the service which is not already in use and an unused port. Once the
service name and port are finalized, an entry will be added to the end
of the {x}inetd and service configuration files. The installation will
show you which files are being changed and which entries are being
added. The final part of defining the server environment is creating a
script in <install_path>/easysoft/xml-odbc/server which will be run by
{x}inetd when the OOB client connects to the specified port. Once this
is complete the {x}inetd daemon is asked to reread the configuration
files so it may listen on the specified port on behalf of the XML-ODBC
server.

NOTE:
The shared objects installed are NOT stripped. You may strip them if
you wish but this may affect any support Easysoft can supply.

Testing the XML-ODBC server
===========================

The XML-ODBC Server is dynamically linked with libodbc in which case
libodbc may be any ODBC driver you have or a driver manager such as
the unixODBC DM (recommended)(the unixODBC driver manager is included
in the XML-ODBC distribution). The Server archive file is also
supplied in case you would like to relink the server yourself.

If you have a running server you may telnet to the service
"esxmlodbcserver" on port 8895 (or if this was in use the server name
or port you specified during installation) to test the server is
working correctly:

telnet localhost esxmlodbcserver OR
telnet localhost 8895

(Substitute esxmlodbcserver and 8885 with the service name and port used
in the installation).

If the server is configured correctly and listening you should be
connected (control D or control ] to escape).

To test the server functionality properly consult the section below on
testing with an XML-ODBC sample client.

Testing a sample XML-ODBC client
================================

There are various XML-ODBC Server sample clients provided in the
distribution (C, Perl, PHP, VB and netpipes being some). Probably the
easiest client to use initially is the client built from C source as
it is prebuilt and requires nothing more than your run-time C library
and perhaps a socket library (both of which you will already have on
your machine). To use the other sample clients consult the README.txt
files in the <installdir>/xml-odbc/clients/<client> directories.

cd /usr/local/easysoft/xml-odbc/clients/c
./xmlodbc_client

You should get usage instructions for this sample XML-ODBC client.

To test a XML-ODBC Server you will need:

hostname
  the server hostname, where a listening XML-ODBC Server is installed.

port
  the port where the XML-ODBC Server is listening (this defaults to
  8895 if the port is omitted)

connection string
  a valid ODBC connection string defining a system ODBC data source
  on hostname. An example is:

  DSN=SYSTEMDSN;UID=dbuser;PWD=dbauth;

  Here, SYSTEMDSN is the name of a SYSTEM ODBC data source on hostname
  that require database authentication with a username of dbuser and a
  password of dbauth. Some data sources may need additional connection
  attributes (consult the documentation for the ODBC driver you are
  connecting to). ODBC defined that each attribute in the connection
  string should be separated by a ';'.

sql
  The SQL you want to run. Generally this is a SQL query but it can
  also be an insert, update etc statement. Any valid SQL.

e.g.

Suppose we have the XML-ODBC server installed on the server 'myserver'
listening on the default port (8895). There is a SYSTEM DSN called
MYDSN for MS SQL Server which requires a database login of myusername
and mypassword. The MYDSN data source points to a MS SQL Server
database containing a table called mytable. We could issue the
following command to xmlodbc_client:

./xmlodbc_client -h myserver -c 'DSN=MYDSN;UID=myusername;PWD=mypassword;'
                 -s 'select * from mytable'

This would return the contents of mytable in XML to stdout. To
redirect the XML result-set to a file add -f outfile to the
xmlodbc_client command line.

The format of the XML output is described by files in the
<installdir>/xml-odbc/doc directory.

Installation Warnings and Failures
==================================

There are a number of ways in which part of the installation may fail.
Here are a few minor problems and their resolution:

[1] If you specify an installation path different from the default
    (/usr/local) then the installation script will attempt to link
    /usr/local/easysoft to <install_path>/easysoft. The install does
    this because some of the binaries are linked with a run path
    for the dynamic linker. The installation will only attempt to create
    this link if:

    [a] /usr/local/easysoft does not already exist.

    [b] /usr/local/easysoft already exists but is a symbolic link in
        which case you will be asked to confirm first.

    [c] if you specified a different install path from the default.

    If the installation cannot create the link then you may have to fix
    this yourself or define LD_LIBRARY_PATH/LD_RUN_PATH to contain the
    paths:

    <install_path>/easysoft/lib
    <install_path>/easysoft/unixODBC/lib

    If you are using the XML-ODBC Server on the machine where the
    symbolic link could not be created there is no alternative but to
    create the symbolic link. Licensing in the XML-ODBC Server will
    not work without it.

