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