SREhttp/2 Manual

## Using SREhttp/2 Pre-Response Procedures

### 1) Introduction

SREhttp/2s `pre-response procedure` feature allows you (the savvy webmaster) to have a last second shot at the contents to be sent to a client. In other words, `the pre-response` is a hook into SREhttp/2, a hook that occurs prior to sending the contents of a response to the client.

In general, this feature is best used when you need to make generic changes to large sets of responses. For example, you may wish to translate text files into alternative code pages (say, based on the user-agent). Or, you might want to add an additional response header. Or, you might want to add a time and date stamp to a subset of your text files. Or you might want to attempt special encoding (such as GZIP content-encoding, or SREhttp/2's encryption) to all document files.

Although quite powerful, this `pre-response` feature is a rather blunt, and not particularly efficient, instrument. For example, any changes due to a `pre-response procedure` will suppress SRE2003's request caching. In many cases, you might be better off using one of the several other request specific modifications possible in SREhttp/2, such as:

- content-negotiation
- advanced options

  ### II) Usage

  As with SRE2003 SRE2003's IM procedures, you can specify several `pre-response` procedures, and then use one of these.
  Although one of the pre-response procedures will be used by default, you can also choose which one to use on a selector-specific basis.

  The following is done to specify `pre-response procedures`:

  1. Set `PRE_RESPONSE` parameter(s) in PRELOADS.CFG (in the `SREHTTP2\CFG` directory).
     Each `PRE_RESPONSE` parameter should have the following structure:
     `PRE_RESPONSE= name file astring`
     where:

     `name` | a short, case-insensitive, unique name that identifies this `pre-response procedure` If you specify just one pre-response procedure, it will always be used If you specify several pre-response procedures, the default procedure used will be determined by: The one with a `name` of `DEFAULT` Otherwise, the first pre-response procedure specified Note that instead of using the default you can choose a pre-response procedure on a selector-specific basis. One of these choices is to not call a pre-response procedure.
     `file` | a fully qualified name of a file containing an external REXX procedure; or a relative filename, relative to the filter directory (eg; to the `SREHTTP2` directory).
     `astring` | an optional string that will be sent to the pre-response procedure. It must not contain commas (commas will be converted to spaces). Note that this string can be changed on a selector specific basis
     Examples: | `PRE_RESPONSE= DEFAULT D:\SRE\PRE_RESP.RXX PRE_RESPONSE= ENCRYPT procs\ENCRYPT.RXX SRE_A PRE_RESPONSE= RSYNC D:\SRE\SRERsync.CMD PRE_RESPONSE= DEFAULT 0 PRE_RESPONSE= 0` Notes: `PRE_RESPONSE=0` means do not call a pre-response procedure. If it is used, all other pre-response entries are ignored. `PRE_RESPONSE=DEFAULT 0` means by default, do not call a pre-response procedure.

  2. Create external REXX procedure(s). Pre-response procedures will be called (by SREhttp/2) as:`
     stuff=SREH2_PRE_RESPONSE(contents,fileflag,mtype,message,req_string,seluse,privset,host_nickname,id_info)`
     where...

     contents | the actual contents to be sent to the client, or a fully qualified file name (whose contents is to be sent)
     fileflag |

  3. `0` if this is actual contents,
  4. `1` if this is a file,
     mimetype the mime type.
     For example, `image/gif` or `text/plain`.
     message a message. By default, this is the `astring` argument (which may be blank) contained in the `PRE_RESPONSE=` definition (in PRELOADS.CFG). Alternatively, the value of message can be set by creating a PRE_RESPONSE selector-specific advanced option.
     req_string the actual request string sent by the client (before url-decoding)
     seluse the transformed (after redirection, etc.) selector. This is the selector that is used to find a matching file.
     privset the client privileges. This may be empty -- since, unless specifically instructed, SREhttp/2 does not bother looking up client privileges for resources that do not have access controls.
     host_nickname the host-nickname of this site
     id_info the SRE2003 id_info for this request (can be used to speed up processing of SRE_COMMAND and other SRE2003 procedures).
  5. The stuff returned by your `pre-response procedure` should be:

     nothing | when the procedure does nothing (SREhttp/2 will then take care of the response in its normal fashion)
     0 status_code bytes_sent | when the procedure responds to the client (using SRE_COMMAND). Note that status_code bytes_sent is the value of the argument returned by the call to SRE_COMMAND.
     1 info '0d0a'x new_contents | SREhttp/2 will return new_contents to the client `info` can contain the following `SRE_COMMAND('FILE ...')` style directives: `type type/subtype` -- use `type/subtype` in the Content-Type header. `EXPIRES nnn` -- modify the Expiration content header. `MD5` or `NOMD5` -- enable/suppress generation of a Content-MD5 response header. ... or ...
     1 '0d0a'x new_contents | If `info` is not specified, the current value of the mimetype (and the Expiration and Content-MD5) response headers are used.

  ### III) Notes

  - Only one pre-response procedure is used with a single request.
    In contrast, several ...
  - pre-transaction procedures,
  - pre-request procedures,
  - EXEC procedures,
    and
  - post-response procedures, can be used with a single request.

  - You can choose which (of several possible pre-response procedures) to use by setting a PRE_RESPONSE selector-specific option. You can also use the `PRE_RESPONSE` selector-specific option to pass a short string to the chosen pre-response procedure.

  - All static responses are subject to the pre-response procedures. However, !SPECIAL requests, CGI-BIN requests, and SREhttp/2 addons are typically not subject to pre-response procedures. Actually, appropriately written addons are subject to pre-response procedures,

  - SREhttp/2 comes with several `pre-response procedures`. They are stored in the SREHTTP2\PROCS directory:

  - `PRE_RESP.REX`. A simple example, it adds date-stamps to all text/plain, text/html, and image/gif files.

  - `ENCRYPT.REX`. Supports SREhttp/2's encryption

  - `GZIP.REX`. Supports GZIP as a content-encoding.

    > If the client lists `GZIP` in an `Accept-Encoding` request header, then `GZIP.REX` will GZIP the contents of a response, and will add a `Content-Encoding: GZIP` response header.

  - `PACKBACK.REX`. Compresses HTML documents by removing extraneous characters (extra spaces, comments, etc). PACKBACK can also GZIP (after removing extaneous charaters). See PACK_CVT for the details. on PACKBACK and CVT_PAGE.
  - `CVT_PAGE.REX`. Convert the code page (character set) of the response. Not currently working!

  - If a pre-response procedure modifes the contents:
  - SRE2003 request caching will be suppressed
  - Instance-manipulation, including range extraction, may be attempted

  - In addition to the variables sent by SREhttp/2, the usual SRE2003 variables, and the various SREhttp/2 and SRE2003 procedures, can be used in the `pre-response` procedure. For example, you can use `SRE_COMMAND('HEADER ...')` to add new response headers.

  - If you change the size of the contents, SREhttp/2 will detect this and set the appropriate content-length header -- you should not set the content-length header in your`pre-response procedure`.

  - Rather then calling the actual external procedure, SREhttp/2 calls a version of the procedure it stores in macrospace. Therefore, to change a `pre-response` procedure, you must restart SRE2003.

  - You can use `alist=SRE_VALUE('PRE_RESPONSE',,'SREBEST')` to retrieve the list of currently loaded PRE_RESPONSE procedures.

    The syntax of `alist` will be:
    `name proc_id astring , ... , name proc_id astring`
    where `proc_id` identifies a macrospace procedure (that contains the pre-response procedure).

  Last updated 27 September 2002.