10 March 2000 Using SRE-http's "pre-reply" feature 1) Introduction SRE-http's "pre-reply 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-reply" is a hook into SRE-http, 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 almost all 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 all text files. Or you might want to attempt special encoding (such as rsync encoding). The main advantage of the "pre-reply" is that it applies to nearly all SRE-http responses -- images and other non-text files, text/plain files, html files with and without server-side-includes, the output of most addons, and the output of most CGI-BIN scripts. Although quite powerful, this "pre-reply" feature is a rather blunt, and not particularly efficient, instrument. In many cases, you might be better off using one of the several other "request specific" modifications possible in SRE-http, such as: * content-negotiation (NEGOTIAT.DOC) * browser specific or client specific modifications (BYBROWSR.DOC and BYCLIENT.DOC), and * advanced options (ADV_OPTS.DOC) II) Usage To specify a "pre-reply procedure": 1) Modify the PRE_REPLY_PROCEDURE parameter in INIT_STA.80. You should set this to be the fully qualified name of an file containing an external REXX procedure. Examples: PRE_REPLY_PROCEDURE='D:\GOSERVE\PREREP.CMD' this is the "use by default" format PRE_REPLY_PROCEDURE='!D:\GOSERVE\SRERsync.CMD' this is the "use only if enabled on a selector specific basis" format. Notes: * to not use a PRE_REPLY_PROCEDURE, set PRE_REPLY_PROCEDURE=0 * see INITFILT.DOC for details on PRE_REPLY_PROCEDURE. 2) Create this "external REXX procedure". This procedure will be called (by SRE-http) as: stuff=sref_preprely_proc(contents,fileflag,mimetype,clen,modstring) where contents = the actual contents to be sent to the client, or a fully qualified file name fileflag = 0 if this is actual contents, 1 if this is a file, 2 if "sref_multi_send" contents mimetype = the mime type, For example, image/gif or text/plain. clen = content-length (might be missing) modflag = a string to use to signal "new mimetype" (and other flags) 3) Possibly set the PRE_REPLY selector-specific advanced option. * To suppress (on a selector specific basis) the use of a pre-reply procedure, use the SET PRE_REPLY 0 advanced option. * For a "use only if enabled on a selector specific basis" specification of a pre-reply procedure, you must set a SET PRE_REPLY 1 advanced option. See ADV_OPTS.DOC for the details on the SET PRE_REPLY advanced option. The "stuff" returned by your "pre-reply procedure" should be: '' == when the procedure responds to the client (using SRE_COMMAND('FILE or SRE_COMMAND('VAR -- do NOT user SREF_GOS) 0 == when the procedure does nothing (SRE-http will then take care of the response in its normal fashion) or... modified-contents to be sent to the client. SRE-http will return this modified-contents to the client (perhaps after applying encrypt, compression, and other additional transformations). Assuming that "modcontents" is the result of your pre-reply procedure, modflag is the "modflag" argument (see above) then the format of the modified-contents should be one of: i) modcontents * the content-type is not modified, * range retrieval is NOT attempted * delta encoding is attempted ii) modflag||' '||mime/sub||'0d0a'x||modcontents * mime/sub is the new content-type. * range retrieval is NOT attempted * delta encoding is attempted iii) modflag||' '||mime/sub||' '||nodelta_flag||'0d0a'x||modcontents * mime/sub is the new content-type. You MUST specify mime/sub, even if it hasn't changed. * if nodelta_flag =1 then delta encoding is suppressed Notes: * If the PRE_REPLY procedure modifes the contents * GoServe caching (and SREPROXY caching) will be suppressed * Range retrievals are NOT attempted * Unless delta_flag is used, delta encoding may be attempted * In addition to the variables sent by SRE-http, the usual GoServe variables, and the various SRE-http procedures, can be used in the "pre-reply" procedure. * If you change the "mimetype" of the response (say, you return a .GIF instead of a .JPEG), you MUST use the "special variant" of modified-contents (noted above). * If you change the size of the contents, SRE-http will detect this and set the appropriate content-length header -- you should NOT set the content-length header in your pre-reply procedure * This "pre-reply" procedure is called by the SREF_GOS procedure. Some older addons, and some cgi-bin scripts, skip this addon -- for these, the "pre-reply" feature will not work. In other words: the output of an addon that uses the 'VAR and 'FILE GoServe completion codes will NOT be subject to this "pre-reply" procedure. * Rather then calling the actual external procedure, SRE-http calls a version of the procedure it stores in macrospace. Therefore, to change this "pre-reply" procedure, you MUST restart GoServe. Note that the "sref_prereply_proc" procedure name is an arbitrary name used by sre-http when saving this procedure file to macrospace; you do NOT have to use this as a label anywhere in your procedure. * For an example of a simple "pre-reply procedure", see PREREP.CMD -- it adds date-stamps to all text/plain, text/html, and image/gif files. * For another example, see the CVT_PAGE utilities, which contain CP_CONV.CMD -- it converts cyrillic code pages (http://www.srehttp.org/apps/cvt_page/) * Or, see the SRERSYNC utility, which uses rsync to return a differnce file. * To suppress or enable the use of a pre-reply procedure on a selector specific basis, you can SET the PRE_REPLY variable as a selector-specific "advanced options" (see ADV_OPTS.DOC for the details).