------------------------------------------------------------------------------
 PxPlus SQL ODBC Driver - Installation README
 
 Copyright 2015-2019, 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
    licenses_3rdparty.txt    3rd Party License Agreements
    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.

------------------------------------------------------------------------------
Activating and Configuring the SQL ODBC Driver:

To activate and 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.

Enter your activation information as follows:

     serial=xxxxx-y- zzzzzzzzzzzzzzzz

Where:
 	xxxxx	Serial number
 	y	User count
 	zzzzzzzzzzzzzzzz	Activation key

If purchasing a Professional or Web edition of PxPlus that includes SQL ODBC Driver support,
you must use the SerialNumber, UserCount, and ODBC activation key of your PxPlus Professional
or Web License.


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=, InstallDir=
and Directory= or IniFile=. Here is an example:

[PxPlusDSN]
Driver=PxPlus
Description=PxPlus SQL ODBC DSN
InstallDir=/usr/pxpsqlodbc
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] COMMAND

Connection Info:

One of the following connection info paramters must be specified

-d Path or --directory Path    -The path of the DDF file which is the
                                relative starting point for all embedded
                                file references.
-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.
--catalog Name                 -Name of catalog. A catalog defines a remote
                                data dictionary and/or INI file and optionally
                                a prefix.
-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

-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.
--ssl                          -Enable secure SSL network communication
                                between the client and the 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.
--legacy-null                  -Enable legacy null mode where empty strings
                                are treated as NULLs.

Options:

-g or --separator              -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.
--column-names                 -Include a header row with column names in
                                the output.

--version                      -Output the version number.

COMMAND is either:

   SQL query e.g. "SELECT * FROM CUSTOMER" used to read or modify data or

   "LIST" command used to display list of table names or

   "LIST Table" command used to display list of column names for given table.

------------------------------------------------------------------------------
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 Forum (forum.pvxplus.com) 
#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
