15 June 2002

   The SREH2_MULTI_SEND procedure of the SREhttp/2 Web Server

SREH2_MULTI_SEND is used to create a multi-part document. It can also
be used to "send pieces" of a document as it becomes available.

  * Multi-part documents are used for "server push" delivery of several files
    sequentially. The basic presumption of a multi-part document is that
    each part stands on its own. Typically, a browser will replace an earlier 
    part as soon as the next part becomes available. For example, 
    server push can be used as a form of animation, with each part being
    a "frame" of a movie. Alternatively, server push can be used to send
    a "get ready" document, followed by a selected file, and lastly
    a thank you.
    
    For example, the GIF_TEXT addon uses multi-part document to build
    complicated images, with simpler images displayed first, which 
    are then replaced by more elaborate versions.

         Multi-part documents require browsers that are able to maintain
         connections, and that understand the multipart/mixed-replace mimetype.
         Internet-ancient browsers, such as IBM Web Explorer, can not do this.

  * Sending pieces is used to send earlier portions of a document as 
    they become available. This gives the client something to read when
    long documents are being built on-the-fly. For example, the BBS
    addon uses "sending in pieces" to display long listings, that
    might "time out" the server (or the client's attention span)
    if nothing is sent before the entire listing is created.
        
       Send-in-pieces documents can be handled by all browsers.


By using SREH2_MULTI_SEND, it's easy to create "multi-part" 
or "send as pieces" documents. All you need to do is specify a list of 
files (or strings), and let SREH2_MULTI_SEND take care of the grubby details

Technical note: SREH2_MULTI_SEND makes extensive use of the SEND option of 
                SRE2003's SRE_COMMAND command.


I. Using SREH2_MULTI_SEND 

The basic syntax of SREH2_MULTI_SEND is:
 res=SREH2_multi_send(message,options,howsnd,fflag,verbose,opthdr,id_info,cprot)

where:
  message: a message, or filename, to send
  options: header and connection-close options
  howsnd:  specifies whether this is a part, or a piece, of a document
  fflag:   flag that means "message is a filename"
  verbose:  verbose status messages 
  opthdr:   additional headers
  id_info: optional, it's use can speed up processing a bit
  cprot:   clientprotocol. Optional, using it can speed up processing a bit.

In greater detail:

 message:
   either contains the "message" to be sent (text or non-text);
   OR a fully qualified file name -- see the fflag description below.

 options:
   Options can contain three items: 
      NOWAIT, EXPIRES d.f, and type/subtype.

   type/subtype refers to the "mimetype".
     * For single part documents, this is the mimetype of the entire document 
     * For multi-part documents, this is the mimetype of the part
        
       Examples: text/html, or image/gif.

   NOWAIT tells SRE2003 to "close the connection when the transaction is 
   completed (do NOT maintain the connection).
              
   EXPIRES d.f causes SRE2003 to add an Expires: header to the document. 
      The d.f is used to form an expiration time.  
      d.f should be: 
         d number_of_days, f fraction_of_a_day
      For example:  
         expires 0.5
      means "this response expires in 12 hours".
               
   Examples of options:
       image/gif
       NOWAIT text/plain
       EXPIRES 7.0
       EXPIRES 0.05 text/html

   Notes on options:
     * NOWAIT and EXPIRES can ONLY be used on the "starting"
       portion of either single or multipart documents. 
       That is, EXPIRES can ONLY be used if howsnd='S', '1', 'SS', or '1S'

    * type/subtype can be used on the starting call of single-part 
      or multi-part documents, and on the starting call to subsequent
      parts of a multi-part document. That is, it can NOT be used
      when howsnd='A', '1A', '1E', 'SE', 'ME', and 'EE'
    

 howsnd:
   A flag that tells SREhttp/2 "where in the multi-send process we are".  

   There are basically four values (with possible modifiers):
     '1' == Single part document to "send in pieces" (requires a modifier)
     'S' == Start the multipart send, and send this part
     'M' == A middle part -- more parts will follow
     'E' == End piece -- send this "part" and close the connection.
               
    In addition, you can "build" a long message, displaying each portion as 
    it becomes available. To do this, use the following HowSnd codes:
     '1S' and '1E' -- Start and end a "sent in pieces" single part document
     '1A'          -- Add stuff (between 1S-1E)

     'SS' and 'SE' -- Start and end the first "part"
     'MS' and 'ME' -- Start and end the middle "part(s)"
     'ES' and 'EE' -- Start and end the final "part"
     'A'           -- Add stuff (between SS-SE ; MS-ME; or ES-EE)

 fileflag:
   If equal to 1, then "message" is to be treated as a fully-qualified 
   file name. The contents of this file will be retrieved, and then sent to  
   the client. 
   Otherwise, message is treated as a string (whose contents will be
   sent to the client).

 verbose: 
   If > 2, some status info will be displayed (optional)

 opthdr:
    Optional list of response headers. 
    See the technical notes below for details on opthdr.
              
 id_info:
    Optional. The id_info argument is provided to addons.
    Providing this to SREH2_MULTI_SEND can speed up processing a bit.

  cprot: 
    Optional. The client protocol (i.e.; HTTP/1.1).  
    When calling SREH2_MULT_SEND a number of times, it can
    speed things up a bit to provide this value. 
    You can obtain this value by calling SRE_EXTRACT('CLIENTPROTOCOL')

Notes:

  * The return code (res) is the status. If blank, no error.
    Otherwise, a message that starts with 'ERROR '

  * MULTSEND.CMD demos the use of SREH2_MULTI_SEND.

  * x and xS are the same (where x=1,S,M, or E.
    In particular: 1S=1, SS=S, MS=M, and ES=E.

  * If howsnd is not specified, A is assumed.

Examples:

 A 3 picture animation:
        foo=SREH2_multi_send('d:\i1.gif','image/gif','S',1)
        foo=SREH2_multi_send('d:\i2.gif','image/gif','M',1)
        foo=SREh2_multi_send('d:\i3.gif','image/gif','E',1)
 
 A 3 screen status report, with the middle portion a "running tally"
        foo=SREh2_multi_send('Welcome','text/plain','S', , , ,
                             'X-1: Welcome')
        foo=SREH2_multi_send('Part 1 is done','text/plain','MS', , ,  ,
                             ,'X-part1: On ')
        foo=SREH2_multi_send('Part 2 is done',,'A')
        foo=SREH2_multi_send('Part 3 is done',,'ME')
        foo=SREH2_multi_send('good bye','text/plain','E')

 A 5 piece single part document:
        crlf='0d0a'x
        foo=SREH2_multi_send(' This is the first line||crlf','text/plain','1S')
        foo=SREH2_multi_send(' This is line 2 '||crlf,,'1A')
        foo=SREH2_multi_send(' This is line 3 '||crlf,,'1A')
        foo=SREH2_multi_send(' This is line 4 '||crlf,,'1A')
        foo=SREH2_multi_send(' This is the last line  ',,'1E')

For a longer example, see MULTSEND.CMD


II. Technical Notes 


Using the OPTHDR argument:

    OPTHDR is used to add response headers. 
      * For single part documents: OPTHDR will add response headers to 
        the document (these are sometimes referred to as "entity headers").
      * For multi-part documents: OPTHDR will add response headers to  
        the part. These will be placed after the "begin part" 
        seperator string.

    Thus, OPTHDR should only be used with 
        howsnd='1', '1S', 'S', 'SS', 'M', 'MS', 'E', or 'ES'. 

    OPTHDR can be a CRLF delimited list, with each line a seperate header.

    Example:          
       phdr='Part-New: This is another part '||'0d0a'x||'Content-Disp: keep'

    Note that if OPTHDR is specified in a  "middle" or "end" portion 
    (when howsnd='A','SE', etc'), it will  be ignored.


Other ways of specifying response headers:

 * The EXPIRES option can be used to set an Expires: "entity" header.
 * The NOWAIT option can be used to generate a 
   Connection: Close "entity" header.
 * The type/subtype option will generate a Content-Type: option.
   ** For single-part documents, this will be an "entity header".
   ** For multi-part documents, this will be a "part header" .
   **The Content-Type "entity" response header for multi-part documents
     will always be set to:
     Content-Type: multipart/mixed ; boundary=asf(%(&*dfF#234asg#%^6q32472341ys
    (the value of the boundary may change).

 * To add additional "entity" headers (headers for the entire document),
   you can use:
     SRE_COMMAND('HEADER ....').
   This must be called before the first call to SREH2_MULTI_SEND.

 * For multi-part documents, use of SRE_COMMAND('HEADER ..') is the
   ONLY way of adding additional "entity" headers

   Example:
     To set a X-Hello "entity" header,
         SRE_COMMAND(' Header X-Hello : This is hello')
     before the first (say, the SS or S) call to SREH2_MULTI_SEND.

     
Multi-Part Documents:
  When ever you issue a S (or SS), M (or MS), or E (or ES) command,
  SREhttp/2  will assume that you are "starting a part".  

  Specifically, xS (x=S,M, or E) will start a new part of a  
  "multi part document".  On the other hand, xE will close this part.

  Upon recieving a "new part", multipart aware browsers (such as 
  netscape 2.0 and  above) will "remove old stuff". This might mean
  clearing the screen (or frame); or clearing the box within
  which an in-line image is drawn.

  In contrast, "A" means "add new content" -- it never generates a new
  document.  "A" can be used with any browser, since it does
  not require multi-part awareness. Note that using A with non-text 
  information should work (i.e.; streaming audio), but has not 
  been tested.

  Therefore, "animated" documents (or images) should be generated by
  using:

  1) "S" -- which sends the appropriate "this is a multi-part document" 
            headers to the browser, as well as the file/string you specify, 
  2)one or more "M"  --which sends a seperator line and the 
                       file/string, and
  3) "E" -- which sends the file/string, and closes the multi-part document.

If one of these (S, M, or E) will be sent in pieces (with each piece
appended to previously sent pieces of the "part"), then you should use 
a series of xS, A ... A,xE (where x is S,M or E) calls.

Single Part Document Sent In Pieces:
   Single part documents are more generally understood (by older
   browsers). The calling sequence should be 1S, 1A,..,1A,1E.
   Notes:
     *    As with multi-part documents, you can use as many "1A" calls 
          as needed.
     *    A '1' and a '1S' have the same effect (starting a "send in          
          pieces" document).
     *    You can NOT intermix "1x"  with "Sx", "Mx", or "Ex".
     *    You should always end a "send in pieces" document with
          a '1E'.
     *    If the client is http/1.1, then "chunking" will be used
          (the chunk transfer encoding will be used to send each
          piece to the client).
          
        

