PicLan-IP Web Server Configuration

The PicLan-IP Web Server is configured using a text item similar in format to the PicLan-IP TCP/IP stack configuration.

In pervious releases of PicLan-IP, configuration entries were scattered among multiple configuration items. With PicLan-IP build 2.0.0(106), all of the configuration items have been consolidated into PLIP.CTRL CONFIG. Any reference to other configuration items are obsolete.

The PicLan-IP Web Server Configuration Files

The web server configuration is located in PLIP.CTRL CONFIG. This is a sample PicLan-IP Web Server configuration item:

HTTP DIR=*:80 / FILE WWW.ROOT (S

Web Server Virtual Directories

A web server is organized into "virtual directories". This structure allows you to store web documents in logical groupings. The example above demonstrates the simplest structure. With this configuration the web server will listen on the default IP port (the first port listed in the TCP/IP stack configuration file) on TCP port number 80 (the default for HTTP). The content is stored in a MV file named WWW.ROOT. The (S option indicates that the file can contain both plain items as well as items that include what looks like a directory path (ie, both INDEX.HTM and IMAGES/MSC_COL2.GIF).

Web Server MV File Structure

Beginning with this build 2.0.0(106), the PicLan-IP web server no longer requires individual multiple data portion files to help store web content. These files have been replaced with global cache files stored under the WWW.CTRL dictionary. Other than insuring that these files are correctly sized, you no longer need to create any special files for storing web content.

The PicLan-IP Web Server can use either standard MV data files or files in a non-MV file system accessed over:

A PicLan DOS Services Gateway
Native Unix file-system files
Native NT file-system files

You can choose to store your entire web content within a single MV file, or you can subdivide the content amongst multiple files and/or network directory specifications. How you manage this depends on your needs and habits.

Web Server Control Files

The PicLan-IP Web Server uses several control files to store pre-computed values for web pages. The item-ids used for these content files consist of the complete URL for the page (less the http://) as in:

207.215.231.99:80/INDEX.HTM

These control files are sub-files under the WWW.CTRL dictionary and have the names:

WWW.CTRL,PGCACHE: This file contains information that tells the Web Server when a page has been changed. For local MV files, this file contains items that are copies of the source HTML or Text content. For network files, this file contains items that contain the time/date stamp for the network directory entry. For binary items, this file is not used.
WWW.CTRL,PGDATA: This file contains web information pre-converted into web format. Binary items are stored as hex strings. Pages that contains active content will have multiple text attributes stored to facilitate efficient merging of web results into page templates.
WWW.CTRL,PGCTRL: This file contains web control information for each web page. This tells the web server whether a subroutine is associated with the page and what type of data and MIME type is involved. HTTP headers are also pre-computed and stored here. You will also see the generated subroutine item-id for pages with active content in this file.
WWW.CTRL,PGBASIC: This file contains generated MV/Basic source code for pages that contain active content. Generated subroutine have item-ids that are addigned sequentially starting with WEB$ as in:
WWW.CTRL,PGBASICXREF: This file has the same item-id format as the WWW.CTRL,PGBASIC file and contains the URL for a subroutine that is generated.
WWW.CTRL,DTA: This file contains run-time parsing information about web directories for each running web process.
WWW.CTRL,LOCAL.PAGES: This file contains local web pages and graphics that are used for default error message pages. You can access web content by specifying a URL that begins with an ampersand '&".
WWW.CTRL,APP.STATES: This file is used to store state information used by the mv/Web environment.
WWW.CTRL,CONN: This file contains information about currently opened TCP/IP connections.
WWW.CTRL,LOCK: This file is empty and is used as a placekeeper for PicLan-IP to set execution READU locks.
WWW.CTRL,PROCESSES: This file is used by PicLan-IP web processes internally.
WWW.CTRL,STATES: This file is used by PicLan-IP web processes to manage connection states.
WWW.CTRL,WORK: This is a temporary work file

Types of Web Files

There are actually five types of PicLan-IP Web Server directory types:

Local files. These are MV data files where the content is actually stored on the MV host. In the web server's configuration file, this is type FILE.
Host files. These are host operating system files stored either locally on the host system or transparently accessible to the host system with a simple path. This is type HOST.
DSG files. These are network data files where the content is accessed via a PicLan DOS Services Gateway. Storing the content in a network file is slower than storing it directly on the MV host, but can make authoring of web pages easier because it eliminates the upload step. When a DSG directory is referenced, the web server saves a copy of the information in the Web Servers cache file and only import the data when the contents change. This is type DSG.
Host-RAW files. There are host data files where the content is not cached in a local file. This directory type is intended for storing large binary items that are infrequently accessed. HOST-RAW directories do not support embedded MV/Basic code. This is type HOST-RAW.
DSG-RAW files. These are network data files where the content is accessed via a PicLan DOS Services Gateway and is not also stored in a local file. This directory type is intended for storing large binary items that are infrequently accessed. DSG-RAW directories do not support embedded MVBasic code. This is type DSG-RAW.

Web Directory Definitions

PicLan-IP Web Server directory definitions define the "rules" that the web server uses in responding to HTTP requests. Each HTTP DIR entry in the web server configuration file defines a TCP address and port to "listen" to for connections, a file structure directory, what type of directory is in use (FILE, HOST, HOST-RAW, DSG, or DSG-RAW), a number of parameters for each type of directory, and possible options. Here is the complete definitions for each of the possible web file types:

MV FILE Definitions

HTTP DIR=addr:port WebDir FILE FName (options) [name]

Host File System HOST Definitions

HTTP DIR=addr:port WebDir HOST HostPath (options) [name]

Host File System HOST-RAW Definitions

HTTP DIR=addr:port WebDir HOST-RAW HostPath (options) [name]

DOS Services Gateway DSG Definitions

HTTP DIR=addr:port WebDir DSG DsgName DsgDir (options) [name]

DOS Services Gateway DSG-RAW Definitions

HTTP DIR=addr:port WebDir DSG-RAW DsgName DsgDir (options) [name]

In each case the following definitions apply:

addr: This is the IP address that the web server will respond to. If a * is specified, the web server will use the first IP address specified in the TCP/IP stack configuration.
port: This is the TCP port number that the web server will respond to. The default TCP HTTP port of 80 should be specified for most applications although other ports number can be used if desired.
WebDir: This is the base directory that this entry will process. The "root" directory is specified as a forward slash /. Virtual sub-directories can be specified here as /dir/. Be sure to both begin and end the directory specification with forward slashes.
FName: This is the base name of a MV data file (created with the four data portions described above) that is used to store or cache web content items. The data file can be stored either in the PICLAN-IP account or elsewhere so long as it can be accessed via a Q-pointer in the PICLAN-IP account.
DsgName: This is the name of a PicLan DOS Services Gateway that will be used to retrieve pages.
HostPath: This is the path used to access a host file system file. In most cases, this path should end with a '/' character.
DsgPath: This is the base drive letter and directory that will pre-pended to the file name when retrieving files through a PicLan DOS Services Gateway. This parameter should always end with a / as in c:/www/.
options: The optional options that are available are:

S - process directory definition with sub-directories. If this option is specified, then a single directory definition will also be used to specify storage for sub-directories. Items in the MV data file will be stored with / characters. DSG references will have directory entries passed through.
B - ignore embedded MV/BASIC code. If this option is specified then any embedded MV/BASIC code will not be processed by the web server but instead displayed "as-is" to the user as a part of the page. This option is primarily used as a demo tool so that users can see the original page contents.
C - do not perform cache checking. This option tells the web server to assume that the cache files are up to date. You should not use this option unless you also run the CACHE-WEB verb after you have made any web content updates.
V - use the system COMPILE verb instead of the system BASIC verb. This allows you to write embedded MV/Basic code in lower case on AP and D³ systems that support this.
R - instrument compiled MV/Basic code in embedded web pages. Instrumenting means that the code has additional source included at every line. By instrumenting the generated code, the PicLan-IP supervisor process can display detailed messages about where a generated subroutine failed making debugging much easier. The down side of instrumenting the code is that the performance and size of the generated subroutine is dramatically effected and thus instrumenting should be reserved for program development only.
D - default page will be called instead of specified page. The page _DEFAULT.HTM will always be called regardless of the URL. This page can then query the variable _FNAME to chain to the desired page. Unless the A option is also used, the default page will only be called for HTML pages.
A - default all. The _DEFAULT.HTM page will always be called regardless of the content type specified in the URL. This option is only effective when used with the D option.
E - error page. This option will cause the page _ERROR.HTM in the directories root to be called to build an HTTP error page. This page can look at the variables _FNAME and _ERROR to create a more customized error message.
X - do not compress HTML. The PicLan-IP web server will remove formatting spaces from HTML pages before transmitting them. This can reduce the size of transmitted web pages by as much as 30% depending on the HTML editor that was used to create the source without effecting the displayed image. If you do not want PicLan-IP to remove formatting spaces from HTML source, include the X option in the directory line.

name: This optional field allows you to create a "name" for a configuration item. This name is used to name items in the WWW.CTRL subfiles. If you do not include a name, the server's IP address will be used as the name. The primary reason for a name field is to allow web sites to be pre-cached.

How Directories are Resolved

If it is possible for several directory definitions to process a single request, then the directory definition that is "longest" will be used. For example, if the configuration file contains:

HTTP DIR=*:80 / FILE WWW.ROOT (S
HTTP DIR=*:80 /IMAGES/ DSG WWW.DSG DSG1 C:/IMAGES/

An HTTP request with the file specification of /images/a3.gif will use line two and reference the file through the DSG where a reference of /text/x1.txt will use line one and reference the file locally.

Case Sensitivity

All PicLan-IP Web file references are converted to "upper case" for storage in local file systems. Host file names on case sensitive hosts (such as Unix) are converted to "lower case" when accessing the local host's file systems. This means:

Store all MV data items with upper-case item-ids.
Store all Unix data files with lower-case paths and file names.

Setting Up Multiple Configurations

Multiple configurations are no longer supported.