home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 35 Internet / 35-Internet.zip / srev13h.zip / prereply.doc < prev    next >
Text File  |  2001-03-27  |  7KB  |  158 lines
  1. 10 March 2000   
  2.                      Using SRE-http's "pre-reply" feature
  3.  
  4. 1) Introduction
  5.  
  6. SRE-http's "pre-reply procedure" feature allows you (the savvy webmaster) to have a 
  7. "last second" shot at the contents to be sent to a client.  In other words,
  8. the "pre-reply" is a hook into SRE-http, a hook that occurs prior to sending 
  9. the contents of a response to the client.  
  10.  
  11. In general, this feature is best used when you need to make generic changes to
  12. almost all responses.  For example, you may wish to translate text files into
  13. alternative code pages (say, based on the user-agent). Or, you might want to
  14. add an additional response header. Or, you might want to add a time and date stamp
  15. to all text files. Or you might want to attempt special encoding (such as 
  16. rsync encoding).
  17.  
  18. The main advantage of the "pre-reply" is that it applies to nearly all SRE-http
  19. responses -- images and other non-text files, text/plain files, html files with and 
  20. without server-side-includes, the output of most addons, and the output of most
  21. CGI-BIN scripts.
  22.  
  23. Although quite powerful, this "pre-reply" feature is a rather blunt, and not
  24. particularly efficient, instrument. 
  25. In many cases, you might be better off using one of the several other 
  26. "request specific" modifications possible in SRE-http, such as:
  27.   * content-negotiation (NEGOTIAT.DOC)
  28.   * browser specific or client specific modifications (BYBROWSR.DOC and BYCLIENT.DOC), and
  29.   * advanced options (ADV_OPTS.DOC)
  30.  
  31.  
  32. II) Usage
  33.  
  34. To specify a "pre-reply procedure":
  35.  
  36.   1) Modify the PRE_REPLY_PROCEDURE parameter in INIT_STA.80.
  37.      You should set this to be the fully qualified name of an file containing 
  38.      an external REXX procedure.
  39.          Examples: 
  40.                 PRE_REPLY_PROCEDURE='D:\GOSERVE\PREREP.CMD'
  41.                         this is the "use by default" format
  42.                 PRE_REPLY_PROCEDURE='!D:\GOSERVE\SRERsync.CMD'
  43.                         this is the "use only if enabled on a selector
  44.                         specific basis" format.
  45.  
  46.     Notes: 
  47.         * to not use a PRE_REPLY_PROCEDURE, set PRE_REPLY_PROCEDURE=0
  48.         * see INITFILT.DOC for details on PRE_REPLY_PROCEDURE.
  49.         
  50.  2) Create this "external REXX procedure".
  51.  
  52.     This procedure will be called (by SRE-http) as:
  53.         stuff=sref_preprely_proc(contents,fileflag,mimetype,clen,modstring)
  54.  
  55.    where
  56.      contents = the actual contents to be sent to the client, or a fully
  57.                  qualified file name
  58.      fileflag = 0 if this is actual contents, 
  59.                  1 if this is a file, 
  60.                  2 if "sref_multi_send" contents
  61.      mimetype = the mime type,
  62.                     For example, image/gif or text/plain.
  63.       clen    = content-length (might be missing)
  64.     modflag  = a string to use to signal "new mimetype" (and other flags)
  65.  
  66.  3) Possibly set the PRE_REPLY selector-specific advanced option.
  67.      * To suppress (on a selector specific basis) the use of a 
  68.         pre-reply procedure, use the SET PRE_REPLY 0 advanced option.
  69.      * For a "use only if enabled on a selector specific basis"
  70.        specification of a pre-reply procedure, you must set a
  71.        SET PRE_REPLY 1 advanced option.
  72.      
  73.        See ADV_OPTS.DOC for the details on the SET PRE_REPLY advanced option.   
  74.  
  75. The "stuff" returned by your "pre-reply procedure" should be:
  76.  
  77.    ''   == when the procedure responds to the client (using 
  78.            SRE_COMMAND('FILE or SRE_COMMAND('VAR  -- do NOT
  79.            user SREF_GOS)
  80.    0    == when the procedure does nothing (SRE-http will then take care of 
  81.            the response in its normal fashion)
  82.    or...
  83.          modified-contents to be sent to the client.  SRE-http will return this 
  84.          modified-contents  to the client (perhaps after applying
  85.          encrypt, compression, and other additional transformations).
  86.  
  87. Assuming that
  88.    "modcontents" is the result of your pre-reply procedure,
  89.    modflag is the "modflag" argument (see above)
  90. then the format of the modified-contents should be one of:
  91.  
  92.   i)  modcontents  
  93.     *     the content-type is not modified,
  94.     *     range retrieval is NOT attempted
  95.     *     delta encoding is attempted    
  96.  
  97.  ii)  modflag||' '||mime/sub||'0d0a'x||modcontents  
  98.     *     mime/sub is the new content-type.  
  99.     *     range retrieval is NOT attempted
  100.     *     delta encoding is attempted
  101.  
  102. iii)  modflag||' '||mime/sub||' '||nodelta_flag||'0d0a'x||modcontents
  103.      *    mime/sub is the new content-type.  You MUST specify mime/sub, even 
  104.           if it hasn't changed.
  105.      *   if nodelta_flag =1 then delta encoding is suppressed
  106.  
  107.     
  108. Notes:
  109.  
  110.   *  If the PRE_REPLY procedure modifes the contents
  111.  
  112.         * GoServe caching  (and SREPROXY caching) will be suppressed
  113.         * Range retrievals are NOT attempted
  114.         * Unless delta_flag is used, delta encoding may be attempted
  115.       
  116.  
  117.   *  In addition to the variables sent by SRE-http, the usual GoServe variables,
  118.      and the various SRE-http procedures, can be used in the "pre-reply" procedure.
  119.  
  120.   *  If you change the "mimetype" of the response (say, you return a .GIF instead 
  121.      of a .JPEG), you MUST use the "special variant" of modified-contents (noted
  122.      above).
  123.  
  124.   *  If you change the size of the contents, SRE-http will detect this and
  125.      set the appropriate content-length header -- you should NOT set the
  126.      content-length header in your pre-reply procedure 
  127.  
  128.   *  This "pre-reply" procedure is called by the SREF_GOS procedure. Some older 
  129.      addons,  and some cgi-bin scripts, skip this addon -- 
  130.      for these, the "pre-reply" feature will not work.  
  131.            In other words: the output of an addon that uses the 'VAR and 
  132.           'FILE GoServe completion  codes will NOT be subject to this "pre-reply"           
  133.           procedure.
  134.  
  135.    * Rather then calling the actual external procedure, SRE-http calls a version of
  136.      the procedure it stores in macrospace. Therefore, to change this "pre-reply"
  137.      procedure, you MUST restart GoServe.
  138.  
  139.      Note that the "sref_prereply_proc" procedure name is an arbitrary name
  140.      used by sre-http when saving this procedure file to macrospace; you do 
  141.      NOT have to use this as a label anywhere in your procedure.
  142.   
  143.    * For an example of a simple "pre-reply procedure", see PREREP.CMD -- it
  144.      adds date-stamps to all text/plain, text/html, and image/gif files.
  145.    
  146.    * For another example, see the CVT_PAGE utilities, which contain CP_CONV.CMD -- 
  147.      it converts cyrillic code pages (http://www.srehttp.org/apps/cvt_page/)
  148.  
  149.    * Or, see the SRERSYNC utility, which uses rsync to return a differnce
  150.      file.
  151.  
  152.    * To suppress or enable the use of a pre-reply procedure on a selector 
  153.      specific basis, you can SET the PRE_REPLY variable as a selector-specific
  154.      "advanced options" (see ADV_OPTS.DOC for the details).
  155.  
  156.  
  157.  
  158.