Apache Mod_Rexx Interface Package

Package: Mod_Rexx

Version: 1.1.1

Author:  W. David Ashley
         IT Architect
         IBM Global Services
         dashley@us.ibm.com

Warning! Warning! Warning! Warning! Warning! Warning! Warning! Warning! Warning! Warning! Warning! Warning!

This version of Mod_Rexx contains significant changes from all previous versions and new additional features. You should carefully read this documentation before installing or using this version of Mod_Rexx.

This software is subject to the terms of the Common Public License. You must accept the terms of this license to use this software. Refer to CPLv1.0.htm for more information.

This package provides an interface from Apache to IBM Object REXX and Regina REXX under Windows, AIX, Linux and OS/2. To use the package you do not need to know how to write Apache modules, but you do need a general understanding of how Apache processes requests.

This package is not an Apache module tutorial/reference.

This release is a major update of the previous versions of Mod_Rexx. There is brand new functionality and some changes to the methodology used to execute REXX scripts in this release. It is suggested that you read the documentation carefully before attempting to install or use this version of Mod_Rexx. I think you will like what you find.

Many people have contributed to this effort and I want to thank some of them here.

Richard Brandle - IBM Demo Package Delivery and Service
Sam Detweiler - IBM Research
Rony G. Flatscher
Mark Hessling
Patrick McPhee - Thanks for the Powered by REXX images
Reiner Micke - IBM Object REXX Team
Bill Stoddard - IBM Apache Team
Steve Swift - IBM ITS Technical Support
Gunter Thum - IBM Object REXX Team




Table of Contents

What is Mod_Rexx
Windows Package Installation
Unix Package Installation
OS/2 Package Installation
Windows Information
Unix Information
OS/2 Information
Other Platforms
Version History
Known Problems
Mod_Rexx Apache Configuration Directives
Apache Object REXX Class Documentation
REXX Apache External Functions
Available REXX Variables
Mod_Rexx HowTo
REXX Server Pages  <---!!!NEW!!!
Future Enhancements



What is Mod_Rexx

Mod_Rexx is NOT a CGI environment for REXX. Your REXX CGI programs will not run under Mod_Rexx without significant modifications. The Mod_Rexx execution environment is CGI-like, but even that is not a proper definition of the environment.

Mod_Rexx is a very powerful package that can bring full control of the Apache request process to the REXX programmer. When Apache receives a request it divides the processing of that request into phases. Each of these phases is responsible for a small part of the request.

                                 +-------------------+
                                 | REQUEST           |
                                 +-------------------+
                                          |
                                          V
        +-------------------+    +-------------------+
        | (wait)            | -> | post-read-request |
        +-------------------+    +-------------------+
                 ^                        |
                 |                        V
        +-------------------+    +-------------------+
        | cleanup           |    | URI translation   |
        +-------------------+    +-------------------+
                 ^                        |
                 |                        V
        +-------------------+    +-------------------+
        | logging           |    | header parser     |
        +-------------------+    +-------------------+
                 ^                        |
                 |                        V
        +-------------------+    +-------------------+
        | response          |    | access control    |
        +-------------------+    +-------------------+
                 ^                        |
                 |                        V
        +-------------------+    +-------------------+
        | fixup             |    | authentication    |
        +-------------------+    +-------------------+
                 ^                        |
                 |                        V
        +-------------------+    +-------------------+
        | MIME type check   | <- | authorization     |
        +-------------------+    +-------------------+

  1. Post Read Request Phase - This phase can modify the request itself after the request has been read.
  2. URI Translation Phase - This phase maps the URI request to a physical file, virtual document produced by an external script, or a document generated by an internal module.
  3. Header Parser Phase - Another chance to examine the request headers.
  4. Access Control Phase - This is the first of three phases that handle authentication and authorization. This phase should perform simple access control based on the browser's IP address, hostname, or some other simple attribute of the programmer's choice.
  5. Authentication Phase - This phase is called whenever the requested file is password-protected. Usually this phase checks the userid and password. This is the second phase involved in authentication and authorization.
  6. Authorization Phase - Actually determines if the user is actually authorized to access the requested URI. This is the third (and last) phase involved in authentication and authorization.
  7. MIME Type Check Phase - This phase assignes a provisional MIME type to the request.
  8. Fixup Phase - This is the last chance to modify the request before the response handler phase is called.
  9. Response Handler Phase - This is also known as the content handler phase. This phase is responsible for actually returning the requested information to the browser either dynamically or statically, by returning a file. This handler acts somewhat like a CGI program but the runtime environment for this phase is very different from the traditional CGI environment.
  10. Log Phase - This phase is responsible for logging the request.

Each of these phases can have a REXX script assigned to it. In most cases you will probably only assign a script to the Response Phase, but it is possible for a REXX script to fully process any phase. Mod_Rexx defines directives which are placed into the Apache configuration file which then define how a REXX script is assigned to a particular request phase.

For more information about how the Apache request phases work I highly recommend the book Writing Apache Modules with Perl and C by Lincoln Stein & Doug MacEachern published by O'Reilly and Asscoiates, Inc. ISBN: 1-56592-567-X.






Windows Package Installation

To install the package on Windows, unzip the contents to a temporary subdirectory. Move the following files to these locations (where x: is the Apache server install drive):


   mod_rexx.dll   ->     x:\Program Files\IBM HTTP Server\modules
                              or
                         x:\Program Files\Apache\modules

   rspcomp.rex    ->     x:\Program Files\IBM HTTP Server\bin
                              or
                         x:\Program Files\Apache\bin

   test.rex       ->     For testing purposes place all these files in Apache's
   otest1.rex            document root subdirectory. You can move them later.  
   Apache.cls                                                                 
   footer.rex
   access.rex
   rsptest1.rsp
   rsptest2.rsp
   rsptest3.rsp

In the httpd.conf file (located in Apache conf directory) insert the following lines:


 # The following line needs to be added to the end of the appropriate 
 # httpd.conf LoadModule list
 LoadModule rexx_module modules/mod_rexx.dll

 # The following lines should be added at the end of the http.conf file
 #
 # Note: These lines form a new methodology for execution of Mod_Rexx scripts.
 #       With these lines, REXX programs can now be placed anywhere in Apache's
 #       document tree. The scripts only need to have one of the file extensions
 #       specified on the AddType application/x-httpd-rexx-script statement.
 AddType application/x-httpd-rexx-script .rex .rexx
 AddType application/x-httpd-rexx-rsp .rsp
 
 #Add these for REXX Server Page support
 RexxTempFileNameTemplate "c:/temp/execrsp????.rex"
 RexxRspCompiler "c:/Program Files/IBM HTTP Server/rspcomp.rex"

You may need to modify the lines above if your Apache server modules subdirectory is not located in the specified place.

Now restart the Apache server.

To test that the package is working start your browser and enter the following URL (where your.domain.com is the name of your server):


http://your.domain.com/test.rex

This should execute the REXX program test.rex and a sample HTML page should be displayed.

To build your own Apache REXX programs just code your program and place it anywhere in Apache's document tree. Your REXX programs should have a file extension which matches one of the extensions listed in the

 AddType application/x-httpd-rexx-script .rex .rexx

line of the Apache configuration file. When a browser request for a document arrives at the Apache server it checks the file extension of the document with its list of handlers and then passes that document to the appropriate handler. In this case, if the file extension matches, then the document will be passed to Mod_Rexx and executed as a REXX program.






Unix Package Installation

To install the package on Unix, unzip the contents to a temporary subdirectory. Move the following files to these locations:


   mod_rexx.so    ->     /opt/IBMHTTPServer/libexec
                              or
                         the libexec location of your Apache Server

   rspcomp.rex    ->     /opt/IBMHTTPServer/bin
                              or
                         the bin location of your Apache Server

   test.rex       ->     For testing purposes place all these files in Apache's
   otest1.rex            document root subdirectory. You can move them later.
   Apache.cls
   footer.rex            Note that REXX program files do NOT need to be marked
   access.rex            executable in order for Mod_Rexx to execute them. If
   rsptest1.rsp          you do not mark them executable then they cannot be
   rsptest2.rsp          executed outside of the Mod_Rexx environment by
   rsptest3.rsp          accident or maliciously through the standard Apache
                         CGI interface.

Be sure the mod_rexx.so file is marked executable.

In the httpd.conf file (located in Apache conf directory) insert the following lines:


 # The following 2 lines need to be added to the ends of the appropriate 
 # httpd.conf LoadModule and AddModule lists
 LoadModule rexx_module libexec/mod_rexx.so
 AddModule mod_rexx.c

 # The following lines should be added at the end of the http.conf file
 #
 # Note: These lines form a new methodology for execution of Mod_Rexx scripts.
 #       With these lines, REXX programs can now be placed anywhere in Apache's
 #       document tree. The scripts only need to have one of the file extensions
 #       specified on the AddType application/x-httpd-rexx-script statement.
 AddType application/x-httpd-rexx-script .rex .rexx
 AddType application/x-httpd-rexx-rsp .rsp
 
 #Add these for REXX Server Page support
 RexxTempFileNameTemplate "/tmp/execrsp????.rex"
 RexxRspCompiler "/opt/IBMHTTPServer/bin/rspcomp.rex"

You may need to modify the lines above if your Apache server libexec subdirectory is not located in the specified place.

Now restart the Apache server.

To test that the package is working start your browser and enter the following URL (where your.domain.com is the name of your server):


http://your.domain.com/test.rex

This should execute the REXX program test.rex and a sample HTML page should be displayed.

To build your own Apache REXX programs just code your program and place it anywhere in Apache's document tree. Your REXX programs should have a file extension which matches one of the extensions listed in the

 AddType application/x-httpd-rexx-script .rex .rexx

line of the Apache configuration file. When a browser request for a document arrives at the Apache server it checks the file extension of the document with its list of handlers and then passes that document to the appropriate handler. In this case, if the file extension matches, then the document will be passed to Mod_Rexx and executed as a REXX program.






OS/2 Package Installation

To install the package on OS/2, unzip the contents to a temporary subdirectory. Move the following files to these locations (where x: is the Apache server install drive):


   mod_rexx.dll   ->     x:\Apache\libexec

   rspcomp.rex    ->     x:\Apache
                              or
                         the bin location of your Apache Server

   test.rex       ->     For testing purposes place all these files in Apache's
   otest1.rex            document root subdirectory. You can move them later.
   Apache.cls
   footer.rex
   access.rex
   rsptest1.rsp
   rsptest2.rsp
   rsptest3.rsp

In the httpd.conf file (located in Apache conf directory) insert the following lines:


 # The following line needs to be added to the end of the appropriate 
 # httpd.conf LoadModule list
 LoadModule rexx_module libexec/mod_rexx.dll

 # The following lines should be added at the end of the http.conf file
 #
 # Note: These lines form a new methodology for execution of Mod_Rexx scripts.
 #       With these lines, REXX programs can now be placed anywhere in Apache's
 #       document tree. The scripts only need to have one of the file extensions
 #       specified on the AddType application/x-httpd-rexx-script statement.
 AddType application/x-httpd-rexx-script .rex .rexx
 AddType application/x-httpd-rexx-rsp .rsp
 
 #Add these for REXX Server Page support
 RexxTempFileNameTemplate "c:/temp/execrsp????.rex"
 RexxRspCompiler "c:/Apache/rspcomp.rex"

You may need to modify the lines above if your Apache server modules subdirectory is not located in the specified place.

Now restart the Apache server.

To test that the package is working start your browser and enter the following URL (where your.domain.com is the name of your server):


http://your.domain.com/test.rex

This should execute the REXX program test.rex and a sample HTML page should be displayed.

To build your own Apache REXX programs just code your program and place it anywhere in Apache's document tree. Your REXX programs should have a file extension which matches one of the extensions listed in the

 AddType application/x-httpd-rexx-script .rex .rexx

line of the Apache configuration file. When a browser request for a document arrives at the Apache server it checks the file extension of the document with its list of handlers and then passes that document to the appropriate handler. In this case, if the file extension matches, then the document will be passed to Mod_Rexx and executed as a REXX program.






Windows Information

The package was compiled under Microsoft Visual C++ version 6.0 with Visual Studio Service Pack 3 installed.

The package was tested using

All the source files, except makefile.nt and the REXX sample scripts, are in Unix format (lines are delimited only by a line feed).






Unix Information

For Linux, the package was compiled under Red Hat Linux 7.2 using the standard GCC compiler installed from Red Hat 7.2 (NOT GCC version 3.0).

The package was tested using

For AIX, the package was compiled under AIX 5.1 with ML 1 installed using the IBM VisualAge C++ Professional compiler.

The package was tested using

All the source files, except the REXX sample scripts, are in Unix format (lines are delimited only by a line feed).






OS/2 Information

The package was compiled under EMX C++ version 0.9d with the OS/2 Developer's Toolkit installed.

The package was tested using

All the source files, except makefile.os2 and the REXX sample scripts, are in Unix format (lines are delimited only by a line feed).






Other Platforms

Mod_Rexx has also been compiled and tested on Linux for 390. It has not been tested on any other platform other than the ones listed above.

If you undertake to compile and test Mod_Rexx on any platform other than Linux, AIX, OS/2 or Windows I would appreciate hearing from you. I would also appreciate a copy of the makefile used to compile the source for the platform you used so it can be included in subsequent releases of Mod_Rexx.






Version History

 Date       Author      Description
 ---------- ----------- -----------------------------------------------------
 2001-10-11 WD Ashley   v1.0.1 Initial Public Release
 2001-10-29 WD Ashley   v1.0.2 Support for OS/2, Regina REXX and other fixes
 2002-01-14 WD Ashley   v1.0.3 Support for AIX and a major bug fix for
                               Apache request record pointers
 2002-06-03 WD Ashley   v1.1.0 Major Upgrade                          
                               Reorganized the source code
                               Documented the request, server, and connx record
                                Rexx external functions used by the Apache class
                               Added REXX Server Page (RSP) functionality
 2002-06-30 WD Ashley   v1.1.1 License change only, no code changes  





Known Problems

  1. The binary files supplied with this release do not work with versions of Object REXX or Regina REXX which do not match the version used during compilation and linking. You may need to upgrade your version of REXX or recompile Mod_Rexx with your version of REXX before you get a working mod_rexx binary.
  2. During Apache subrequest processing none of the REXX handlers will be invoked. They will always DECLINE the request. This is to prevent an infinite recursion problem with non-response/content handlers.
  3. The REXX TRACE instruction should not be used in your REXX scripts. Output from the TRACE instruction will be sent to the Apache error log. Input to the TRACE instruction will not be allowed. This limitation has been imposed due to a problem with REXX sending error information to the client browser as an unknown MIME-type when a REXX program/script crashes.





Future Enhancements

  1. A future version will include autoconf support but at this point it is a low priority as there are problems with autoconf when both Object REXX and Regina REXX are installed on the target build system.

Valid XHTML 1.0!