------------------------------------------------------------------------------
 PxPlus SQL Server - Installation README
 
 Copyright 2011-2018, 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 running the
PxPlus SQL Server application on UNIX and Linux systems.

------------------------------------------------------------------------------
Installation:

The PxPlus SQL Server comes in a Tar-Compressed file (.TAZ) which contains
the following files:
    pxpsqlsvr                SQL Server Executable
    libpxpio.so              PxPlus File IO Library used by pxpsqlsvr
    pxpsqlsvr.conf.sample    SQL Server Sample 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.

Upgrade Note:
    When shutting down a running server it is best to use SIGHUP:
        kill -1 <server pid>
    rather than a SIGKILL (-9). An alternative to SIGHUP is:
        pxpsqlsvr --shutdown
    or
        pxpsqlsvr -s
    The server uses shared memory and a SIGKILL does not allow the server to 
    remove the shared memory. A new instance of the server cannot be started 
    until the existing shared memory has been removed through either a reboot
    or the use of the ipcs/ipcrm commands.
    
To extract the files from the distribution file: sql_server_v.vv.vvvv_ddd_www_aaa.taz perform the
following procedure:

   #1 - Obtain the install file: sql_server_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.: rel.3 for RedHat Enterprise Linux 3
      where www is the word size, i.e.: 32-bit
      where aaa is the architecture, i.e.: x86

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

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

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

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

   #6 - Set the file permissions on the pxpsqlsvr executable and configuration
   files to whatever is necessary depending on the user name who will run the
   server daemon (typically root)

      chmod 500 pxpsqlsvr
      chmod 600 pxpsqlsvr.conf.sample
      chown root *
      chgrp root *

    #7 - If this is the first time the SQL Server has been installed on this
    server, then copy the "pxpsqlsvr.conf.sample" file to "pxpsqlsvr.conf".

        cp pxpsqlsvr.conf.sample pxpsqlsvr.conf

    #8 - Copy library to /usr/lib or /usr/lib64 directory:
      cp libpxpio.so /usr/lib/. 

The installation of the SQL Server is now complete.

------------------------------------------------------------------------------
Activate and Configuring the Server:

To activate and configure the server, use a text editor, e.g. vi, to modify (or create a 
new copy of) the pxpsqlsvr.conf file. The pxpsqlsvr.conf.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 TCP/IP port 
number the server will listen to, as well as the Activation Information, catalog
definitions, views library path, and any security settings required.

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 server will run in demo mode if not properly activated. An demo activated
server will allow only 1 user to connect and any user connecting will be 
notified that they are connected to a demo activated server.

You MUST define at least one catalog before running the server. To do this
find the "catalogs:" line in the pxpsqlsvr.conf file. If not found add the line
in and make sure it is above the "security:" line. If you find the "catalogs:"
line but it starts with a # then remove the # to uncomment the line. Next you
write a new line underneth the "catalogs:" line to define your catalog. It
should look something like this "myapp=*[/usr/local/myapp][][]".
See the pxpsqlsvr.conf.sample file for details.

------------------------------------------------------------------------------
Running the Server:

To run the server, simply run the pxpsqlsvr program.

/usr/pxpsqlsvr/pxpsqlsvr [options]

Options:
   -h or --help       - Display this help message
   -v or --version    - Display Version information
   -f ConfigFile      - This is the path and file name of your PxPlus SQL Server
                        config file (other default locations will not be checked with this option)
   -p TCPPortNumber   - This is the TCP/IP port number the server is to listen
                        on. If given, it will override the port number specified
                        in the pxpsqlsvr.conf file.
   --ssl sslCertPath  - This is the path and file name of your SSL certificate
                        file. If given, it will enable SSL secure communication.
   -s or --shutdown     - Shuts down server
   -d or --debug        - Output debug information to file:pxpsqlsvr.log
    
------------------------------------------------------------------------------
Starting the SQL Server software automatically:

The PxPlus SQL Server, may be run from the command line, or if you wish to
have it start automatically, you may use whatever method your OS uses to
launch process during its boot cycle. Such as adding an entry into
/etc/inittab for SCO operating systems, or creating a startup script in
/etc/init.d (/etc/rc.d/init.d) for Linux servers, and putting the appropriate
symbolic links into the various /etc/rc?.d directories to have the server
start when the operating system boots.

    Example /etc/inittab entry:
    Note the "\" at the end of the line should NOT be in the inittab file
    but is used here to signify that the remainder of the entry follows
    on the next line.

    pxpo:2345:respawn:<path>/pxpsqlsvr -f <path>/pxpsqlsvr.conf -p 20222 \
    </dev/null >/dev/null 2>&1
 
    The first entry "pxpo" is an ID tag for inittab, most OS's only want 
    a 4 character or less ID name.

    The 2nd entry "2345" are Run-Levels. The OS will launch this command line
    when switch to one of the given Run-Levels. Unixes typically start up in
    Run-Level 2, while most Linux's start in Run-Level 5.

    The 3rd entry "respawn" tells inittab to restart the program if it is 
    not currently running.

    The 4th entry is the command to run. Note that all paths either to the 
    executable or .conf file, should be full path names from the / directory.


------------------------------------------------------------------------------
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 the 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
