Please read this carefully BEFORE installing the Easysoft ODBC-SQL 
Server Driver.

These instructions show how to install the Easysoft ODBC-SQL Server 
Driver on UNIX platforms.

The driver requires an ODBC driver manager to be installed on your
system. Easysoft support the unixODBC driver manager
(http://www.unixodbc.org) but this driver can be used with other driver
managers. If you don't have a recognised ODBC driver manager on your
system this installation can install unixODBC for you. The
installation can also tell unixODBC about the driver and create sample
data sources for you.

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/sqlserver/doc
directory before using the driver. 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 1.5Mb.

o You need to be the root user for a successful install on most UNIX
  systems since dynamic linker configuration files and unixODBC
  odbc*.ini files tend to be only accessible by root and at a minimum
  a symbolic link from /usr/local/easysoft to where you installed 
  the Easysoft ODBC-SQL Server Driver is required. No files will be 
  changed without asking first and copies are taken before alteration.

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

Untar the tar distribution file. On some platforms this is gzipped,
compressed or bzipped. This should create a directory called
"odbc-sqlserver-p.q.r-os-var" (where p.q.r is the version, os is the operating
system name and the optional var is a variation for that operating
system) containing some further tar files, some checksum files, this
INSTALL.txt file and an installation script ("install").


NOTE:

Make sure you read the license file, 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>.

You will need approximately 5 Mb of disk space to install all of the
driver.

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 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 autodetect 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, the driver will be installed
in /usr/local/easysoft and below. When installing the driver under an ODBC
driver manager 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.

The driver is now distributed as 2 packaged tar files. These tar files
are for common/driver elements, and optionally the unixODBC Driver
Manager. The tar files are all untarred into subdirectories of
<install_path>/easysoft.

The installation procedure for the unixODBC driver manager will now
start. Your system will be searched for an existing unixODBC and if
one is found the location will be shown. If unixODBC is not found you
have the opportunity to tell the install script where to find it.  You
can use your installed unixODBC in preference to the one included with
this distribution. If unixODBC is not installed on your system the
install script will install it into <install_path>easysoft/unixODBC.

Note: Easysoft builds of unixODBC have sysconfdir set to /etc at build
time.

The installation will next untar the common/driver tar file. Some files
and shared objects are common to multiple Easysoft products. If files
shared between Easysoft products are included in the driver 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

At this stage, some platforms (e.g. Linux, FreeBSD) need to have the
dynamic linker configuration file updated to add the paths to the 
Easysoft ODBC-SQL Server Driver 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 the driver install.

The installation will now install the driver under the unixODBC
Driver manager. Please watch the process carefully as the install uses
unixODBC's odbcinst command to install the driver. In particular you
should note:

[1] If you have had the driver installed in one path and reinstall with
    it in a different path then odbcinst will simply increase the
    driver usage count in unixODBC's odbcinst.ini file but NOT update
    the Driver attribute which points to the IB ODBC driver. You will
    have to do this manually after the installation.

[2] Ignore the text from odbcinst saying "Target directory is xxx".
    The target directory reported appears to have no relevance
    whatsoever.

A demo data source using the ODBC driver called SQLSERVER_SAMPLE
will be added to unixODBC's system DSN list (usually /etc/odbc.ini). 
This is only a sample and some attributes of the data source will 
have to be edited after the install to match the SQL Server you 
want to use connect the driver to.

The driver requires a license. There are currently two types of license.
Trial licenses last approximately two weeks, and allow unlimited
connections to SQL Server but they expire 14 days 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 SQL 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 the Easysoft ODBC-SQL 
Server Driver 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 license.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 driver will not be licensed and
will not accept connections from ODBC applications. 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.

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

Post Installation
=================

After a typical installation the Easysoft ODBC-SQL Server Driver will 
be accessible in /usr/local/easysoft/sqlserver. The installation will 
also have installed:

o the unixODBC driver manager (or used your existing copy)
o installed the driver as an ODBC driver under unixODBC by adding an 
  entry to your odbcinst.ini file.
o installed a sample Easysoft ODBC-SQL Server Driver data source in 
  your system odbc.ini.
o optionally installed a Easysoft ODBC-SQL Server Driver data source 
  for one of your server instances in your system odbc.ini.

NOTE: The unixODBC included with the driver has sysconfdir set to /etc. 
This means if you use the included unixODBC your odbcinst.ini and 
odbc.ini files (defining ODBC drivers and system DSNs) are in /etc. If you
built unixODBC yourself or are using a copy installed from RPM etc it
is more likely that sysconfdir was set to /usr/local/etc when unixODBC
was built. You can check by running odbcinst -j.

If you did not obtain a license during the installation you need to do
this now (you need to run /usr/local/easysoft/license/licshell and see
the license instructions above.

Currently the installation installs the Easysoft ODBC-SQL Server Driver
in odbcinst.ini with a default settings. e.g.

[Easysoft SQL Server]
Description    	= Easysoft ODBC-SQL Server ODBC Driver
Driver          = /usr/local/easysoft/sqlserver/lib/libessqlsrv.so
Setup           = /usr/local/easysoft/sqlserver/lib/libessqlsrvS.so
FileUsage       = 1
DontDLClose     = 1

The sample ODBC data source called SQLSERVER_SAMPLE is installed into
your system odbc.ini file. You need to edit this DSN or create a
different named one with the correct Database location, User, Password,
for your server. The sample one looks similar to this:

[SQLSERVER_SAMPLE]
Driver          = Easysoft ODBC-SQL Server
Description     = Easysoft SQL Server ODBC driver
Server			= server.domain.com
Port			= 1422
Database        = northwind
User            = sa
Password        = password
Mars_Connection     = No
Logging     	= 0
LogFile     	=
QuotedId        = Yes
AnsiNPW     	= Yes
Language        = 

Testing the Driver
==================

To test the driver you need to complete all the processes above in the 
Post Installation section. In particular, you need to edit the sample DSN
or create a new one to match your particular system setup.

Once your DSN is defined you can use unixODBC's isql to try a connection.

e.g.

Suppose the DSN defined in odbc.ini is SQLSERVER_SAMPLE and your 
server needs a username and password of testuser/password then:

cd /usr/local/easysoft/unixODBC/bin (or wherever your unixODBC's isql is)
./isql -v SQLSERVER_SAMPLE testuser password

If this connects you will get a prompt you can start typing SQL into
or just "help" to get a list of tables. Pressing <enter> on a new line
will exit isql.

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 attempt to install the driver under the unixODBC Driver
    Manager and you are not root you will probably get an error from
    odbcinst about a buffer too small. This is a bug in odbcinst. You
    must be root to perform this step. If it fails you will have to
    run odbcinst as root manually. See the unixODBC documentation.

[2] 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 driver 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/sqlserver
    <install_path>/easysoft/lib
