The SWSSEND Function
Related Topics
 |
May be used in Shadow/REXX |
| |
May be used from Other REXX Interpreters |
| |
High-level language interface is available |
| |
Also see SWSSEND Host Command Environment |
SWSSEND is a built-in function used to transmit outbound data to Web server clients from REXX-Language event procedures. SWSSEND may only be used from within WWW event procedures and will return an error if invoked from other event procedure types.
SWSSEND Syntax
The SWSSEND function takes one or two arguments.
The invocation format for SWSSEND is:
z = SWSSEND( arg1 {, arg2 } )
The first argument always specifies the data to be be transmitted to the Web server client. A NULL string should be passed as the first argument for PURGE or FLUSH requests.
The second argument may be one of the following string constants:
- TEXT - Indicates that the data specified by the first argument is text data. The string is converted from EBCDIC to ASCII before transmission and a trailing CRLF is added. Trailing blanks, if any, are also removed from the string. Text format data is assumed, if the second argument is omitted.
- BINARY - Indicates that the data specified by the first argument is binary data. The string is transmitted to the Web Client, as is, without additional processing.
- FLUSH - Indicates that all data already in the outbound buffers should
be committed for transmission to the client. The first SWSSEND argument is ignored.
Out-bound transmission of the response data will normally begin immediately, but may be deferred by the Server, under some conditions, until the transaction ends.
Response data which has been FLUSHed cannot subsequently be discarded using a PURGE request. Once committed, the data is always transmitted to the client, and may be discarded only if the communications session is lost. The use of FLUSH may interfere with the operation of Server-provided recovery routines, which normally PURGE all outbound response data before generating an error message.
We recommend that you use FLUSH requests only in situations where your program requires direct control of the outbound communications session.
- PURGE - Indicates that all data currently untransmitted within buffers
should be discarded, without transmission to the client. The first SWSSEND argument is
ignored.
Note that a PURGE request cannot be used to discard data which has already been committed for transmission (i.e. data which was subject to a previously issued FLUSH request). Only data added to the outbound response since a previous FLUSH request can be purged.
Return Values
SWSSEND always returns a numeric value. If the value is zero the operation has completed successfully. A non-zero return value indicates that the communications session has been lost.
The SWSSEND operation is not logged to the Server's wrap-around trace file unless an error occurs. If you need to trace information sent using SWSSEND, use the SENDTRACE keyword of the /*WWW rule header.
Examples
The following call will buffer the HTML data for outbound transmission. A linefeed character will be added following the data and the data will be translated to ASCII before transmission:
htmldata = "<h1>This is a Header</h1>" z=SWSSEND( htmldata )
The following call will place the data into the outbound buffer with no additional processing:
z=SWSSEND( gifdata , "BINARY" )
The following call will cause all buffered data to be sent to the client immediately.
z=SWSSEND( , "FLUSH" )
The following call will purge all previously buffered data. Data which was flushed prior to this call, will have already been sent to the Web client.
z=SWSSEND( , "PURGE" )