Apache Mod_Rexx
Open Source Logo SourceForge.net Logo

Package: Mod_Rexx

Version: 2.1.0

Author:  W. David Ashley
         Linux Software Engineer
         IBM Linux Technology Center
         dashley@us.ibm.com

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

This version of Mod_Rexx works with Apache 2.0 only. 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 and Linux. 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.

There are changes in this release of Mod_Rexx which will require some changes to your Rexx scripts. The builtin function WWWGETARGS has changed and you will need to adjust your scripts accordingly.

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
Jan Engehausen - IBM Object Rexx Team
Rony G. Flatscher
Mark Hessling - Maintainer of Regina Rexx
Heikki Kauppinen - IBM Finland
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
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.


Figure 1

  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. It should be noted that this book applies to Apache 1.x only and contains no information on writing modules for Apache 2.0.






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\Apache Group\Apache2\modules

   rspcomp.rex    ->     x:\Program Files\Apache Group\Apache2\bin

   Apache.cls     ->     x:\Program Files\Apache Group\Apache2
                              or
                         somewhere in the system PATH

   test.rex       ->     For testing purposes place all these files in Apache's
   otest1.rex            document root subdirectory. You can move them later.  
   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
 #
 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/Apache Group/Apache2/bin/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/Apache2/modules
                              or
                         the modules location of your Apache Server

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

   Apache.cls     ->     /usr/bin
                              or
                         somewhere in the system PATH

   test.rex       ->     For testing purposes place all these files in Apache's
   otest1.rex            document root subdirectory. You can move them later.
   fotter.rex
   access.rex            Note that Rexx program files do NOT need to be marked
   rsptest1.rsp          executable in order for Mod_Rexx to execute them. If
   rsptest2.rsp          you do not mark them executable then they cannot be
   rsptest3.rsp          executed outside of the Mod_Rexx environment by
                         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 modules/mod_rexx.so
 AddModule mod_rexx.c

 # The following lines should be added at the end of the http.conf file
 #
 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/Apache2/bin/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.






OS/2 Package Installation

Note: No OS/2 DLL has been supplied in this package. However, you can still compile your own. A makefile.os2 has been supplied. You should also note that OS/2 is not supported in this version of Mod_Rexx for Apache2.

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:\Apache2\modules

   rspcomp.rex    ->     x:\Apache2\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
 #
 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:/Apache2/bin/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 8.0 using the standard GCC compiler installed from Red Hat 8.0. You will need to compile your own module for your version of GCC, Linux/AIX, or Apache.

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

OS/2 is no longer supported by the Mod_Rexx team. All the OS/2 support code is still present within Mod_Rexx but it is not supported. You are on your own.

If you have the resources and are interested in supporting Mod_Rexx on OS/2 please let me know.






Other Platforms

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
 ---------- ----------- -----------------------------------------------------
 2002-11-09 WD Ashley   v2.0.0 Initial release
 2004-08-18 WD Ashley   v2.1.0 Upgrade and fix release





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. Output from the Rexx 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.
  4. You should not attempt to do I/O to stdin, stdout or stderr in Rexx scripts running under Mod_Rexx since they are not attached to traditional file system or console handles.
  5. Using the Rexx SAY statement or calling the LINEOUT function to stdout from a Rexx thread (a method that uses the REPLY statement) will cause the Apache server to ignore the output. This is because Mod_Rexx internally holds the Apache request record pointer in a table who's key is the Rexx program's main thread ID. Since the Rexx program's sub thread is unknown to Mod_Rexx there is no entry in the table for that thread's ID and this will result in the output from the thread to be ignored.
  6. OS/2 is no longer a supported Mod_Rexx environment. An OS/2 makefile has been supplied with this release but it has NOT been tested and it is NOT supported.





Future Enhancements

  1. Add full autoconf support.

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