First, SREhttp/2 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 SREhttp/2 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 SREhttp/2. This procedure can handle the request, or it can subsequently call any other program (such as a database manager).
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 SRE2003 terminology; such as selector and action .
and ...
| Example: | SREhttp/2's STATUS.CMD (it's installed in the SREHTTP2\ADDON directory)
is a simple addon that displays arguments passed
to addons. It can be called using: /status?hello (the hello is optional). |
How SREhttp/2 finds an addon program
SREhttp/2 will match the requested addon to a program (typically a REXX program).
There are several places this program can be stored.
Arguments supplied by SREhttp/2
When calling an addon, SREhttp/2 will provide a set of arguments.
You can retrieve them using:
parse arg list,servername,verb,tempfile,,
prog_file,reqnum,verbose,user,privset,,
uri,host_nickname,id_info,aiter,attribs,seluse2
where ...
| list | The list of arguments passed to the addon.
|
|---|---|
| servername | the domain name (or IP address) to whom this request was addressed. |
| verb | The request method. Either GET, POST, or HEAD. |
| tempfile | A name of a temporary file that the addon can use to build a response. The addon is not required to use this file, but it is a file name that is reserved for this request. |
| prog_file | The name of the file containing the addon. Actually, prog_file should be parsed using: parse var prog_file prog_file ',' mproc If the addon was pre-loaded into macrospace, then the mproc contains the name of this macrospace procedure. Otherwise, mproc will be blank. |
| reqnum | The request number. This has the form nnCC, where:
|
| verbose | The value of the SREhttp2 VERBOSE variable. |
| client_ip | the client's IP address. Note: you can use SRE_CLIENTNAME to retrieve the client's IP name. |
| privset | the client privileges granted to this client.
|
| uri | the request-string, without any url-decoding; and without any removal of !SPECIAL commands. |
| host_nickname | the HOST_NICKNAME (corresponding to the servername). |
| id_info | Special identifier information that can be used by several SRE2003 and SREHTTP2 procedures. |
| aiter | Usually blank. However, if 1, then this is the second (or more) time this addon has been called during this request. Multiple calls can only occur if the addon had previously returned a PRIVS to SREhttp/2. |
| attribs | The selector-specific attributes. This can be parsed using:
parse var attribs ,
realm '01'x ,
rule '01'x ,
redirect '01'x ,
options '01'x ,
failure_file '01'x ,
permissions '01'x ,
requires |
| seluse2 | The selector, after internal redirection. |
| Example: |
code that uses lineout to write HTML to TEMPFILE...
rcode=sre_command('FILE ERASE type text/html name 'tempfile)
return rcode
|
|---|
This technique is often recommended -- since SREhttp/2 will then be able to apply its pre-reply procedures to the addon output.
| Syntax: |
|
|---|
To induce SREhttp/2 to lookup client privileges, you can use one of these returns:
| Note: | In both the AUTH and PRIVS cases, if the client has no username/password defined, she can leave the username and password fields blank, and re-submit the request -- SREhttp/2 will not find any client privileges, and will set the privset to be empty. |
|---|
After determining the (possibly blank) client privileges, SREhttp/2 will then recall the addon. Note that other then the privset parameter (and the aiter parameter), all of the other parameters will be the same.
The aiter parameter is also set on a re-call after a PRIVS, PRIVS_CHECK, or PRIVS_LOOK return. Specifically, when an addon is first called, aiter is blank. On subsequent calls (after one of these returns), aiter is set to 1 .
Addons should examine the value of aiter before issuing a PRIVS, PRIVS_CHECK, or PRIVS_LOOK. Failure to do so could cause an infinite loop!Note that if, after using PRIVS, a client does not have sufficient privileges, addons can:
| Hint: | Some sample code using PRIVS and AUTH:
if wordpos('SUPERUSER',privset)=0 then do
if aiter='' then return 'PRIVS This addon requires superuser privileges '
return 'AUTH This addon requires that you have superuser privileges ' /*force auth response */
end |
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 the request information into a VARLIST stem variable:
/* if GET, use original request string*/
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=sre_packur(translate(aval,' ','+'))
varlist.avar=aval
end
| Note: |
The URL-decoding performed by SREhttp/2 will not convert
+ characters to spaces -- you'll always have to do that yourself. This can be done with:
newlist=translate(list,' ','+'). Caution: do this before you call SRE_PACKUR; else you'll end up converting legitimate + characters to spaces! |
|---|
These addons might have installation procedures that register the addon with SREhttp/2.
Would you like to list the addons currently registered with SREhttp/2