## 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:
  - SREF_VALUE: extract information from the OS/2, GoServe, and SRE-http environments SREF_GOS: a http/1.1 compliant replacement for the FILE and VAR GoServe completion codes
  - SREF_QUEUE: read and write information to an SRE-http queue
  - SREF_BROWSER_INFO: Get information about the client's browser
  - SREF_GET_COOKIE: Get a cookie
  - SREF_GET_URL: Get a resource from a remote server
  - SREF_GRAB_FILE: Read a file into a string, possibly waiting for it to be unlocked
  - SREF_HOST: Get information on an IP address
  - SREF_NEW_GMT: Return a GMT date and time.
  - SREF_WILDCARD: Compare a "needle" to a possibly * containing "haystack"

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:
  - In addition to SRE-http's access control capabilities, you can require a "dynamic-password" based on shared-secret -- see DYNPWD.DOC for the details.
  - You can encrypt responses using a moderately strong (a 40bit) non-SSL encryption algorithim -- see ENCRYPT.DOC for the details
  - You can also use javascript to encrypt responses from a client
Multiple part documents
  Multiple part documents are used when performing server-push. Since this requires a fairly precise syntax, SRE-http provides SREF_MULTI_SEND, a procedure that facilitates the creation of these documents by taking care of these grubby details.

Reading a database
  If your addon needs to examine databases quickly & frequently, the SRE-Data addon for SRE-http may be useful. It provides a simple, but fast, daemon that will quick-sort and binary-search fixed or variable length data files.

Storing addons in macrospace
  Since procedures stored in macrospace are much more quickly loaded, it can be advantageous to tell SRE-http to load your addons into macrospace. This can be accomplished with the KEEP_ADDONS parameter(s), which instructs SRE-http to load selected external procedures into macrospace.
  Alternatively, ambitious programmers can create a library of their own macrospace procedures to be called as addons -- a library which you could "load into macrospace" before starting GoServe/SRE-http. For details on how to do this, see the description of the KEEP_ADDONS. parameter in INITFILT.DOC.