S/Web Objects - Response

S/Web Objects

Links on this page:

Properties
Methods

Response

This object handles information relating to the HTTP response.

Properties:

Property	Get/Set	Description
ALLOW	Get/Set	An @Vm'd list of allowed HTTP methods, eg GET,POST,PUT etc
AUTHENTICATE	Get/Set	The Authentication scheme to be used by the browser.
BUFFERCOUNT	Get	Returns the number of 64K buffers in the response
COOKIES	Get/Set	The cookie array used in this response. Cookies are passed @VM delimited, with each cookie value @SVM delimited. Appendix A contains a listing of cookie field values. This property is simply a shell around the GETCOOKIE and SETCOOKIE methods. It is recommended that you use these methods instead.
ENCRYPTCOOKIES	Get/Set	If TRUE$ then cookies will be encrypted using WWW_Utility function LHASH.
ENCODING	Get/Set	The name of the encoding mechanism used ( if any ) to encode the data returned. You will need to review your web server manual for more information on the types of encoding available and the format required.
EXPIRES	Get/Set	The expiry date and time of the response content. The format is Date : "." : Time where date and time are in Revelation internal format.
HEADERS	Get/Set	The custom headers used in this response. Presented as an array delimited by @Vms with the structure HeaderName : @Svm : HeaderValue. This property differs slightly from the GETHEADER and SETHEADER methods. This property GETS and SETS the entire custom header settings. The GETHEADER and SETHEADER methods set and update individual custom headers. If you wish to delete a specific custom header, you must GET the entire set of headers, remove the value you wish to delete from the array, then SET the entire HEADER property.
HTTPS	Get/Set	If TRUE$ then the response may only be returned to the client if the link is via SSL. If not the response is cached and a redirect issued to the browser to switch to SSL but return the cached response (implemented via WWW_SWAP_PROTOCOL)
LENGTH	Get/Set	The length of the response content. This field is automatically set by the SEND method.
LOCATION	Get/Set	The Redirection URL for a redirection header. Forces a redirect of the client browser to the specified location. This also automatically sets the STATUS and REASON to an HTTP 302 message.
LOGMSG	Get/Set	A log message for the HTTP Server to use
NOTFOUND	Get/Set	Indicated whether an HTTP 404 error has occurred. Setting this property to True$ will cause an HTTP404 error to be returned to the client.
PENDING	Get/Set	Indicates whether there is a pending response to send back to the client. Setting this property to True$ will return the RESPONSE content back to the client immediately. The current request will continue to process normally, however the request will not be returned a second time. This property is useful to allow selects or other long processes to continue while informing the browser of the progress. For example, suppose a user request requires creation of a report that generally takes 30 minutes to calculate the data. The initial request to initiate the report will create a record indicating the current status of the report. The request will then set the PENDING property to True$ and return back a self-reloading document. The returned document will run a different request which checks on the status record of the report, returning back another instance of itself. While this is happening, the initial request process is busy calculating the report and updating the status record with any required information. This will allow the report to continually check on the status and report on the progress being made. When the report is finished, the second request process will send back the actual report.
REASON	Get/Set	The status code reason - eg OK, File Not Found etc
RESPONSEDIR	Get/Set	The response folder that has been specified for returning HTTP responses to the server. This property changes the output location for the response for the S/WEB server only. It does not change the response location the web server looks at. This value should always be the same location stored in the SWEB.INI file at the operating system level. If you change this value, the web server will be unable to find the response document and client requests will continually time-out.
SENT	Get	True$ if the response has been sent.
SERVER	Get/Set	The server information that pertains to the supplier of the current Request. This field represents the server process name that is returned back with the request.
STATUS	Get/Set	The HTTP Status code of the response, eg.. 200 ,201, 404, 500 etc
SWAPLIST	Get/Set	The Swap List used by the SWAP embedded processor command.
TITLE	Get/Set	The title of the HTTP response
TYPE	Get/Set	The type of data contained in requestContent@. Should be in the format Type/SubType..eg text/html. HTTP data can be returned in many types and formats. Perhaps the most standard is HTML, which has a type of "text/html". Any frequent web-surfer has seen "HTML" pages that contain images, music, java applets, word processing documents, flash programs, Adobe Acrobat documents and hosts of others. Any valid format can be returned back from S/WEB in an individual response, provided the sum total of the response is less then 4 megabytes in size.
VERSION	Get/Set	The version associated with the Content of the HTTP response message. This field is used to return the HTML version used back to the client browser. This value defaults to 4.0. If for any reason you wish to inform the browser you are using a different HTML version, you must set this property, otherwise it can be left as is.
XVERSION	Get	The current S/Web version

Methods:

call www_Exec_Method( "RESPONSE", method, param1, param2, param3, param4, param5, errorText)

Method	Description
CLEAR	Used to clear the RESPONSE content and optionally the RESPONSE header.
CREATE	This method creates a new response object
DESTROY
GET	This method retrieves properties of the response object
GETCONTENT	Retrieves contents of the response already submitted for return to the client.
GETCOOKIE	Returns a specific cookie
GETHEADER	Returns a specific custom header
SEND	This method returns the response back to the client
SET	This method sets properties of the response object
SETCOOKIE	This method sets a specific cookie name and value or updates an existing cookie.
SETCONTENT	This method updates the content to be returned to the client browser.
SETHEADER	This method sets or updates a specific custom header.

[top]

CLEAR method

This method clears the response content and optionally the response header.

Argument	Description
param1	TRUE$ to clear response header.
param2	Not used.
param3	Not used.
param4	Not used.
param5	Not used.
param6	Not used.

Example:

declare function www_Exec_Method, www_Get_Status, www_Set_Status
$insert www_Status_Equates
$insert logical
......
PurgeDisk = True$
www_Exec_Method( "RESPONSE", "CLEAR", "", "", "", "", "", ErrorText)

[top]

CREATE method

This method creates a new response object. The developer does not need to call this method.

Argument	Description
param1	Not used
param2	Not used.
param3	Not used.
param4	Not used.
param5	Not used.
param6	Not used.

[top]

DESTROY Method

This method clears the content and header of the response object.

Argument	Description
param1	Not used
param2	Not used.
param3	Not used.
param4	Not used.
param5	Not used.
param6	Not used.

[top]

GET method

This method retrieves properties of the response object. Multiple properties may be retrieved by @Rm delimiting the Properties variable.

Argument	Description
param1	Properties to retrieve. May be @Rm delimited.
param2	Returns an @Rm delimited set of property values.
param3	Not used.
param4	Not used.
param5	Not used.
param6	Not used.

Example:

     declare function www_Exec_Method, www_Get_Status, www_Set_Status
   $insert www_Status_Equates
   $insert logical
   Properties =   "LENGTH"
   if www_Exec_Method( "RESPONSE", "GET", Properties, RetVals, "", "", "", "", errorText ) then
      Length    = Field( RetVals, @RM, 1 )
      If ( Length > 2000 ) Then
          * Request is too large for WAP....send back now!
          Call www_Exec_Method( "RESPONSE", "SET", "PENDING" )
          * Finish processing
      End
   end else
      abort = TRUE$
   end

[top]

GETCONTENT method

Retrieves contents of the request already submitted for return to the client.

Argument	Description
param1	HTTP data in specified section returned
param2	Section number of data to return.
param3	Not used.
param4	Not used.
param5	Not used.
param6	Not used.

Example:

   declare function www_Exec_Method, www_Get_Status, www_Set_Status
   $insert www_Status_Equates
   $insert logical
   SectionNbr   =   2
   HTTPData     =   ""
   if www_Exec_Method( "RESPONSE", "GETCONTENT", HTTPData, SectionNbr, "", "", "", "", errorText ) then
      * Contents of section 2 is now in HTTPData
      * Continue processing as you see fit
   end else
      abort = TRUE$
   end

[top]

GETCOOKIE method

Returns a specific cookie

Argument	Description
param1	Cookie Name
param2	Cookie data @Fm delimited
param3	Not used.
param4	Not used.
param5	Not used.
param6	Not used.

Example:

   declare function www_Exec_Method, www_Get_Status, www_Set_Status
   $insert www_Status_Equates
   $insert logical
   CookieName   =   "ZZ_USER"
   CookieData   =   ""
   if www_Exec_Method( "RESPONSE", "GETCOOKIE", CookieName, CookieData, "", "", "", "", errorText ) then
       UserName   =   CookieData< HTTP_RESPONSE_COOKIE_VALUE$ >
       UserName   =   Iconv( UserName, "HEX" )
       UserName   =   Invert( UserName )
       * Continue processing...
   end else
      abort = TRUE$
   end

[top]

GETHEADER method

Returns a specific custom header

Argument	Description
param1	Custom header name
param2	Custom header data returned @Fm delimited.
param3	Not used.
param4	Not used.
param5	Not used.
param6	Not used.

Example:

   declare function www_Exec_Method, www_Get_Status, www_Set_Status
   $insert www_Status_Equates
   $insert logical
   CustomHeaderName =   "ZZ_HEADER"
   CustomHeaderData =   ""
   if www_Exec_Method( "RESPONSE", "GETHEADER", CustomHeaderName, CustomHeaderData, "", "", "", "", errorText ) then
       * Custom header is now in CustomHeaderData
       * Continue processing...
   end else
      abort = TRUE$
   end

[top]

SEND method

This method returns the response back to the client.

Argument	Description
param1	Not used
param2	Not used.
param3	Not used.
param4	Not used.
param5	Not used.
param6	Not used.

Example

   declare function www_Exec_Method, www_Get_Status, www_Set_Status
   $insert www_Status_Equates
   $insert logical
   if www_Exec_Method( "RESPONSE", "SEND", "", "", "", "", "", "", errorText ) then
       * The request is now back on it's way to the client.
       * We can continue processing information, if we wish, however,
       * there is no direct way to return it to the client.
       * Continue processing...
   end else
      abort = TRUE$
   end

[top]

SET method

This method sets properties of the response object. Each parameter is @RM delimited

Argument	Description
param1	Name of the new property to set
param2	New data to use for the property
param3	The current property value is returned here.
param4	Not used.
param5	Not used.
param6	Not used.

Example:

   declare function www_Exec_Method, www_Get_Status, www_Set_Status
   $insert www_Status_Equates
   $insert logical
   Properties   =   "TITLE"
   NewValues    =   "A redirection page"
   Properties   := @RM : "LOCATION"
   NewValues    := @RM : "http://www.sprezzatura.com"
   PrevValues   =   ""
   if www_Exec_Method( "RESPONSE", "SET", Properties, NewValues, OldValues, "", "", "", errorText ) then
       * This document will have a title of "A redirection page" and
       * will send the user to the Sprezzatura home page
       * Continue processing...
   end else
      abort = TRUE$
   end

[top]

SETCOOKIE method

This method sets a specific cookie name and value or updates an existing cookie. See WWW_Response_Equates for the cookie data layout.

Argument	Description
param1	Cookie data to set
param2	Original cookie data, if any, is returned here.
param3	Not used.
param4	Not used.
param5	Not used.
param6	Not used.

Example:

   declare function www_Exec_Method, www_Get_Status, www_Set_Status
   $insert www_Status_Equates
   $insert logical
   UserName     =   Invert( UserName )
   UserName     =   Oconv( UserName, "HEX" )
   CookieData   =   ""
   CookieData< HTTP_RESPONSE_COOKIE_NAME$ > = "ZZ_USER"
   CookieData< HTTP_RESPONSE_COOKIE_VALUE$ > = UserName
   OrigCookieData = ""
   if www_Exec_Method( "RESPONSE", "SETCOOKIE", CookieData, OrigCookieData, "", "", "", "", errorText ) then
       * Continue processing...
   end else
      abort = TRUE$
   end

[top]

SETCONTENT method

This method updates the content to be returned to the client browser.

Argument	Description
param1	Content to store in content buffers
param2	Section to place the content in. A "+" tells the system to append the data to the end of the content buffer. This is the default action.
param3	Current data stored in specified buffer is returned.
param4	Not used.
param5	Not used.
param6	Not used.

Example:

   declare function www_Exec_Method, www_Get_Status, www_Set_Status
   $insert www_Status_Equates
   $insert logical
   * Place the REV_CONV_LIBRARY and REV_STRING_LIBRARY into the buffer for use with the document
   reposType = "JS"
   DocID     = "REV_STRING_LIBRARY"
   GoSub AddJS
   DocID     = "REV_CONV_LIBRARY"
   GoSub AddJS
   * Content document now contains the two libraries.
   Return
   AddJS:
   loop
      www_Exec_Method( "REPOSITORY", "ACCESS", reposType, docID, reposEntity, reposRec, bufferInfo, True$ )
      if www_Get_Status( errorText ) then
         abort = TRUE$
      end else
         call www_Exec_Method( "RESPONSE", "SETCONTENT", docBuffer, "+" )
         docBufferNo += 1
         if ( docBufferNo > docBufferCount ) then
            eofDocument = TRUE$
         end
      end
    until ( bufferInfo<1> = bufferInfo<2> or abort )
    repeat
    Return

[top]

SETHEADER method

This method sets or updates a specific custom header.

Argument	Description
param1	Custom header data @Fm delimited
param2	Existing custom header data
param3	Not used.
param4	Not used.
param5	Not used.
param6	Not used.

Example:

   declare function www_Exec_Method, www_Get_Status, www_Set_Status
   $insert www_Status_Equates
   $insert logical
   CustomHeader =   "Pragma" : @Fm : "NoCache"
   if www_Exec_Method( "RESPONSE", "SETHEADER", CustomHeader, CustomHeaderData, "", "", "", "", errorText ) then
       * Custom header is now in CustomHeaderData
       * Continue processing...
   end else
      abort = TRUE$
   end

[top]