WebRexx
 

HTTP: Rexx Language

Newsgroups: comp.lang.rexx

Table of Contents

Introduction
InSide HTML: Embedding Rexx
Structure of a Rexx Script
Managing Your Rexx Modules
Examples
Function Definitions
Introduction
 WebRexx makes it easy to develop rapid prototypes of systems. In most cases the prototype will be fast enough for actual deployment, especially as WebRexx is substantially faster than CGI because of its much lower overhead.

WebRexx is fully integrated into PowerWeb, allowing Rexx code to be embedded within your HTML and executed before the document is sent to the client's browser.

You can also write independent Rexx modules as ".CMD" files and have them called by way of a URL or from within HTML by means of the #exec WebMacro.

PowerWeb also allows you to extend its internal engine by defining API Hooks which selectively override aspects of its behaviour, such as user authentication and access control. You can write these hooks in Rexx and take advantage of PowerWeb's caching of the tokenised Rexx module for speed.

Windows NT Users:

You should obtain and install the Object Rexx for Windows NT available from IBM's Rexx site before attempting to use WebRexx.

You MUST set your system PATH (not just your local user PATH) to include the ObjRexx directory if you are running PowerWeb as an NT Service. You do this through the Windows Control Panel, System settings.

You must also obtain the 30 December 1996 or later release of Object Rexx, otherwise you will not be able to run WebRexx when PowerWeb is installed as an NT service. In addition, you must leave the "Interact with Desktop" setting enabled in the PowerWeb Service startup settings (this is enabled by default upon installation).

InSide HTML: Embedding Rexx
 The easiest way to create your own Rexx programs is to embed them within HTML. This is demonstrated by the "\powerweb\system\tour\rexxtime.htm" HTML document which shows how you can store Rexx code within an HTML document and have it executed by the server before the page is delivered to the client's browser.

The process to follow is:

  1. Place your Rexx code within a #Script WebMacro.
  2. Write the HTML portions of your document.
  3. Call the Rexx code by using a #Call WebMacro.
The skeleton structure for your document is therefore:
<!--#script ScriptName -->
/* Your Rexx Code */
<!--#endscript -->
<html>
Your HTML text.
<!--#call rexx=ScriptName -->
Your further HTML text.
</html>
Structure of a Rexx Script
 Remember that all Rexx programs must start with a comment, such as:
/* My Rexx Script */
PowerWeb calls WebRexx with a "parcel" that is a magic cookie for further communication between PowerWeb and Rexx.

You access this "parcel" within Rexx by using the following code at the top of your script:

parse arg parcel
By using this "parcel", you can gain access to any PowerWeb variable through the PowerWeb API functions, which are documented in the PowerWeb API Function Reference Manual.

Your Rexx script is expected to return a result indicating the success or failure of your script, according to the following table: For example, you would use this Rexx code to indicate success:

return "0"
Managing Your Rexx Modules
 Each Rexx Script that is not embedded within HTML should be stored in a file with a ".CMD" file extension.

PowerWeb Rexx Scripts can be stored in any directory, but the guidelines below will help you manage all your modules. The PowerWeb Server++ is initially configured during installation to support extensions in the following suggested directory.

Suggested Location for Rexx Modules:
Assuming your server root is "\powerweb", put your module in the directory "\powerweb\rexx-bin", so that you can load it with the URL "/rexx-bin/module.cmd" where "module.cmd" is the name of your Rexx module.

Example URL: "/rexx-bin/svrpush.cmd"

PowerWeb automatically associates files within the rexx-bin directory as Rexx scripts. This is set up through the URL Alias Editor. If you create sub-directories under this directory, they will also be recognised as Rexx script directories.

You can create further directories in other locations by simply defining an alias to that directory and giving it an object type of "Rexx Script".

Examples
TimeZone Display Example:
Under "\powerweb\system\tour", there is a document "rexxtime.htm" which demonstrates how Rexx can be embedded within HTML to display tables with dynamic content. Try it!

Guided Tour Sample Code:
The Guided Tour has a complete Rexx example of an API hook for dynamic translation of a database into an HTML document. It has equivalent functionality to the C example code, so you can compare the two language implementations.

Server Push Sample:
Under "\powerweb\system\rexx-bin", there is a file "svrpush.cmd" which demonstrates server-push for those browsers capable of handling this feature which allows for periodic updating of the client's page or image.

Semaphore Example:
Under "\powerweb\system\rexx-bin", there is a file "semaphor.cmd" which shows how to use semaphores to achieve safe multi-tasking even when the external library you are using is single-threaded (such as the IBM Rexx to DB/2 interface).

Directory Listing Example:
Under "\powerweb\system\rexx-bin", there is a file "dirlist.cmd" which demonstrates how Rexx can be used to process HTML forms and dynamically generate Web Macro code.

Tree Display Example:
Under "\powerweb\system\rexx-bin", there is a file "tree.cmd" which is equivalent to the C-code Guided Tour example which displays your server configuration settings in a tree format.

Function Definitions
 The Rexx Library is equivalent in functionality to the C-compatible API library. The function names have been kept consistent for ease of working in both environments. It is a straightforward procedure to port a Rexx implementation to C for speed because of this consistency.

You will need to read the API Function Reference, before writing code which calls these functions.

The PowerWeb Server++ Rexx Interface Function Definitions Are:

Return
Value		Function
Name		Input
Parameters
handle ServerGetConfig parcel
handle ServerGetServer parcel
handle ServerGetConnect parcel
handle ServerGetRequest parcel
handle ServerGetParameters parcel
handle ServerGetArguments parcel
handle ServerFind parent, name
type ServerKind handle
size ServerSize handle
name ServerName handle
- ServerFlush handle
value ServerReadText parent, name
value ServerReadBinary parent, name
- ServerWriteText parent, name, value
- ServerWriteBinary parent, name, value
- ServerAppendText parent, name, value
- ServerAppendBinary parent, name, value
- ServerNewInteger parent, name, value
- ServerNewFloat parent, name, value
- ServerNewText parent, name, value
- ServerNewBinary parent, name, value
- ServerNewList parent, name
- ServerNewSemaphore parent, name
- ServerDelete handle
handle ServerParent handle
handle ServerChild handle
handle ServerSibling handle
- ServerInterpret parcel, code