------------------------------------------------------------------------------
 PxPlus SQL ODBC Driver - Installation README
 
 Copyright 2015-2016, PVX Plus Technologies Ltd.
------------------------------------------------------------------------------
*IMPORTANT* - Please read the License Agreement before installing or using
this product. (see license.txt)

These installation notes cover installing, configuring and using the
PxPlus SQL ODBC Driver and the PxPlus SQL Command Line Client on UNIX and Linux
systems.

------------------------------------------------------------------------------
Dependency:

The PxPlus SQL ODBC Driver requires that unixODBC be installed to work.

Installation:

The PxPlus SQL ODBC Driver comes in a Tar-Compressed file (.TAZ) which contains
the following files:
    pxpsql                SQL Command Line Client Executable
    libpxpio.so           PXPio Library Used By SQL ODBC Driver
    libpxpsqlodbc.so      SQL ODBC Driver
    license.sample        SQL ODBC Driver Sample License Configuration File
    install.txt           This Installation Readme file
    license.txt           License Agreement
    readme.txt            Readme file for this version containing change information.

    
To extract the files from the distribution file: sql_odbc_driver_v.vv.vvvv_ddd_www_aaa.taz perform the
following procedure:

   #1 - Obtain the install file: sql_odbc_driver_v.vv.vvvv_ddd_www_aaa.taz
      where v.vv.vvvv is the version number, i.e.:5.00.0000
      where ddd is the OS description, i.e.: rhel.5 for RedHat Enterprise Linux 5
      where www is the word size, i.e.: 32-bit
      where aaa is the architecture, i.e.: x86

   #2 - Rename the file to sql_odbc_driver_v.vv.vvvv_ddd_www_aaa.tar.Z
         mv sql_odbc_driver_v.vv.vvvv_ddd_www_aaa.taz sql_odbc_driver_v.vv.vvvv_ddd_www_aaa.tar.Z

   #3 - Decompress the tar file: uncompress sql_odbc_driver_v.vv.vvvv_ddd_www_aaa.tar.Z

   #4 - Create the directory to install the software to:
         mkdir /usr/pxpsqlodbc

   #5 - Extract the files to the new directory
         cd /usr/pxpsqlodbc
         tar xvf /<path>/sql_odbc_driver_v.vv.vvvv_ddd_www_aaa.tar

   #6 - Set the file permissions on the pxpsql executable and configuration
   files to whatever is necessary depending on the user name who will run the
   PxPlus SQL ODBC Driver (typically root)

      chmod 500 pxpsql
      chmod 600 license.sample
      chown root *
      chgrp root *

    #8 - Copy libraries to /usr/lib or /usr/lib64 directory:
      cp *.so /usr/lib/. 

    #7 - If this is the first time the PxPlus SQL ODBC Driver has been installed on
    this machine, then copy the "license.sample" file to "license".

        cp license.sample license

The installation of the PxPlus SQL ODBC Driver is now complete.

------------------------------------------------------------------------------
Configuring the SQL ODBC Driver:

To configure the SQL ODBC Driver, use a text editor, e.g. vi, to modify
(or create a new copy of) the license file. The license.sample file contains
documentation at the top of the file on the entries that are required and the
syntax of those entries. This file is used to configure the Activation Information, and 
file write settings.

The SQL ODBC Driver will run in demo mode if not properly activated. A user running
a demo activated SQL ODBC Driver will be notified that they are using a demo.

Next an entry for the PxPlus SQL ODBC Driver must be added to the odbcinst.ini file.
This lets the UNIX/Linux OS know about the SQL ODBC Driver, the entry should look like:

[PxPlus]
Description = PxPlus SQL ODBC Driver
Driver      = /usr/lib/libpxpsqlodbc.so
FileUsage   = 1

The driver name and description can be whatever you want.

The last step is to create a DSN by adding an entry to the odbc.ini file. The
DSN defines what PxPlus data to access and how to access it. The entry should be
made up of connection string keywords and corresponding settings. A couple of parts
are mandatory the rest are optional. The mandatory lines are Driver= and Directory=
or IniFile=. Here is an example:

[PxPlusDSN]
Driver=PxPlus
Description=PxPlus SQL ODBC DSN
Directory=/pxp/data
ViewDLL=/pxp
Debug=1
LogFile=/root/odbc.log
SERVER=NotTheServer

The driver= should use the name of the driver as defined in the odbcinst.ini file
while the DSN name and description can be whatever you want. You must define either
the Directory or IniFile so that the data source knows where the PxPlus data is.

------------------------------------------------------------------------------
Using the SQL ODBC Driver:

The SQL ODBC Driver is used by applications that support ODBC. Some examples are isql,
DataManager, OpenOffice/LibreOffice Calc, and OpenOffice/LibreOffice Base.

To use the SQL ODBC Driver you simply have to run a ODBC application and choose a
DSN you created for the PxPlus SQL ODBC Driver. The ODBC application will then use
the PxPlus SQL ODBC Driver to work with PxPlus data.

The PxPlus SQL ODBC Driver also installs the PxPlus SQL Command Line Client
application. This is a simple application that uses our SQL ODBC Driver directly to
query PxPlus data. It is useful for testing or just getting at the data quick and
can even be called from other applications and scripts.

------------------------------------------------------------------------------
Running the SQL Command Line Client:

To run the SQL Command Line Client, simply run the pxpsql program.

/usr/pxpsqlodbc/pxpsql [Connection Info] [Options] SQL COMMAND

   Connection Info:

   One of the following connection info paramters must be specified

   -d Path or --directory Path    -The path and file name of the DDF file which
                                   is the relative starting point for all
                                   embedded file references.
   -f Path or --config-file Path  -The path and file name of the config file.
                                   Note that if other options are specified they
                                   override configuration in the config file.
   -c Conn_Str or --connection-string Conn_Str
                                  -Specify the connection string directly. This
                                   ignores other connection info parameters.

   These are optional connection info parameters

   -i Path or --ini-file Path     -The path and file name of the INI file used
                                   to define the data dictionary manually for
                                   files that cannot be handled by the PxPlus
                                   embedded data dictionary.
   -v Path or --view-dll Path     -The path and file name of the PxPlus DLL/SO
                                   file. This is required by the ODBC in order
                                   to use the Views system
   -x Paths or --prefix Paths     -Search paths to be inserted in front of all
                                   relative file references. Use comma ',' to
                                   separate multiple prefixes.
   -s Address or --server Address -Network name or IP address required for
                                   connecting to the PxPlus SQL Server.
   -p Port or --port Port         -TCP/IP Port required for connecting to the
                                   PxPlus SQL Server.
   -z or --compression            -Enable ZLib compression to minimize network
                                   traffic between the client and the server.
   -j Name or --company Name      -Value to replace occurrences of %%C$ in a
                                   definition pathname.
   -u Name or --user Name         -Value to replace occurrences of %%U$ in a
                                   definition pathname.
   -w Pass or --password Pass     -Password value, used in conjunction with a
                                   Sage MAS 90 or Sage MAS 200 system only.
   -o ID or--session-id ID        -Value to replace occurrences of %%S$ in a
                                   definition pathname.
   -r or --dirty-read             -Enable dirty read mode which causes normal
                                   file consistency checks to be skipped.
   -e or --enforce-double         -Enable treating numeric data as doubles.
   -b or --burst-mode             -Enable burst mode which reduces the number
                                   of times a file is locked by holding the lock
                                   for either 50 operations or 3/10 of a second
                                   whichever comes first.
   -n or --null-date              -Enable suppression of invalid date error.
   -k or --key-restrict           -Enable key restrict mode. This option allows
                                   the driver to be used with applications that
                                   do not support keys, or supports keys with
                                   limitations.
   -t or --strip-trailing-spaces  -Enabling to strip trailing spaces from key
                                   values when joining multiple tables.
   -q or --silent                 -Enable suppression of most messages.
   -a Size or --cache-size Size   -Amount of memory in MB used for local storage
                                   of intermediate results.
   -l Path or --log-file Path     -Output debugging information to a specified
                                   log file.
   -y or --read-only              -Disable write access for this SQL command.

   Options:

   -g sep or --separator sep      -Set separator string used to update query
                                   results. Default value is "|"
   -m or --html                   -HTML output mode. In this mode query results
                                   are outputted as html table data.

    
------------------------------------------------------------------------------
Obtaining Technical Support:

Technical support for this product may be obtained from several sources:

#1 - The dealer or distributor this product was purchased from
#2 - The PxPlus Web Site (www.pvxplus.com) and / or PxPlus Mail List 
#3 - By contacting PVX Plus technologies Ltd. directly:

PVX Plus Technologies Ltd
25 Centurian Drive, Suite 204
Markham, Ontario, Canada
L3R 5N8
Tel. 1-888-975-7587
www.pvxplus.com
