home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
OS/2 Shareware BBS: 35 Internet
/
35-Internet.zip
/
srev13h.zip
/
MULTSEND.DOC
< prev
next >
Wrap
Text File
|
2001-03-27
|
10KB
|
234 lines
31 March 2000
The SREF_MULTI_SEND macrospace procedure of the SRE-http Web Server
SREF_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 stand's 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 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 SREF_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 SREF_MULTI_SEND take care of the grubby details.
I. Using SREF_MULTI_SEND
The basic syntax of SREF_MULTI_SEND is:
rcode=sref_multi_send(message,mime_type,howsend,file_flag,verbose,audnam,resp_hdr,part_hdr)
where:
message: either contains the "message" to be sent (text or non-text);
OR a fully qualified file name (whose contents will be read
and sent)
mime_type : A mime type; such as text/html or image/gif
You can also use mime_type to send additional response headers
(see the notes below).
howsend : A flag that tells SRE-http "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 (i.e.; the first image)
'M' == A middle piece -- more will follow
'E' == End piece -- send this "message" and close the connection.
In addition, you can "build" a long message, and display
each portion as soon as they are added. To do this, use the
following HowSend codes:
'1S' and '1E' -- Start and end a "sent in pieces" single part
document
'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' and '1A' -- Add stuff (between 1S-1E; SS-SE ; MS-ME; or ES-EE)
fileflag: If equal to 1, then "message" is to be treated as a
fully-qualified file name (Optional)
verbose : If > 2, some status info will be displayed (optional)
audnam : Name to use when writing to GoServe audit file (for future
implementation)
resp_hdr : Optional list of response headers-- to add before the first part.
If more then one header, then each header should be
seperated by a CRLF, but there should NOT be a CRLF at the end
of this string.
Note that as of 1.3h.0300.c, "part headers" are specified with
the part_hdr argument.
part_hdr : Optional list of part specific response headers
See the technical notes below for details on resp_hdr and part_hdr.
Notes:
* The return code (rcode) is the RC from the 'SEND' command: you can
check for negative values which indicate a broken connection.
* MULTSEND.CMD demos the use of SREF_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.
* audnam is ONLY used on "first calls".
In particular, when howsend=1, 1S, S, or SS.
* mime_type is only used on "first calls of a part".
In particular, when howsend=1, 1S, S, SS, M, MS, E, or ES.
* If howsend='A', the name and mime_type arguments are ignored.
* If mime_type is not specified, text/html is assumed.
* If howsend is not specified, A is assumed.
* We no longer recommend using the mime_type argument to send additional
"part specific" headers -- you should use the part_hdr argument instead
(as explained below).
Examples:
A 3 picture animation:
foo=sref_multi_send('d:\i1.gif','image/gif','S',1)
foo=sref_multi_send('d:\i2.gif','image/gif','M',1)
foo=sref_multi_send('d:\i3.gif','image/gif','E',1)
A 3 screen status report, with the middle portion a "running tally"
foo=sref_multi_send('Welcome','text/plain','S',,,, ,
'HEADER ADD X-1: Welcome','X-part0: Yes ')
foo=sref_multi_send('Part 1 is done','text/plain','MS',,,, ,
,'X-part1: On ')
foo=sref_multi_send('Part 2 is done',,'A')
foo=sref_multi_send('Part 3 is done',,'ME')
foo=sref_multi_send('good bye','text/plain','E')
A 5 piece single part document:
foo=sref_multi_send(' This is the first line,'text/plain','1S')
foo=sref_multi_send(' This is line 2 ',,'1A')
foo=sref_multi_send(' This is line 3 ',,'1A')
foo=sref_multi_send(' This is line 4 ',,'1A')
foo=sref_multi_send(' This is the last line ','text/plain','1E')
Simple usage:
foo=sref_multi_send('<h2>This is line 3')
is the same as
foo=sref_multi_send('<h2>This is line 3',,'A')
(note that the second argument is ignored when howsend='A')
For a longer example, see MULTSEND.CMD
II. Technical Notes
Using the RESP_HDR and PART_HDR arguments
RESP_HDR is used to add response headers to your response. These are added
before the body (of a single part document), or before the first part
(of a multi-part document).
The RESP_HDER argument is ONLY used with "beginning" parts --
when howtype = '1','1S','S', or 'SS'.
The form of the RESP_HDR should be similar to the form used in
advanced options -- a CRLF delimited list, with each line starting with
either 'HEADER ADD or 'HEADER DROP.
For example:
resp_hdrs='HEADER ADD X_1: This is X1 '||'0d0a'x||'HEADER Drop Expires'
Note that both ADD and DROP are supported.
PART_HDR is used to add "part specific" headers (these are less
frequently used). PART_HDR is used in "first parts" -- when
howtype='S', 'SS', 'M', 'MS', 'E', or 'ES'
PART_HDR also uses a CRLF delimited list, which will be
added to the "head" of the part as is. Thus, you should NOT
include the 'HEADER ADD. Furthermore, HEADER DROP is NOT supported.
For example:
hdrs='PART_NEW: This is another part '||'0d0a'x||'Content-Disp: keep'
Lastly, if either PART_HDR or RESP_HDR argument is specified in a
"middle" or "end" part (such as when howtype='A','SE', etc'), it will
be ignored.
Multi-Part Documents:
When ever you issue a S (or SS), M (or MS), or E (or ES) command,
SRE 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 one 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 portions 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:
* You can use a sequence of SS, A, SE to send-in-pieces
a single part document, but it's not recommended (GoServe
may not close the document properly)
* 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'.
Expiration note:
As of ver 1.3a, the FIX_EXPIRE "correction" is automatically handled
when SREF_MULTI_SEND is first invoked (with a '1S', 'S', or 'SS').