README

Web Server Html Package "orxwww"

Prerequisites

To run this package Object REXX is required to be installed on your system running an http-server. The http-server can be any server supporting the http protocol, such as The proper installation of the http-server has to be performed according to the installation and configuration instructions of the respective software provider.

As a generic client, any modern browser available can be used. Using one of the later versions of the Netscape Navigator is recommended but not required. Nevertheless, for the demonstration of web-pages with multimedia components the following plugins are required:

Package contents

This package contains: This package is portable without change to all system environments where Object REXX is available (see note at the end of this Readme). At this time these are:

Package Installation

Download the package file orxwww.zip and unpack it in a directory of your choice. The zip-file unpacks into a directory orxwww. Now move the file orxwww.zip into directory orxwww.
Then add the following two lines at the top of the mapping rules portion of the http-demon configuration file httpd.cnf or httpd.conf in the Unix environments, respectively.

  Exec    /cgi-bin/orxwww/*  d:\www\orxwww\cgi-rexx.cmd 
  Pass    /orxwww/*   d:\www\orxwww\*
with d:\www being the directory where the orxwww package was installed, for example in the OS/2 or Windows environment. For the Unix environments the mappings have to be specified correspondingly.

In shell environments not recognizing REXX command files automatically, the cgi-rexx.cmd file cannot be invoked directly since the REXX environment is not established yet. This can be achieved by invoking the simple shell script cgi.cmd that invokes rexx.exe taking cgi-rexx.cmd as parameter (see file cgi.cmd). In this case, the Exec statement in the http-server configuration file has to look instead as follows:

  Exec    /cgi-bin/orxwww/*  d:\www\orxwww\cgi.cmd 

Before you start the http-server make sure that Object REXX is available to the process the server is running in. Check the respective specification of the path.
Now restart your http-server. As the http-server becomes ready you can try the following URL with your favorite browser:

http://hostname/orxwww/main.htm

with hostname being the fully qualified name of your host system. This brings up the home page containing a menu of items each of which is associated with a sample cgi-program contained in directory orxwww being basically a rexx command file. These are:

These sample cgi-programs may be explored by clicking on a desired list item.

The Cgi-REXX Processor

The cgi-REXX Processor is a REXX program (file cgi-rexx.cmd) which is invoked by the http-server whenever a REXX script prefixed by /cgi-bin/orxwww/ is recognized in the URL as specified in the Exec statement of the http-server configuration mentioned earlier.

The http-server passes information on the IP-address of the requesting host, the name of the cgi-script to be executed, and the parameter string to be passed to the cgi-script by means of environment variables to the cgi-REXX processor, which in turn invokes the respective cgi-script.
The cgi-script returns an Html-object being an instance of the myHtml class. This is resolved by the cgi-REXX processor by passing its information as an html-document line by line to the http-server (via standard output) which in turn returns it to the requester's address. There it is rendered by the browser so becoming visible to the user now.

In case the cgi-script causes the Object REXX interpreter to raise an exception, the cgi-REXX processor generates an Html-document describing the cause of the problem.

Note: The cgi-REXX processor contains a shell script prefix '#!/usr/local/orexx/bin/rexx' being used in the Linux system environment. If you are executing on an AIX system platform this shell script prefix has to be changed to '#!/usr/lpp/orexx/bin/rexx'.
Make sure that the cgi-rexx processor (file cgi-rexx.cmd) is executable when being invoked directly.
The shell script prefix is simply ignored when executing on Windows system platforms provided you have Object REXX for Windows V1.0.3.0 installed. If you are running an older version you simply need to remove the first line of the script.
On OS/2 Warp3 and Warp4, the shell script prefix has to be removed since the command interpreter requires a conventional comment starting in column 1 of the first line to invoke the REXX interpreter.

Inspecting the Sample Web-Pages

Each sample cgi-script invoked from the main page menu creates a Web-page that has a standard footing with two active areas: In addition, the browser allows you to view the Html-source of the document currently being displayed. With these facilities, the rendered web-page, its associated Html-source, as well as the cgi-script generating the Html-source can be inspected to learn about the respective features available with the personalized and basic Html classes provided in this sample programming package.

Have fun with dynamic Html-programming using Object REXX on the Internet!