10 Nov 2002

           SREhttp/2 and the use of CGI-BIN scripts written in PERL.

By default, SREhttp/2 assumes that a CGI-BIN script is a binary executable,
or is a "script" written in REXX.  However, to take advantage of the
wide-world of PERL scripts, SREhttp/2 can invoke non-REXX interpreters when 
running a CGI-BIN script.

Let's consider some examples:
  * If the request string is:  CGI-BIN/TEST-CGI?arg1
    then SREhttp/2 will CALL the TEST-CGI program, which should either
    be a REXX program, or a binary executable (a .EXE file).
 
 * If the request string is: CGI-BIN/TEXTCLOCK.PL
    the SREhttp/2 will invoke the PERL processor, and use it
    to execute TXTCLOCK.PL.

So all you need to do is make sure your PERL scripts have a .PL extension.

... oh, you also need to install an OS/2 version of PERL on your
computer.

We've had success with the PERL implementations available on hobbes.
The following outlines what you need to install PERL on your computer.

1) Obtain the PERL interpreter. You can get it at hobbes, look
   for (ver 5.02b). As of this date, you can try:
      http://hobbes.nmsu.edu/pub/os2/dev/perl/perl502b.zip
   or (ver 5.6, newer but larger)
      http://hobbes.nmsu.edu/pub/os2/dev/perl/perl-5.6.1.zip   
   or (ver 5.7.2, a "stable" build of a development version)
      http://hobbes.nmsu.edu/pub/os2/dev/perl/perl-5.7.2.zip   


2) You'll also need a copy of the EMX "runtime environment". You can
   get it at hobbes -- you can try:
       http://hobbes.nmsu.edu/pub/os2/dev/emx/v0.9d/emxrt.zip

  If you use 5.7.2, you'll also need
      http://www.axess.com/users/sobotka/warpzilla/binaries/gcc2952m.zip 
  which you should UNZIP to your LIBPATH (i.e.; to x:\OS2\DLL).

Notes:
   *  If you can't find the EMX, PERL, or GCC2592 files on hobbes, you can try
      http://www.srehttp.org/pubfiles/
 
   *  There is a "WPI" distribution of EMX that we have not tried. It's
      supposed to automate installation. You can find it at:
         http://hobbes.nmsu.edu/pub/os2/dev/emx/v0.9d/emx-0-9-d.wpi
      and
         http://hobbes.nmsu.edu/pub/os2/dev/emx/v0.9d/emx-0-9-d1.wpi

3) Upon obtaining these two packages, you need to install them.
   The following worked for us, using PERL 5.02b. For PERL 5.6 and 5.7.2, 
   you should check the instructions.  Of course, it's always advisable to
   to look at the documentation that comes with both packages.

     a)  Assuming you got ver 0.9d of EMX, copy the .ZIP file to the root 
         of your boot drive (say, C:\)
     b)  Unzip this file -- make sure you use an UNZIP that will automatically
         create sub directories.
          An EMX directory (with several subdirectories and about 50 files) 
          will be created. There should be nothing copied to the root 
          directory.
     c)  Modify the following in  CONFIG.SYS:
             i)  Add C:\EMX\DLL to your LIBPATH= line.
             ii) Add C:\EMX\BIN to your PATH= line.
         (of course, the c:\emx should be changed to reflect where
         you installed EMX).

     EMX should now be installed. To test it, at an OS/2 command prompt type:
        x:>EMXREV
     you should get a report that looks like:
        EMX : revision = 61
        EMXIO : revision = 60
        EMXLIBC : revision = 63
        EMXLIBCM : revision = 64
        EMXLIBCS : revision = 64
        EMXWRAP : revision = 60


     d)  Create a PERL directory somewhere.

           The PERL authors HIGHLY recommend using an HPFS drive;
           since most PERL scripts are long-named. If you installed 
           SRE2003 on a FAT drive, and you have an HPFS drive elsewhere
           on your system, you can move your CGI-BIN directory to the
           HPFS drive.  If you do this, you'll have to change the value
           of the CGIBIN_DIR parameter (in SREH2INI.RXX).

     e) This step is applicable to PERL 5.02b. 
         Let's assume you create D:\PERL directory.

       e1)  Copy PERL502B.ZIP to this directory, and UNZIP it.

       e2)  Copy PERL5.EXE and PERLGLOB.EXE to a directory in the
            OS/2 PATH (i.e.; C:\OS2\APPS).  

       e3)  Copy PERL5.DLL to a directory in the OS/2 LIBPATH
            (i.e.; C:\OS2\DLL).

           Note: both .EXE files and the .DLL file should be in D:\PERL.
               You can leave them there after copying them (to
               the OS/2 PATH and LIBPATH).
  
       e4)  Add the following to config.sys: 
              SET PERL5LIB=D:\PERL\LIB
           (of course, D:\PERL should be changed to reflect where
            you've installed PERL).

           The authors also suggest adding: 
              SET PERL5LOAD=10 
           (to leave the interpreter in memory, thereby reducing load time)


      f) This step is applicable to PERL 5.7.2
  
        f1)  Copy perl-5_7_2.zip to this directory, and UNZIP it.
             Let's assume that you unzipped to PERL-5_7_2 to D:\PROGS.
             If you use some other directory, change the examples below.
        
        f2) Make the following changes to your CONFIG.SYS. 
            i) add the following to the end of your LIBPATH line:
                  d:\progs\perl\lib
            ii) add the following to the end of your your PATH line
                  d:\progs\perl\bin\5.7.2
            iii) add the following to the end of your your BOOKSHELF line
                  d:\perl57\perl\book
             iv) add the following lines
                   SET PERLLIB_PREFIX=o:/Perl/lib;d:\Progs\perl\lib
                   SET PERL_BADFREE=0
                   SET PERL_BADLANG=0
                   SET PERL_SH_DIR=d:\perl57\Perl\bin\5.7.2

                Note: the o:/Perl/lib in the PERLLIB_PREFIX line is never
                      changed. That is, if you unzipped PERL to F:\STUFF,
                      then use:
                          SET PERLLIB_PREFIX=o:/Perl/lib;F:\STUFF\perl\lib

         f3) Copy SH.EXE from D:\progs\perl\bin to d:\progs\perl\bin\5.7.2.
        
4)  You'll have to reboot for these changes to take effect.
    If you are using 5.7.2, you should run the TESTPERL.CMD program (from
    an OS/2 prompt); it's in d:\progs\perl\bin

5) Check SREH2INI.RXX (in your SREHTTP2 directory), and 
   make sure that:
        interpret_types=' PL=PERL5 '   (if you are using 5.02b)
   or
        interpret_types=' PL=PERL -T '   (if you are using 5.7.2)

   The latter is the default value.

   If you want to use extensions other then .PL for your perl scripts,
   you'll need to modify interpret_types. For example, to use the PL5
   extension also, set:
        interpret_types=' PL=PERL5 , PL57=PERL -T '
 
That should do it.  You'll probably want a few scripts to try out --
a good source is Matt's Script archive, located at:
  http://worldwidemart.com/scripts 
or, the more modern equivalents at
  http://nms-cgi.sourceforge.net/


As a convenience, a very simple "time" script (TXTCLOCK.PL) is
included with SREhttp/2. To check that it works, hit your server with:
   /cgi-bin/txtclock.pl
Or, create a "server side include aware" web page (with .SHT or
 .SHTML extension), and use the following line as a means of reporting
the current date and time.
     <!-- #EXEC cmd="txtclock.pl" -->

We also include TEXTCLOCK.PL, which is designed to work with PERL 5.7.2.


Good luck.

(and thanks to David Richardson & Anil Khosla for pointing out the need, 
and for finding the PERL5 interpreter, etc.)


