Rexx Server Pages



Table of Contents

Introduction to Rexx Server Pages
How It Works
Mod_Rexx RSP Directives
RSP Syntax Rules
The RSP Compiler
Examples


Introduction to Rexx Server Pages

Rexx Server Pages (RSPs) are similar to Java Server Pages and PHP pages. RSPs allow the programmer to embed Rexx code into an HTML page. This allows HTML pages to be created dynamically at run time. The following is a small example RSP.

<html>
<body>
<center><h1>RSP Test Page</h1></center>
<p>This is some straight HTML text in the RSP file.
<p>The current date and time is
<?rexx
/* the following is a Rexx statement */
say date() time()
?>
</body>
</html>

RSP-enabled web pages are created just like standard HTML pages using the editor of your choice.

Rexx statements are delimited from HTML lines in an RSP using special tags. There are three available delimiters.

Short Form Delimiter

The easy and shortest form of the Rexx statement delimiters is the <?rexx and ?> form.

Here is an example.

<p>The current date and time is
<?rexx
/* the following is a Rexx statement */
say date() time()
?>

Note that the <?rexx and ?> parts of the tag must each be placed on lines by themselves in the RSP file.

Long Delimiter Form

The long delimiter form uses the standard HTML <script> tag to delimit Rexx statements.

Here is an example.

<p>The current date and time is
<script type="rexx">
/* the following is a Rexx statement */
say date() time()
</script>

Note that the <script> and </script> tags must be placed on lines by themselves in the RSP file.

Depricated Long Delimiter Form

The long delimiter form can also use the depricated form of the HTML <script> tag to delimit Rexx Statements. You should note that this form is depricated in the HTML v4.0 specifications.

Here is an example.

<p>The current date and time is
<script language="rexx">
/* the following is a Rexx statement */
say date() time()
</script>

Note that the <script> and </script> tags must be placed on lines by themselves in the RSP file.




How It Works

When a request is made to Apache and Mod_Rexx for an RSP-enabled file the request is processed in four stages by Mod_Rexx and a Rexx program/script (the RSP compiler).

  1. Mod_Rexx creates a temporary file for the compiled version of the RSP file.
  2. RSPCOMP.REX (the RSP compiler) is called to compile the RSP file into a real Rexx program and place it in the temporary file.
  3. Mod_Rexx calls the newly created Rexx program.
  4. Mod_Rexx removes the temporary file.

The compile process happens very fast and the execution of the Rexx program created by the process is only limited to the actions it invokes. Typically the created program also executes quickly provided it does not access databases or other external environments.

See the section The RSP Compiler for details on how the compiler works and other tasks the compiler can perform for you.




Mod_Rexx RSP Directives

Rexx Server Page support is enabled in Apache using Directives in the httpd.conf file. In addition to the LoadModule statement(s) which load the Mod_Rexx module into Apache at runtime, there are two other required Directives.

AddType application/x-httpd-rexx-rsp .rsp
RexxTempFileNameTemplate "c:\xxx?????.rex"

The following specify all the directives concerning RSP processing.

AddType Directive

The AddType directive adds a new MIME-type to Apache and associates all files that have the specified extension to that type. When a user requests a file from Apache that has that extension it will pass control to Mod_Rexx which will then process the file as an RSP-enabled file.

The AddType directive can have multiple file extensions associated with it so if you do not like using the .rsp extension or you would like additional extensions to be treated as RSP files you can just add them on to the end of the directive. An example might be:

AddType application/x-httpd-rexx-rsp .rsp .rxsp .rxhtml

This directive is required to support RSP execution.

RexxTempFileNameTemplate Directive

The RexxTempFileNameTemplate directive specifies the location and a template for the filename for use when Mod_Rexx creates a temporary file to hold the compiled version of the RSP file. This template must be in a form acceptable to the rexxutil external API SysTempFileName (although the SysTempFileName() external function is not used during the RSP compile process). See your rexxutil library documentation for more information on the SysTempFileName external function argument requirements.

Be sure that Apache has write access to the location you specify in the RexxTempFileNameTemplate directive.

An example for Windows might be:

RexxTempFileNameTemplate "c:\xxx?????.rex"

Or for Unix it might be:

RexxTempFileNameTemplate "/tmp/xxx?????.rex"

This directive is required to support RSP execution.

RexxRspCompiler Directive

The RexxRspCompiler directive specifies the name and location of the Rexx program/script which is responsible for compiling the RSP file into a real Rexx program/script. That script is then executed by Mod_Rexx.

This directive is optional. The default is "rspcomp.rex" and Mod_Rexx expects that file to be in Apache's PATH. However, it is recommended that you place "rspcomp.rex" in a location not in the PATH so that the program is not accessible to anyone but Apache. An example might be:

RexxRspCompiler "c:\rspfiles\rspcomp.rsp"



RSP Syntax Rules

The syntax rules for RSP files are very strict. This is due to the parser (rspcomp.rex) used to scan the RSP file and the syntax restrictions imposed by the Rexx language.

Because Rexx is a line-oriented language (Rexx assumes a semicolon at the end of each line unless the continuation character is present) the compiler scan of the RSP file is performed one line at a time and the tags used for delimiting Rexx statements must appear on lines by themselves. This not only simplifies the scan but it also enforces Rexx syntax rules.

Here are the RSP file syntax rules.

  1. The delimiter tags for Rexx program statements in an RSP file MUST appear on a line by themselves. The following are valid lines in an RSP file.

    Example 1 
    <?rexx
say date() time()
?>
    Example 2 
    <script type="rexx">
say date() time()
</script>
    Example 3 
    <script language="rexx">
say date() time()
</script>

    The following examples are all invalid and will cause incorrect parsing of the RSP file.

    Example 1 (Incorrect Syntax) 
    <p>The current date is <?rexx say date() ?>
    Example 2 (Incorrect Syntax) 
    <p>The current date is <?rexx say date()
?>
    Example 3 (Incorrect Syntax) 
    <p>The current date is 
<?rexx say date() ?>
    Example 4 (Incorrect Syntax) 
    <p>The current date is <script type="rexx"> say date() </script>
    Example 5 (Incorrect Syntax) 
    <p>The current date is <script type="rexx"> say date() 
</script>
    Example 6 (Incorrect Syntax) 
    <p>The current date is 
<script type="rexx"> say date() </script>
  2. Short forms of the <?rexx tag such as <? are not allowed.
  3. The attributes charset, defer and src can be specified on the <script> tag but they will be ignored.
  4. The value assigned to the type or language attributes of the <script> tag is considered to be case insensitive. The following are all valid: 
    type="REXX"
type="rexx"
type="Rexx"
  5. Rexx statements must conform to the normal Rexx syntax rules.
  6. Standard HTML lines may be formated in any form subject to the previous rules concerning RSP delimiter tags.



The RSP Compiler

The RSP Compiler (rspcomp.rex) is used by Mod_Rexx to parse an RSP file and turn it into a standard Rexx program which can be executed under the Mod_Rexx environment.

RSP File Parsing

The RSP Compiler is a one-pass parser. It parses the RSP file from top to bottom processing HTML, RSP tags, and Rexx statements in the order they are found. The output file is a real Rexx program/script which is really only executable under Mod_Rexx. The following are the parsing rules:

  1. Before processing the input RSP file the RSP Compiler places some header Rexx comments and statements into the output file which support the Mod_Rexx environment.
  2. HTML lines are turned into Rexx Say statements and appended to the output file in the order they are found.
  3. Rexx statements contained within RSP delimiter tags are appended unchanged to the output file in the order they were found.
  4. When the HTML tag </html> is found a Rexx "return 0" statement is appended to the output file after the HTML line. This is done so that when Rexx executes the script execution does not attempt to fall into Rexx procedures which may appear at the end of the RSP file.

If the parsing was successful the output Rexx program should be executable in the Mod_Rexx environment.

Using the RSP Compiler from the Command Line

The RSP Compiler is designed to be called either from Mod_Rexx or from the command Line. The command line version can be used to turn your RSP files into Rexx programs executable by Mod_Rexx. By using the compiled version you can improve the performance of Mod_Rexx.

The command line syntax is

rexx rspcomp.rex rspfilename rexfilename [errmsg]

where

rspfilename
The name of the RSP input file.
rexfilename
The name of the output Rexx file.
errmsg
This argument is optional and if supplied should be the literal string "errmsg". If supplied the RSP Compiler will send output error and informational messages to the console. If the argument is not supplied the RSP Compiler operates in silent mode.

By using the compiled version of your RSP file you can save the extra step of compiling your RSP file each time it is requested from Apache by a user.

Examples

The following will compile the RSP file into a Rexx program.

rexx rspcomp.rex rsptest1.rsp rextest1.rex

Valid XHTML 1.0! Copyright (C) W. David Ashley 2004. All Rights Reserved.