------------------------------------------------------------------------------
 PxPlus IO Server - Installation README
 
 Copyright 2011-2012, 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 IO Server application on UNIX and Linux systems.

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

The PxPlus IO Server comes in a Tar-Compressed file (.TAZ) which contains
the following files:
    pxpiosvr              IO Server Executable
    libpxpio.so           PxPlus IO Library used by pxpiosvr
    pxpiosvr.conf.sample  IO Server Sample Configuration File
    install.txt           This Installation Readme file
    license.txt           License Agreement
    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:
        pxpiosvr --shutdown
    or
        pxpiosvr -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: file_server_v.vv.vvvv_ddd_www_aaa.taz perform the
following procedure:

   #1 - Obtain the install file: file_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 file_server_v.vv.vvvv_ddd_www_aaa.tar.Z
         mv file_server_v.vv.vvvv_ddd_www_aaa.taz file_server_v.vv.vvvv_ddd_www_aaa.tar.Z

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

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

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

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

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

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

        cp pxpiosvr.conf.sample pxpiosvr.conf

    #8 - Copy librarie to /usr/lib directory:
      cp libpxpio.so /usr/lib/. 

The installation of the IO Server is now complete.

------------------------------------------------------------------------------
Configuring the Server:

To configure the server, use a text editor, e.g. vi, to modify (or create a 
new copy of) the pxpiosvr.conf file. The pxpiosvr.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, and 
any security settings required.

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.

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

To run the server, simply run the pxpiosvr program.

/usr/pxpiosvr/pxpiosvr [-f ConfigFile] [-p TCPPortNumer]

   -f ConfigFile     This is the path and file name of your IO Server
                     configuration file. If not given the server will
                     automatically look for: /usr/pxpiosvr/pxpiosvr.conf

   -p TCPPortNumer   This is the TCP/IP port number the server is to listen
                     on. If given, it will override the port number specified
                     in the pxpiosvr.conf file.

The following arguments can also be used with the PxPlus IO Server 
executable (pxpiosvr) at the command line:

    -h or --help     Displays a message listing the available command line 
                     arguments with brief descriptions.

    -v or --version  Displays the server version information; i.e.,
                     PxPlus IO Server Ver: 5.00.0000 For: AIX 5.3
                     Copyright (c) 2011 PVX Plus Technologies Ltd.

    -d or --debug    Enables output to the debug log file pxpiosvr.log
    
    -s or --shutdown Shuts down the server.
    
------------------------------------------------------------------------------
Starting the IO Server software automatically:

The PxPlus IO 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.

    pvxo:2345:respawn:<path>/pxpiosvr -f <path>/pxpiosvr.conf -p 20222 \
    </dev/null >/dev/null 2>&1
 
    The first entry "pvxo" 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 ProvideX/PxPlus Mail List 
#3 - By contacting PVX Plus technologies Ltd. directly:

PVX Plus Technologies Ltd
4261 Hwy #7 East, Unit A14
Suite 364
Unionville, Ontario, Canada
L3R 9W6
Tel. 1-888-975-7587
www.pvxplus.com
