Hints on Programming to the SRE-http API

Perhaps it's a bit pompous to call it an API, but the combination of GoServe's command set and the tools provided by SRE-http does create an environment that can be quite conducive to the creation of web aware applications. In this document we outline SRE-http's contribution to this mix. For those interested in the GoServe command set, we recommend reading the GoServe.DOC file that comes with GoServe.

First, SRE-http is fully compatabile with CGI-BIN; and can even use PERL scripts. While CGI-BIN has the huge advantage of portability, it is a clunky and sort-of-slow interface. Hence, SRE-http also offers its own method of allowing for "server side processing of client requests" -- through the use of addons. For example, we've created a number of publically available addons, including a bulletin board system, a search engine, and a text-to-gif utiliity.

Creation of these addons requires writing an external REXX procedure that is then called by SRE-http. This procedure can handle the request, or it can subsequently call any other program (such as a database manager). In fact, SRE-http makes it easy to create (in REXX) daemons that these external procedures can talk to, a feature that can greatly improve response time.

We hope the following hints will aid, and entice, you in creation of your own addons! We do presume that you understand some of the somewhat-arcane SRE-http terminology; such as selector and action .

Hints

Invoking an addon
Addon's are invoked when:
  1. When a POST method request is recieved, or
    a GET method request is recived that includes a ?
  2. The action portion of the selector does not contain a CGI-BIN substring

In either case, the ACTION is assumed to point to a file containing a REXX procedure. The file should have a .CMD or .80 extension (if you are not using port 80, then .80 should be .nnnn, where nnnn is your http port). The file shoud be in (or under, since action can contain subdirectory information) the ADDON directory; or in a local virtual directory.

Arguments supplied by SRE-http
When calling an your addon external procedure, SRE-http will provide a list of arguments, including:
   datadir   tempfile  action   req_string   verb         uri       user
   basedir   workdir   privset  env_id       transaction  verbose   servername
   host_nickname     home_directory  
Parsing information provided with the request
SRE-http provides the request string (req_strg) as one of its arguments. This is either the body of a POST request, or the stuff following a ? of a GET request. In the former case (POST), the information is "as is", with no conversions. In the latter case (GET), the information has been URL-decoded; with URL encoding (of & and other special characters) reversed.

While this decoding does save a step, in many cases it can be a hindrance. In particular, if the request may contain special characters, such as +, = and &, it can be difficult to determine whether these characters were seperators added by the browser or important characters that are part of the response .

If this is likely to occur; we recommend use of the URI argument. For example, the following can be used to parse a the request information into a VARLIST stem variable:

   if VERB="GET" then  parse var uri . '?' list
   do until list=""
       parse var list a1 '&' list
       parse var a1 avar '=' aval
       avar='!'||translate(avar)
       aval=packur(translate(aval,' ','+'))
       varlist.avar=aval
   end
Notes:
  • The URL-decoding performed by SRE-http will not convert + characters to spaces -- you'll always have to do that yourself (but do it BEFORE you PACKUR; else you'll convert legitimate + characters to spaces!)
  • You can use the GET_DECODE_OPTIONS parameter to suppress this "automatic decoding of GET options"

  • Using the SRE-http procedure library
    SRE-http makes use of a macrospace procedure library. A number of these procedures should prove useful to addon authors. Of especial interest are:

    Creating daemons
    In many circumstances, such as database manipulation, using a daemon (a semi-permanent thread running along side of GoServe) can markedly improve throughput. Although a great tool, communication with these independent threads can be a hassle. To relieve the user of these hassles, SRE-http provides a number of procedures to help you work with threads.

    Note: when writing daemons to work with GoServe, you should use the PMPRINTF routine (or PMPRINTF_SREF) to write status/debug information (SAY's will not be displayed anywhere).

    Encryption
    SRE-http comes with several encryption facilities: