The SWSRESP Function
Related Topics
 |
May be used in Shadow/REXX |
| |
May be used from Other REXX interpreters |
| |
High Level language interface is available |
SWSRESP is a high level function used to buffer customized outbound HTTP response headers for subsequent transmission to Web client browsers.
SWSRESP may be used to buffer an HTTP response header at any time during the life of a Web transaction. Using SWSRESP to buffer HTTP response headers differs from merely writing these headers using SWSSEND:
- When using SWSSEND, HTTP headers must be written before any message body data (e.g. an HTML page or binary GIF image) has been output.
- However, SWSRESP may be used before, during or after output of the message body.
The Server merges the HTTP response headers which have been buffered using SWSRESP with any other data generated by the Web transaction. This merge processing takes place when the Web transaction ends and causes the complete output stream to be assembled and transmitted to the client.
SWSRESP is only valid when a Web transaction procedure is operating in server-parsed header mode since the merging/assembly, described above, is disabled in non-parsed-header mode. A call to SWSRESP will return an error if the Web transaction is not operating in server-parsed header mode.
SWSRESP Syntax
The SWSRESP function takes three arguments. The invocation format for SWSRESP is:
Z = SWSRESP( func, hname, hvalue )
- func
- The first argument, func, specifies the function to be performed. At this time the only supported function value is "ADD". Any other argument value will return an error.
- hname
- The second argument, hname, specifies the name of the HTTP response/general
header to be transmitted to the Web server client. The HTTP response header name should
be one which is universally recognized as defined in the
Hypertext Transfer Protocol - HTTP/1.1
(RFC2068) specification. However, any string may be coded.
The colon which ends each HTTP response header name must be omitted from the string, since SWSRESP always inserts a trailing colon (e.g. Code "Content-type", not "Content-type:").
- hvalue
- The third argument, hvalue, specifies the value for the corresponding HTTP response header. The content of the third argument will, of course, vary depending on the response/general header specified in the second argument. The entity body text is converted to ASCII and then transmitted exactly as provided by this argument.
Return Values
SWSRESP always returns a numeric value. A zero return value indicates successful buffering (though not actual transmission) of the HTTP response header. A non-zero return value indicates that an error has occurred.
The SWSRESP operation is not logged to the Server's wrap-around trace file unless an error occurs. If you need to trace information actually sent as a result of an SWSRESP request, use the SENDTRACE keyword of the /*WWW rule header.
Example
The following call will cause two HTTP response headers to be merged with other headers generated by SWSFILE. A "Pragma: no-cache" and "Expires: Mon, 14 APR 1998 12:02:03 GMT" HTTP response header will be included in the final output transmission stream.
/*WWW /testswsresp sendtrace(yes) /*REXX Z = SWSRESP('ADD','Pragma','no-cache') Z = SWSFILE('SEND','DDN','SAMPDATA','ICINFO','image/gif','BINARY') Z = SWSRESP('ADD','Expires','Mon, 14 APR 1998 12:02:03 GMT')