Apache Interface
Configuration  
   
Configuring Apache Apache uses a configuration file httpd.conf that is normally found in either in /etc/httpd/conf or /etc/apache2 on Unix or in the Program Files directory for Apache on Windows. Apart from changing this configuration file to meet your own needs, you will need to add a few lines to define the CGI interface for PxPlus.

Two methods can be employed to configure Apache to run the PxPlus interface. You can define it either as a handler based on file suffix or as a script processor based on a pattern match.

Defining PxPlus Interface as a Handler:

To define the interface as a handler the following lines need to be added to the Apache config:

#
# PxPlus program CGI handler
#
AddHandler pxplus-srvr .pxp .pvp
Action pxplus-srvr /cgi-bin/pxp.cgi

The first line defines the suffixes that the CGI interface will handle. In the above example, any requests for a file with a .pxp or .pvp suffix will be handled by the pxplus-srvr interface. The second line identifies that the pxplus-srvr interface will run the CGI script in /cgi-bin/pxp.cgi file.

When configured as a handler the requests must come in with a standard/defined suffix such as .pxp or .pvp. This suffix must be the last part of the requested file name thus, you cannot use entry points (e.g. www.mysite.com/orders/entry.pxp;Chk_cust will not work since .pxp is not the last part of the request).

Defining PxPlus Interface as a Script Processor:

To define the interface as a Script processor the following line needs to be added to the Apache config:

#
# PxPlus as a script processor
#
ScriptAliasMatch <regexp> /var/www/cgi-bin/pxp.cgi

The ScriptAliasMatch allows you to specify a regular expression that will be used to match up with the incoming request. If the request matches the regular expression, the CGI script file will be processed. Some typical regular expressions are:

\.pxp Request contains ".pxp"
/prog/ Request contains "/prog/"
/orders/*.pxp Request contains request for /orders/ directory and has pxp following
The actual configuration of the Apache HTTP server is beyond the scope of this document. Please see the documentation provided with the Apache software or consult www.apache.org for details on the general configuration and setup of an Apache HTTP server.

The CGI Script File on Unix/Linux:

You then need to create the CGI script file pxp.cgi. This file should contain the following:

#!/bin/bash
/pxplus/pxplus /pxplus/lib/_plus/apache/pxp_cgi -arg <args>

It must also be set with execute permissions for the Apache server.

On some Unix systems you may need to include the following line just before the command to run PxPlus (/pxplus/pxplus).

export TERM=unknown

The CGI Script File on Windows:

The CGI script file for windows is fundamentally the same as the file on Unix however instead of running the OS shell script (bash) you will run PxPlus directly. A typical CGI script file for Windows would be as follows:

#!"C:\Program Files\...\...\pxplus.exe" *plus/apache/pxp_cgi -arg debug

The actual pathname to the pxplus.exe will need to be tailored to suite your installation and the version number of PxPlus you are using. The quotes around the pathname are needed since the pathname will likely contain spaces.

Click here for details on how to do a sample/demo Windows installation.
 
Arguments used by pxp_cgi program:

The pxp_cgi program can be passed a number of parameters in the form of command line arguments in the CGI script file. These arguments are:

Arg value Purpose/Function
debug Indicates that the process is to be run in debug mode. The output will be deferred until the processing terminates properly. If an error should occur, a variable dump will be reported.
cookie or cookies Indicates that the programs being run are using the *web/cookie subprogram to generate and send cookies. If this variable is not set, only inbound cookies will be supported. Sending of cookies to the workstation will not be supported. This feature defers output until after the program completes thus performance is slightly slower than when cookies are not supported
noglobal Prevents any HTTP request from altering the value of any global variable. This can increase the security of the web site should the applications utilize global variables. Note that the global variables used to locate the application and control cookies are never allowed to be altered.
task=nn Allows the designer to establish the maximum number of concurrent tasks that the server will process. If omitted, the system will support up to the maximum user count on the PxPlus license. This option allows for sharing user counts between Web services and other PxPlus users by limiting the number of Web tasks active at any given time.
timeout=nn Changes the default 30 second timeout for the maximum run time that a task can take. If a spawned task takes longer than the number of seconds in the timeout period, the system will terminate the task and report an error.
wait=nn This option can be used in conjunction with the Task=nn option to set a limit as to how long a web user will wait (in seconds) until an online task is available. This allows a fallback for the Apache interface to borrow non-Web users in periods of heavy load. For example, '-arg Task=5 Wait=3' would normally allow up to 5 concurrent web tasks, however should a web task wait longer than 3 seconds for a slot to become available, the system will allow the task to start regardless. Wait=0 (the default) will cause the task to wait forever.

Multiple script files can be used to define different options by using different file names and Apache configuration lines.

Dynamic Timeout Control:

Using the "*system" object your application can change and/or disable the timeout settings. Simply instantiate the "*system" object then invoke the 'SetTimer( ) method passing it the new timeout value in seconds. Passing it a value of zero disables the timeout.

sysobj = new("*system")
...
sysobj'SetTimer( new_timeout )
*Note* Security Note: On some Linux systems (Fedora Core in particular), the Apache server is restricted as to which directories it can access using SELinux. You may have to alter these settings in order to run the Apache server.
Start_up Program Like any PxPlus application, whenever the Apache server starts up a PxPlus application, it will first run the START_UP program located in the cgi-bin directory. This start up program can establish global variables, open files, and set other environment variables, as required.

If desired, the START_UP program can be located elsewhere or given a different name by setting the system ENV variable "PVXSTART" prior launching PxPlus. This environment variable can be set in the Apache config file using the SetEnv directive. This allows you to have multiple start_ups, each for different sites.

For example, if you had multiple 'Virtual sites' within your Apache configuration and wanted siteabc.pvxplus.com to use Start_ABC as its start up your config could be set to:

<VirtualHost 192.168.1.200:80>
ServerName siteabc.pvxplus.com
DocumentRoot "/var/www/siteabc"
DirectoryIndex welcome.pxp
SetEnv PVXSTART Start_ABC
Alias /images/ "/var/www/common/images/"
</VirtualHost>
HTTP Call Configuration If the APACHE server is to service PxPlus CALL "[HTTP: ...]" or CALL "[HTTPS: ...]" requests (see [HTTP] command tag), it will need to include the following line in the APACHE configuration:

#
# PxPlus HTTP interface CGI definition
#
AddHandler pxplus-call .pxc
Action pxplus-call /cgi-bin/pxcall.cgi

The first line defines the .pxc suffix that is required for any CALLed program and will be provided within the SOAP/XML request generated by the caller. The second line identifies that the pxplus-call interface will run the CGI script in /cgi-bin/pxcall.cgi file.

The CALL "[HTTP:...]" CGI Script File on Unix/Linux:

You then need to create the CGI script file pxcall.cgi. This file should contain the following:

#!/bin/bash
/pxplus/pxplus /pxplus/lib/_plus/apache/pxp_call

It must also be set with execute permissions for the Apache server.

The CALL "[HTTP:...]" CGI Script File on Windows:

The CGI script file for windows is fundamentally the same as the file on Unix however instead of running the OS shell script (bash) you will run PxPlus directly. A typical CGI script file for Windows would be as follows:

#!"C:\Program Files\...\...\pxplus.exe" *plus/apache/pxp_call

The actual pathname to the pxplus.exe will need to be tailored to suite your installation and the version number of PxPlus you are using. The quotes around the pathname are needed since the pathname will likely contain spaces.

*Note* Samples of the Unix and Windows cgi files are included in the files unix.pxcall.cgi and windows.pxcall.cgi files found in the "_plus/apache" library directory.