# 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

- IBM Internet Connection Server
- Lotus Domino Server
- Apache Server

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:

- An audio player capable to play WAV files,
- A video player capable to play AVI files.

### Package contents

This package contains:

- a generic Html framework for generating html output,
- a tailored myHtml class that may be used for generating personalized html output,
- a main html file defining the main page,
- a number of sample scripts being referenced by the main page.

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:

- Object REXX for Windows95 and WindowsNT:
  - Interpreter Edition V1.0.3.0
  - Development Edition V1.0.3.0
- Object REXX for OS/2 Warp 3 and Warp 4

- make sure you have the latest upgrades available from URL http://www.software.ibm.com/ad/obj-rexx

- Object REXX for Linux V1.2
- Object REXX for AIX V1.1.0

### 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:

- Information about Object REXX (file www1.cmd)
- A simple Form with input (file form1.cmd)
- A simple Form with input type Select (file form2.cmd)
- Another Form with more input (file form3.cmd)
- A simple Form with various inputs (file form4.cmd)
- Amortization sample (file www2.cmd)
- List addresses out of a file (file www3.cmd)
- Sample using mouse-over events (file orxhome.cmd)
- How about some other media (file www0.cmd)
- See an automatically generated error report (file www4.cmd)

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:

- the Object REXX logo on the left upon mouse-click gets you back to the main page,
- the "Download CGI Program" field on the right upon mouse-click downloads the cgi-script source to the browser where it can be stored or viewed as appropriate.

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!