Using SREhttp/2 Pre-Response Procedures

1) Introduction

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:

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	0 if this is actual contents, 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).

   
   
3. 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).