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:
- When a POST method request is recieved, or
a GET method request is recived that includes a ?
- 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:
- 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.