Just as the Request object allows you to retrieve and manipulate
information sent by the client browser in its HTTP request, the
Response object gives you a great deal of control over the HTTP
response to the client. This control comes in three broad
categories:
Control over what data and data types are sent to the client in the
headers of the HTTP response
Control over what data and data types are sent to the client in the
body of the HTTP response
Control over when and how that data is sent
Control over the HTTP response
headers
includes setting cookies on the client machine, setting various
preexisting HTTP header values (such as the content type and
expiration information for a given page), and, finally, adding your
own custom headers to the HTTP response.
You control the HTTP response body directly through the Write and
BinaryWrite methods. As you might infer from the names, these methods
of the Response object allow you to write information directly to the
response body, which will be received by the client just like any
other information received in an HTML request response.
Finally, the Response object allows you to control how and when the
response is sent to the client. For example, using the properties and
methods involved in buffering the response, you can determine whether
to send the HTTP response as a single unit to the client or to send
the results of the request piecemeal. You can dynamically determine
whether the client is still connected to your web site. You can
redirect her request as though she requested something else. Finally,
you can use the Response object to write entries into the web server
log.
Buffer
Response.Buffer[=blnSetting]
The
Buffer
property determines whether the content created by your script is
delivered to the client browser as a whole or sent immediately to the
client browser as each line is created and entered into the HTML
stream. If set to True, then all scripts on the
page are run before the results of that script are sent to the client
browser.
The default value for the Buffer property is False
unless you set
ASPBufferingOn in the metabase (through a Windows
Scripting Host script or through the Microsoft Management Console for
your web site). If set in the metabase, the value there can be
overridden using the Buffer property on a page. For example, if you
set ASPBufferingOn to True, you
could later use the Buffer property to override this behavior and
force IIS not to buffer the page.
Parameters
blnSetting
Specifies whether the HTTP response that results from the web
server's processing of your script is buffered and then sent to
the client or sent to the client as it is created:
True
Causes the web server to buffer all results of your script until all
processing is complete or until the Flush or End method of the
Response object is invoked. Note that even if buffering is set to
True, if you call the End method, the contents of
the buffer are sent to the client and all subsequent results from the
processing of your script are not sent to the
client.
False
Instructs the web server to send information to the client as your
script is processed, instead of waiting until all processing is
complete. Note that if Buffer is set to False, any
call to the Clear, End, or Flush methods of the Response object will
result in a runtime error.
Example
Consider the following example. Note that we haven't set the
Buffer property of the Response object explicitly, so it's
False:
<%@ LANGUAGE="VBScript" %>
<HTML>
<%
CODE THAT RETRIEVES A FIELD VALUE FROM A DATABASE
%>
The response is not buffered before it is
sent to the requesting browser. For this reason, if the previous
database action results in an error, the user will see half a page
ending in an error notice. Now examine the second code example:
<%@ LANGUAGE="VBScript" %>
<%Response.Buffer = True %>
<HTML>
<%
On Error Resume Next
' CODE THAT RETRIEVES A FIELD VALUE FROM A DATABASE
If Err.Number <> 0 Then
Response.Clear
Response.Write "There has been an error. Here is the SQL"
Response.Write "statement that caused the problem: "
Response.Write strSQL
Response.End
End If
%>
In this second example, the response is buffered first and completed
before it is sent to the requesting browser. For this reason, we have
the opportunity to clear the buffer and place a simple error notice
in it that provides more information than does the unbuffered example
shown earlier. The code here doesn't provide much interaction,
but you get the idea.
If the response is not buffered, the client will receive the HTTP
response to its request as it is built—even if that building
results in errors.
Notes
The first thing to remember is that the Buffer property must be set
before the <HTML> tag is generated for the
HTTP response. Attempting to set the Buffer property after the
<HTML> tag will result in a runtime error.
If your script includes a preprocessing directive setting the
language for the page, for example, this directive must be placed
before you attempt to set the Buffer
property's value. If you attempt to set the language for the
page after setting the value for the Buffer property, you will
experience an error.
If the Buffer property is set to True and your
script does not call the Flush method anywhere, then the web server
will honor
Keep-Alive requests sent by the
client. Keep-Alive requests from the browser inform the server that
it should maintain a connection between itself and the client. If the
client's Keep-Alive request is honored on the server, it is not
forced to reestablish the connection each time it makes an HTTP
request. It is, in effect, already connected. This saves the client
from having to resolve the URL again.
If the Buffer property is set to False or if you
use the Flush method somewhere in your script, the server will be
forced to create a new connection to the client in response to each
request.
When should you buffer your scripts? The answer to this question
depends on two things: how long is too long for your clients to wait,
and how complex your scripts are.
If your clients are introductory-level users of the Internet, their
patience is typically fairly low; these clients need immediate action
upon clicking the Submit button in your forms. More experienced users
understand more about the back end of Internet applications and are,
perhaps, more understanding of lag times in script results.
More important than this is how important it is for you to present
the response as a single unit. For scripts that do a great deal of
iterative processing, where each loop is directly affected by the
loop before, it may be important to present the final result as a
single unit. However, if your script consists of several definable
sections, each of which is easily capable of being displayed on its
own, then buffering may be less important.
One strategy for dealing with the lag times for complex scripts whose
results are required in a single unit is to provide a
"please wait" page in some
form. This interim page informs the user that his request was
received and that the script is processing.
For example, suppose the client browser requests an ASP script that
retrieves and formats data from a very complex query requiring a long
load time (30 seconds, for example). Rather than forcing the client
to click on a link and have nothing happen for 30 seconds (in which
time the inexperienced web user might very well click on the same
link or button repeatedly), you might first display a page like the
following:
<HTML>
<HEAD><TITLE>Please Wait</TITLE></HEAD>
<BODY LANGUAGE = "VBScript" OnLoad = "WinLoad( )">
Your request is being processed, please wait...
<SCRIPT LANGUAGE = "VBScript">
Sub WinLoad( )
Parent.Location.HREF = "/Reports/Longreport.asp"
End Sub
</SCRIPT>
</BODY>
</HTML>
The short page will take very little time to load, and when it does,
the user will see a "please wait" message until the next
script has been processed and the report is ready for viewing, at
which time the "please wait" page is unloaded and the
report is loaded.
Finally, if you find that most of your scripts require buffering, you
might consider setting the metabase ASPBufferingOn
(using the App Options Configuration page for your virtual directory;
see Appendix D ) so that all scripts are buffered
by default.
CacheControl
Response.CacheControl[=ProxyCacheControlSetting]
The
CacheControl allows you to set whether
proxy servers serving your pages can cache your page. If your
page's content is large and doesn't change often, you
might want to allow proxy servers to cache the page and thus serve it
faster to requesting client browsers.
Parameters
ProxyCacheControlSetting
Determines whether proxy servers used to access your web site can
cache your pages. The default for this property is
Private, indicating that the proxy servers cannot
cache your page. If this value is Public, however,
proxy servers can cache the page. Note that
Private and Public are string
values.
Example
Setting this property is a simple affair, as the following code
demonstrates. You may be asking yourself if there is any way to
determine if the client is accessing the web page through a proxy
server. Although there is, if you know ahead of time of the existence
of the possible proxy servers, this is problematic and cumbersome.
Furthermore, there is no need to determine this before setting this
property. Either the client request is being handled by a proxy
server and this property will affect the caching of the page, or this
property is completely ignored.
<%
' The following code sets the HTTP cache control header so
' that this page can be cached by the proxy servers being
' used to access the page.
Response.CacheControl = "Public"
%>
<HTML>
<%
' Note that the CacheControl property was set BEFORE the
' <HTML> tag was constructed.
%>
Notes
Clearly, if the proxy server can cache your page, then the
client's access times when accessing the page though a proxy
server will be decreased. However, this is less useful if the page
changes frequently. Also note that just because you set the value of
the CacheControl property to Public, the proxy
server is not required to cache your page(s). This must be configured
on the proxy server.
Setting a value for CacheControl alters the value in the cache
control HTTP header sent to the client upon a request.
If you use this property, you must do so before sending any response
to the client (i.e., before the
<HTML> tag is generated for your page). If
you attempt to set the value for this (or any other HTTP header)
after the <HTML> tag has already been sent
to the client, an error will result unless the response is buffered.
Keep in mind that setting this property does not guarantee caching on
the proxy server. The proxy server itself must be configured to cache
these pages before this property will have any effect.
Charset
Response.Charset(strCharsetName)
The
Charset allows you to specify a character
set for the HTTP response content. The name of this character set is
added to the end of the Content-Type header/value pair in the HTTP
response headers.
Parameters
strCharsetName
The strCharsetName is a string
corresponding to a character set. The default character set is
ISO-LATIN-1.
Example
If you do not set the Charset property, the Content-Type HTTP
response header looks like the following:
content-type:text/html
If you set the Charset property, as in the following line of code:
<%
Response.Charset("ISO-LATIN-7")
%>
the value you use to set the Charset property value (the string
"ISO-LATIN-7" in the preceding code) is appended to the
end of the Content-Type HTTP response header value:
content-type:text/html;charset=ISO-LATIN-7
Notes
Although Charset is referred to in both this book and the Microsoft
documentation as a property, it is really a method that takes a
string argument representing the name of the charset to be added to
the end of the Content-Type HTTP response header. For this reason, if
you attempt to set the value of the Charset "property" as
you would any other Response object property, you will receive an
error:
<%
' Next line will NOT work:
Response.Charset = "ISO-LATIN-7"
%>
If the value you set for the Charset property does not represent a
valid character set, this value is ignored by the client's
browser, and the default character set is used instead.
Note that you can append the name of only one character set to the
end of the Content-Type header/value pair. Each subsequent change of
the Charset property's value simply replaces the last setting.
For example, the following code:
results in the following Content-Type HTTP response header/value pair:
content-type:text/html;charset=ISO-LATIN-3
Also note that if your content type is exclusively nontext (image
data, for example), the character set value is ignored by the
browser.
Finally, the default character set for the Apple Macintosh and
compatibles is not ISO-LATIN-1, as it is for IBM PCs and compatibles.
If you do not set the Charset property, all
Macintosh browsers will interpret requested
pages to be in the Macintosh character set. Microsoft's
Personal Web Server for Macintosh automatically converts the
character set of the requested content to ISO-LATIN-1 and will ignore
any other Charset property settings you provide in your script.
Like other properties that result in a change to the HTTP response
header values, the Charset property must be set before the server
sends the <HTML> tag to the client unless
the response is buffered.
ContentType
Response.ContentType[=strContentType]
The ContentType allows you to set the
value for the Content-Type setting in the HTTP response header. This
value defines the type of data being sent in the Response body. The
client browser uses this information to determine how to interpret
downloaded HTTP response content.
Parameters
strContentType
Represents the content type. This string is in a type/subtype format.
The type portion of the value represents the general content category
and the subtype represents the specific type of content.
Example
<%
' The following code sets the value of the Content-Type
' HTTP response header according to the value of a
' local variable.
If strData = "jpg" Then
Response.ContentType = "image/JPEG"
Else
Response.ContentType = "text/plain"
End If
%>
Notes
Some of the possible values for ContentType type/subtype pairs are
listed in Table 8.1.
Available Content-Type HTTP Header Values
Type
SubType
Description
Text
Plain, RichText
Textual information
Multipart
Mixed, Alternative, Parallel, Digest
Data in response consists of multiple parts of independent data
Message
Partial, External-body
An encapsulated message
Image
JPEG, GIF
Image data
Audio
Basic
Audio data
Video
MPEG
Video data
Application
ODA, PostScript, Active
Typically uninterpreted binary data or data to be processed by a
mail-based application
The number of subtypes is expected to grow significantly over time.
The best reference for the available subtypes is the latest MIME RFC
(RFC 2231 as of this writing). Many of the new subtypes are expected
to come from industry. For example, Microsoft has already added the
x-cdf subtype to the application type for its
Channel Definition Format.
Like other properties that result in a change to the HTTP response
header values, the ContentType property must be set before the server
sends the <HTML> tag to the client unless
the response is buffered.
As another example of the ContentType property, see the code example
for the Response object's BinaryWrite method later in this
chapter.
Expires
Response.Expires[=intNumMinutes]
The
Expires property specifies the length of
time (in minutes) that the client machine will cache the current
page. If the user returns to the page within the amount of time set
for the Expires property, the user will view the cached version of
the page. If the Expires property is not set, content expiration set
for the virtual directory (through the Properties page for the
virtual directory on the Microsoft Management Console) will be used.
Its default is 24 hours.
Parameters
intNumMinutes
The number of minutes you wish the client's browser to cache
the current page
Notes
If you wish to prevent the client's browser from caching the
page, use a value of
for intNumMinutes. Doing so will force the
client to rerequest the page from the web server every time the
client navigates to the page.
If you attempt to set the Expires property more than once in a
script, the shortest setting is used. For example, the page that
includes the following script will result in the client caching the
page for five minutes, even though the last setting of the Expires
property is 20 minutes:
Like other properties that result in a change to the HTTP response
header values, the Expires property must be set before the server
sends the <HTML> tag to the client unless
the response is buffered.
ExpiresAbsolute
Response.ExpiresAbsolute[=[Date] [Time] ]
Specifies a date and time on which
the content of the current page will cease being cached on the client
machine. If no time is specified when setting the ExpiresAbsolute
property, the time is taken to be midnight on the date specified.
Before the date specified in the ExpiresAbsolute property, the client
will display the cached version of the current page if the user
navigates to it.
Parameters
Date
A calendar date after which the current page will no longer remain
cached. The date value you use should be in the standard
month/day/year format. However, the value sent in the Response header
will conform in format to the RFC 1123 date format.
Time
Specifies the exact time on Date after
which the current page will no longer be cached on the user machine.
If no date is specified, the client browser will expire the page at
midnight of the current day. The web server converts the time you use
to GMT before sending this header to the client.
Example
<%
' The following code sets the current page's caching on the
' client machine to end at 9 P.M. on 7 May 1998 GMT. NOTE
' the use of the "#" to designate the date and time.
Response.ExpiresAbsolute=#May 7, 1998 21:00:00#
%>
Notes
As the example demonstrates, you must use the pound character (#) to
designate the date and time used in the ExpiresAbsolute property
value.
Like the Expires property, setting this property multiple times
results in the current page's caching ending on the earliest
date and time specified in the script.
Like other properties that result in a change to the HTTP response
header values, the ExpiresAbsolute property must be set before the
server sends the <HTML> tag to the client
unless the response is buffered.
IsClientConnected
Response.IsClientConnected
A read-only property that evaluates to True if the
client is still connected to the web server since the last use of the
Response object's Write method and returns
False otherwise.
Parameters
None
Example
<%
' The following code determines whether the client
' is still connected to the server. If it is still
' connected, then the SessionID (see Chapter 10) will be
' used to retrieve the user information from a database.
If Response.IsClientConnected Then
strUserName = fn_strGetUserName(Session.SessionId)
End If
%>
Notes
The IsClientConnected property gives you the ability to determine
whether the client has disconnected. This is very important if the
current script is long. If the client is no longer connected, it may
be important to discontinue processing a script.
The following example demonstrates checking for the client connection
before continuing in a long script. If the client is no longer
connected, the easiest way to stop all processing is to use the
Response object's End method.
<%Response.Buffer = True%>
<HTML>
<HEAD><TITLE>One Long Script</TITLE></HEAD>
<BODY>
<%
' The following code is the first of two segments
' in this script that will take a long time to process:
[SOME LONG CODE]
' Now before performing the second half of this long script,
' check to see if the client is still connected.
If Response.IsClientConnected Then
[SECOND LONG CODE SEGMENT]
Else
' The client is no longer connected, end the script's
' processing.
Response.End
End If
%>
</BODY></HTML>
This property is useful only for those clients using HTTP 1.1. If the
browser uses HTTP 1.0, IIS tracks the session using individual HTTP
requests and Keep-Alive requests by the client, not a constant
connection that is only consistent with the later (1.1+) version of
HTTP.
If your ASP file in which you use IsClientConnected is running under
IIS 4.0, then the property value is only accurate if the file sends
content to the client (i.e., if it is a file containing only
server-side code, the resulting value of IsClientConnected is not
correct). However, in IIS 5.0, IsClientConnected works regardless of
whether or not the current file sends content to the client.
PICS
Response.PICS(strPICSLabel)
Adds a
PICS (Platform for Internet Content
Selection) label to the HTTP response header. This PICS system labels
your web content to enable rating services (such as the Recreational
Software Advisory Council (RSAC) and SafeSurf, a parents'
organization) to rate that content according to various criteria set
by content control software such as NetNanny and CyberWatch.
Parameters
strPICSLabel
A string value that contains the entire contents of the PICS label
you wish to add. A PICS label consists of the following parts:
The URL of the rating service that produced the label.
The set of PICS-defined (and extensible) attribute/value pairs that
contains information about the rating of the content itself, such as
the date it was assigned and an expiration date for the rating.
A set of attribute/value pairs designed by the rating service that
represents the rating given the content. For example, the RSAC has
four attributes for which they rate software: violence, sexual
content, language, and nudity. These four attributes and their
corresponding values would appear similar to the following: (V 0
S 1 L 3 N 0).
Example
<%
' The following piece of code sets a PICS label for the
' content of this page corresponding to the rating discussed
' earlier.
Dim strPicsLabel
strPicsLabel = _
"(PICS-1.1 <HTTP://www.rsac.org/ratingsv01.html> "
strPicsLabel = strPicsLabel & "labels on " & Chr(34)
strPicsLabel = strPicsLabel & "2000.07.20T06:00-0000" & _
Chr(34)
strPicsLabel = strPicsLabel & " until " & Chr(34)
strPicsLabel = strPicsLabel & "2000.12.31T23:59-0000" & _
Chr(34)
strPicsLabel = strPicsLabel & "ratings (V 0 S 1 L 3 N 0))"
Response.PICS(strPicsLabel)
%>
Notes
The PICS label in the example states that:
The PICS draft used is 1.1.
The rating service is RSAC.
The URL for the rating service is http://www.rsac.org/ratingsv01.html.
The content label is to go into effect at 6 A.M. GMT 7/20/2000.
The content label expires at 11:59 P.M. GMT on 12/31/2000.
In the content label, the violence level is 0, the sexual content
level is 1, the adult language level is 3, and the nudity level is 0.
The actual PICS label that is added to the HTTP response header is
the following:
PICS-label:(PICS-1.1 http://www.rsac.org/ratingsv01.html
labels on "1998.03.20T06:00-0000" until
"1999.12.31T023:59-0000" ratings (v 0 s 1 l 3 n 0))
If you attempt to add an invalid PICS label to the HTTP header, the
client machine will ignore it. Note that each subsequent setting of
the PICS property value overwrites the last value. Only the final
setting is actually sent to the client machine.
Note also that the dates in the PICS label are in quotation marks.
For this reason you must use the Chr(34) character
(34 is the ASCII equivalent to the quotation mark). This is easiest
to handle by simply typing out the label as it should appear in the
final PICS label and then replacing each quotation mark in the line
of code with the following:
" & Chr(34) & "
Like other properties that result in a change to the HTTP response
header values, adding a PICS label must be done before the server
sends the <HTML> tag to the client unless
the response is buffered.
Status
Response.Status(strStatusDescSetting)
Specifies the HTTP status line that is
returned to the client machine from the web server.
Parameters
strStatusDescSetting
The strStatusDescSetting is a string value
containing a three-digit status code that indicates the status of the
HTTP request and a short explanation of the status code.
The possible values of the
strStatusDescSetting parameter are
described in the current HTTP specification and fall into the following high-level categories:
The
latest version of the HTTP specification can be found at http://www.w3c.org/protocols.
1xx
The 100 range is set aside for sending information-only response
statuses to the client.
2xx
The 200 range is set aside for sending successful response statuses
to the client.
3xx
The 300 range is set aside for redirection of the client. This status
range should be used for requested pages that have been moved
temporarily or permanently.
4xx
The 400 range is set aside for sending
notices of client error to the client. For example, you have
undoubtedly seen the 404NotFound error status sent back to your browser when
you attempt to navigate to a page that has been moved or that does
not exist.
5xx
The 500 range is set aside for sending notices of
server error to the client.
For example, attempts to reach pages on a server that is unable to
handle the request due to temporary overloading or server maintenance
could result in the response status 503
Service Not Available.
Example
<%
' The following code sets the Status property of the
' Response object to 404 Not Found. Unless other content is
' generated for the page, the status code will be
' interpreted by itself by the client.
strStatusText = _
"404 Not Found The Web server cannot find the "
strStatusText = strStatusText & "file or script you asked "
strStatusText = strStatusText & "for. Please check the URL "
strStatusText = strStatusText & "to ensure that the path "
strStatusText = strStatusText & "is correct."
Response.Status = strStatusText
%>
Notes
As with setting other Response headers, each subsequent setting of
the Status property value resets the last setting.
Like other properties that result in a change to the HTTP response
header values, the Status property must be set before the server
sends the <HTML> tag to the client unless
the response is buffered.
The
Cookies
collection of the Response object enables your ASP application to use
the Set-Cookie HTTP response header to write
cookies to the client's machine. If you attempt to set the
value of a cookie that does not yet exist, it is created. If it
already exists, the new value you set overwrites the old value
already written to the client machine.
As with the Cookies collection of the Request object, each cookie in
the Cookies collection of the Response object can also represent a
cookie dictionary. Recall from Chapter 7, that a cookie dictionary is a construct that
is similar to an associative array in that each element of the array
is identifiable by its name. For more information on cookie
dictionaries, see the section on the Cookies collection of the
Request object in Chapter 7.
The Cookies collection of the Response object, like other ASP
collections, has the following properties:
Item
Returns the value of a
specific element in the collection. To specify an item, you can use
an index number or a key.
Key
Returns the name of a specific element
in the Cookies collection. Just as each element's value is
represented by the Item property, so each element's name is
represented by its Key property.
If you do not know the name of a specific key, you can obtain it
using its ordinal reference. For example, assume that you want to
learn the key name for the third element in the collection and,
subsequently, that element's value. You could use the following
code:
If, on the other hand, you know that the third element's key
name is COLOR_PREF, you could simply use the
following code to retrieve the value of that element:
strKeyValue = Response.Cookies.Item("COLOR_PREF")
Count
The Count property of
the Cookies collection represents the current number of cookies in
the collection.
As with other ASP collections, you can retrieve the value of any
field of the Cookies collection through the use of the Item property.
However, as in other places in this book, in the following examples,
the syntax has been abbreviated so that it does not explicitly show
the use of the Item property. For example:
Response.Cookies("UserPref") = "Red"
is an abbreviated form of:
Response.Cookies.Item("UserPref") = "Red"
To set the value of a cookie, you would use code similar to the
following:
Response.Cookies("LastSearch") = _
"SELECT * FROM Details WHERE Color = 'Red'"
For more information on the Item, Key, and Count properties of a
collection, see the discussion in Section 4.2 in Chapter 4.
The previous code would create the cookie UserPref
if it doesn't already exist (or overwrite the original value if
it does). This cookie would translate into a
SET-COOKIE response header being added to the
response sent back to the client browser. The client browser would
receive this response header and create (or overwrite) a
UserPref cookie on the user machine.
Each element in the Cookies collection (or subkey, if the cookie is a
cookie dictionary) also has the following cookie-specific attributes:
Domain
Sets the cookie so that
the client sends the cookie's value only to pages in the domain
set in the Domain property. The Domain property is write-only. For
example, suppose we wanted to add the domain "mycorp.com"
to the following LastSearch cookie. This would
cause the client to send this cookie's value to the mycorp.com domain when it requests pages from
it:
The date on which the cookie expires and
is discarded on the client machine. For example, suppose we want the
cookie to expire on January 29, 2000. We could use the following
code:
If you do not set the Expires property value, the cookie resides on
the client machine for the duration of the client's session.
The cookie also will reside on the client machine only for the
duration of the client's session if the date value you set for
the Expires property is earlier than the current date. The Expires
property is write-only.
HasKeys
As previously mentioned, a cookie in
the Cookies collection also can represent a cookie dictionary. To
determine whether a specific cookie has subkeys, you must use the
HasKeys property of that cookie, as in the following:
blnHasKeys = Response.Cookies("Colors").HasKeys
If blnHasKeys Then
strColor3 = Response.Cookies("Colors")("color3")
End If
The HasKeys property is read-only.
Path
The Path property
represents the virtual directory on the server to which the cookie
will be sent by the client browser when the client browser requests a
page from within that virtual path. For example, if we want the
client to send this cookie to only those scripts in the
/Apps/SearchApps virtual directory, we'd
use the following line of code:
If the cookie's Path attribute is not set, the path defaults to
the path of the current ASP application. The Path property is
write-only.
Secure
The
Secure property allows you to
specify whether the cookie is sent from the client only if the client
is using the Secure Sockets Layer. For example, suppose we have
stored some sensitive information in a cookie (this is not wise, but
there are occasions when you might do so), and you want the
user's browser to send this information only if it is using the
Secure Sockets Layer. This will significantly decrease the
probability that a sensitive cookie could be intercepted. You would
use the following simple line of code:
Response.Cookies("SensitiveCookie").Secure = True
The Secure property takes a Boolean value. The Secure property is
write-only.
Example
The following is a more complete example of the use of the Cookies
collection of the Response object. It demonstrates many of the items
discussed earlier.
<HTML>
<HEAD><TITLE>Search Cookie Example</TITLE></HEAD>
<BODY>
<H3>Welcome to the Search Results Options Page.</H3>
You can use the following form to select your search results display
options.
These options will be saved on your machine as a set of cookies.
<FORM ACTION="/SaveSearchCookie.asp" METHOD = POST>
First Name:<INPUT TYPE = TEXT NAME = "txtFirstName"><BR>
Last Name:<INPUT TYPE = TEXT NAME = "txtLastName"><BR>
User ID:<INPUT TYPE = TEXT NAME = "txtUserId"><BR>
Check All that Apply:
Show Descriptions:
<INPUT TYPE = CHECKBOX NAME = "chkUserPrefs"VALUE = "Desc">
Show Hit Count (display how many matches found per result):
<INPUT TYPE = CHECKBOX NAME = "chkUserPrefs"VALUE = "Count">
Show Relevance with Graph:
<INPUT TYPE = CHECKBOX NAME = "chkUserPrefs"
VALUE = "Graph">
Use Small Fonts(will show more results per page):
<INPUT TYPE = CHECKBOX NAME = "chkUserPrefs"
VALUE = "Small">
<INPUT TYPE = SUBMIT VALUE = "Save Selections">
</FORM>
</BODY>
</HTML>
The following code (SaveSearchCookie.ASP) will
retrieve the values selected in the previous form and save them to
the user's machine as cookies:
<%
' The following code retrieves user information from the
' Form collection of the Request object (see Chapter 7) and
' then writes the information to a set of cookies on the
' client machine.
Dim strFirstName
Dim strLastName
Dim strUserId
Dim intCounter
Dim intPrefCounter
Dim strKeyName
Dim arstrUserPrefs( )
' Retrieve user information...
strFirstName = Request.Form("txtFirstName")
strLastName = Request.Form("txtLastName")
strUserId = Request.Form("txtUserId")
intPrefCounter = 1
For intCounter = 1 to Request.Form("chkUserPrefs").Count
ReDim Preserve arstrUserPrefs(intPrefCounter)
arstrUserPrefs(intPrefCounter - 1) = _
Request.Form("chkUserPrefs")(intCounter)
intPrefCounter = intPrefCounter + 1
Next
' Write the user information to the client machine.
' Save all the information in cookies, but set the
' Expires property only for the UserId. We'll want
' that to remain on the client machine after the session
' is complete.
Response.Cookies("UserFirstName") = strFirstName
Response.Cookies("UserLastName") = strLastName
For intCounter = 1 to intPrefCounter - 1
strKeyName = "Pref" & CStr(intCounter)
Response.Cookies("UserPrefs")(strKeyName) = _
arstrUserPrefs(intCounter - 1)
Next
' Note in the first line below, that when no property
' is specified, the value of the cookie is set.
Response.Cookies("UserId") = strUserId
Response.Cookies("UserId").Expires = #December 31, 1999#
Response.Cookies("UserId").Domain = "www.customsearch.com"
Response.Cookies("UserId").Path = "/usersearch/"
Response.Cookies("UserId").Secure = True
%>
Notes
In the example, the UserFirstName cookie is sent to the client
machine. For this example, let's assume the value of the
strFirstName variable is the string
"David." The actual HTTP response header sent to the
client machine is:
Set-Cookie:USERFIRSTNAME=david
Also for this example, assume the three values sent are 800 (for
client browser width), 8 (for color depth in bits), and English (for
English language preference). The actual HTTP response header sent to
the client is the following:
If the string value sent for a value of a cookie contains spaces,
those spaces are replaced with plus signs (+) in the HTTP response
header.
If you sent a subsequent cookie value to the
UserPrefs cookie on the client machine without
specifying a SubKey, as in the following:
Response.Cookies("UserPrefs") = "german"
the two values for PREF1 and
PREF2 will be overwritten and the Count property
for the UserPrefs cookie will return 1.
Alternatively, if you send a subsequent cookie value and specify a
SubKey to a client machine where the
cookie has a value but no keys, the value already in place on the
client machine is overwritten.
If, while you are generating values for the Cookies collection of the
Response object, you need to determine if there are already subkeys
defined for a given cookie, you can evaluate the HasKeys property of
the cookie. If the cookie has subkeys defined, the HasKeys property
evaluates to True.
Like other properties that result in a change to the HTTP response
header values, the Cookies collection values must be set before the
server sends the <HTML> tag to the client
unless the response is buffered.
AddHeader
ClientCustomHeader:CustomHeaderValue
Allows you to add your own HTTP
response header with a corresponding value. If you add an HTTP header
with the same name as a previously added header, the second header
will be sent in addition to the first; adding the second header does
not overwrite the value of the first header with the same name. Also,
once the header has been added to the HTTP response, it cannot be
removed.
If the client sends the web server an HTTP header other than those
listed in the section on the ServerVariables collection in Chapter 7, you can use
HTTP_HeaderName to retrieve it. For
example, if the client sends the HTTP header:
ClientCustomHeader:CustomHeaderValue
then you could retrieve the value for this element using the
following syntax:
This is an advanced method and should not be used without careful
planning. If another method of the Response object will meet your
needs, use it instead of using the AddHeader method.
Parameters
strName
The name of the HTML header you wish to add to the response header
strValue
The initial value of the new header you are adding to the response
header
Example
<%
' The following code adds the CUSTOM-ERROR HTML header to
' the HTTP response headers.
Response.AddHeader "CUSTOM-ERROR", "Your browser is not IE."
%>
Notes
Like the other methods and properties of the Response object that
alter the HTTP response headers, you must call the AddHeader method
before sending the <HTML> tag to the client.
If you have previously set the Buffer property value of the Response
object to True, you can use AddHeader unless you
have previously called the Flush method. If you call AddHeader after
sending the <HTML> tag to the client or
calling the Flush method, your call to AddHeader will result in a
runtime error.
You should not use underscores in your custom headers. Doing so will
increase your chances of ambiguity with headers already present. Use
hyphens to separate multiple words instead. Also, note that to
retrieve the value of a custom header with hyphens, you replace them
with underscores when retrieving the values of your custom headers.
AppendToLog
Response.AppendToLogstrLogEntry
Adds a string to the web server log
entry for the current client request. You can only add up to 80
characters at a time, but you are able to call the AppendToLog method
multiple times.
Logging web site activity
IIS allows you to log user activity into a text file or into an
ODBC-compliant database. This logging is separate from Windows NT
logging, and the records in the IIS log cannot be viewed using the
Windows NT Event Viewer tool. To view the IIS log files, you must
open them as you would any other ASCII text file, import them into a
spreadsheet or database program, or, if you've been logging to
an ODBC database, view them through queries to that database.
The log files for IIS are found in
winnt\system32\LogFiles\W3svc1\ex[date].log.
Each entry into the (IIS default) log contains time, caller IP,
caller method (GET/POST), uri-stem (no server
path), and resulting status.
Specifically, you can log the following aspects of users'
visits to your web site, among other things:
Date/time of user visit
Requested pages
IP address of user
Length of time connected to server
Using this information and information your application adds to this
log through Response.AppendToLog, you can plan future development for
your site, plan security, and plan for new servers if the load
warrants it.
Parameters
strLogEntry
The string you want added to the current client request's entry
in the web server. This string can be up to 80 characters in length.
Note that the string you append to the web server log entry cannot
contain commas, since the fields in the IIS web log entries are comma
delimited.
Example
<%
' Assume you have constructed one string containing all that
' you'd like logged to the web's server. This string is
' declared as strOrigLogContent. The following Do...While
' loop code will loop through your content and log it to the
' web server 79 characters at a time.
Do While Len(strOrigLogContent) > 0
If Len(strOrigLogContent) >= 79 Then
strLogString = Left(strOrigLogContent, 79)
Else
strLogString = strOrigLogContent
End If
' Log the content.
Response.AppendToLog strLogString
If Len(strOrigLogContent) > Len(strLogString) Then
strOrigLogContent = _
Right(strOrigLogContent, _
Len(strOrigLogContent) - Len(strLogString))
Else
strOrigLogContent = "
End If
Loop
%>
Notes
Before you are able to append information to the web server log in
IIS, you must enable the URL Query option of the Extended Logging
Properties sheet for the web site whose activity the log files are
being used to record.
This method can be an invaluable time saver in maintaining detailed
information about actions on your web site. If you have a unique
identifier for each user that is stored in the log file with the
entry (which contains an IP address, possibly a Windows NT account
name, and the date and time of the visit), you can quickly determine
who was visiting the site at the time of an unexpected error on your
site. This method cannot be relied on for security, since you cannot
be 100% certain of the user's identity, but it can help.
BinaryWrite
Request.BinaryWritearbyteData
Writes
information directly to the response content without any character
conversion. If your application involves writing binary data to the
client, you must use this method to ensure that data you send is not
converted to character data from the original binary.
Parameters
arbyteData
An array of bytes you wish to write to the response content
Example
The following example code is lengthy for the simple call to
BinaryWrite, but it demonstrates a very useful concept, especially if
you are forced to deal with binary data from a database.
<%
' The following code retrieves a binary object
' (in this case a JPG image) and writes it to the
' client using BinaryWrite. (For more information
' on ActiveX Data Objects usage, see Chapter 12.)
' Create an ADO connection object.
Set adoCon = Server.CreateObject("ADODB.Connection")
' Use the Open method of the Connection object
' to open an ODBC connection with the database
' represented by the DSN ImageDatabase.
adoCon.Open "ImageDatabase"
' Use the Execute method of the ADO Connection object
' to retrieve the binary data field from the database.
Set adoRecImgData = adoCon.Execute _
("SELECT ImageData FROM Images WHERE ImageId = 1234")
' Create a Field object by setting one equal to a
' specific field in the recordset created previously.
Set adoFldImage = adoRecImgData("ImageData")
' Use the ActualSize property of Field object to retrieve
' the size of the data contained in the Field object. After
' this line you will know how many bytes of data reside in
' the Field object.
lngFieldDataLength = adoFldImage.ActualSize
' Use the BinaryWrite method to write 4K bytes of binary
' data at a time. So, first we need to determine how many
' 4K blocks the data in the Field object represents.
lngBlockCount = lngFieldDataLength / 4096
' Now let's get how many bytes are left over after removing
' lngBlockCount number of bytes.
lngRemainingData = lngFieldDataLength Mod 4096
' We now must set the HTTP content type Response header
' so that the browser will recognize the data being sent
' as being JPEG image data.
Response.ContentType = "image/JPEG"
' Loop through and write the first lngBlockCount number
' of binary blocks of data.
For intCounter = 1 to lngBlockCount
Response.BinaryWrite adoFldImage.GetChunk(4096)
Next
' Now write the last remainder of the binary data.
Response.BinaryWrite adoFldImage.GetChunk(lngRemainingData)
' Close the recordset.
adoRecImgData.Close
%>
Notes
At first, the BinaryWrite method seems to be of limited use, until
you have binary data stored in a database that must be sent to the
client; then, BinaryWrite is invaluable. As the code sample
demonstrates, one example of this is the display of image data that
is stored and retrieved from a DBMS capable of storing binary data.
I have used this method to display JPEG images stored in a Microsoft
SQL Server database (using code similar to the preceding), and it
works quite well. Because you are sending the HTTP response
containing only the image data (not a link request to the image), it
may even be faster than sending images to the client upon a straight
client request, assuming your database access is suitably
fast.
Clear
Response.Clear
Empties the
current
contents of the Response buffer. It does so without sending any of
the buffered response to the client.
Parameters
None
Example
<% Response.Buffer = True%>
<HTML>
<HEAD><TITLE>Response Clear Method Example</TITLE></HEAD>
<BODY>
<%
On Error Resume Next
[CODE TO DO SOME CALCULATIONS]
lngFormulaElement1 = 47
lngFormulaElement2 = lngFormulaElement1 - 47
lngFormulaElement3 = 23
' This next line results in a division-by-zero error
' (Error Number 11).
lngNewCalcTotal = lngFormulaElement3 / lngFormulaElement2
' This next line will still be processed because we used
' ON ERROR RESUME NEXT.
If Err <> 0 Then
' The following code clears the Response buffer, writes
' an error message, and ends the response, forcing IIS to
' send the response to the client. Note that the Buffer
' property has to be set to True for the following code
' to work properly.
Response.Clear
Response.Write "Your request resulted in the error: " & _
Err.Description
Response.Write " Error Number: " & Err.Number
Response.Write "<BR>Call your web admin at 555-HELP for "
Response.Write "more information."
Response.End
End If
%>
. . . [additional code]
Notes
The Clear method of the Response object does not clear any HTTP
headers, only the content. As noted in the example, the Buffer
property of the Response object must be set to
True or the use of this method will result in a
runtime error.
One of the most important uses for the
Clear method is to clear the buffer and send to the client browser
something else instead, often error information, as is the case with
the example.
For errors to be caught and error information to be sent to the
client in this fashion, not only must the Buffer property be set to
True, but also you must use the following line of
code to ensure that your error trap will be processed:
On Error Resume Next
End
Response.End
Ends
all storage of information in the response buffer and sends the
current contents of the buffer immediately to the client. Any code
present after the call to the End method is not processed. Any memory
set aside by the script up until the call to End (such as database
objects previously used in the script) is released.
Parameters
None
Example
See the previous example for the Clear method.
Notes
If the Buffer property is set to True, calling the
End method will flush the Response buffer exactly as if you had
called the Flush method (see the next section). However, unlike
calling the Flush method, no code after the call to End is processed
by the web server.
Flush
Response.Flush
Immediately sends all data currently in
the response buffer to the client. Unless the Buffer property of the
Response object is set to True, this method will
result in a runtime error. This method allows you to send various
portions of the response to the client at your discretion.
Parameters
None
Example
<% Response.Buffer = True%>
<HTML>
<HEAD><TITLE>Response Flush Method Example</TITLE></HEAD>
<BODY>
<%
' Suppose for this example that this first part of the
' script retrieves some information from a database and
' that retrieval takes a long time, say 30 seconds.
' (Don't worry about the details of the ActiveX Data Object
' calls. They are covered later in the book and serve only
' as an example here of something that might take a long time.)
Set adoCon = Server.CreateObject("ADODB.Connection")
adoCon.Open MyDatabase
Set adoRec = adoCon.Execute([BIG SQL STATEMENT])
' Rather than continue to the second part of the script, in
' which a second slow SQL statement (say another 15 seconds)
' executes, first we'll use the Flush method to force the
' first part of the script results to the client. This way,
' the user can be looking at the results of the first query
' while waiting for the second.
Response.Flush
' [Second LONG SQL statement.]
Set adoRec2 = adoCon.Execute([BIG SQL STATEMENT])
%>
</BODY></HTML>
Notes
Using the buffering capacity of the Response object, you are able to
send the response to the client in parts. For example, suppose you
are presenting a description of your worldwide organization followed
by a list of offices derived from information in a database. The
organization description is straight text, and thus it takes very
little time to prepare and send it to the client. The second part
takes more time. You could use the Flush method of the Response
object to send the organizational description to the client first and
then send the list when it is complete. Without this approach, the
user can get the impression that the page is slow to download.
One caution, however: if you use the Flush method on an Active Server
Page, the server will ignore Keep-Alive requests sent by the client
for that page. This will force a new connection to be made for each
piece of information sent to the client.
Redirect
Response.RedirectstrURL
Redirects the client's request
to another URL.
Parameters
strURL
The Universal Resource Locator string for the new location to which
you wish to redirect the client
Example
<%
' The following code determines whether the client has
' security clearance for a certain page. If not, it
' is redirected to another URL.
[...Code to determine user's clearance for the current page...]
If Not(strUserSecurity = "ADMIN" or strUserSecurity = "SUPERADMIN") Then
Response.Redirect "/security/noclearance.asp?usrid=09563"
End If
%>
Notes
The strURL value you use when calling the
Redirect method can be an exact URL with DNS or a virtual directory
and filename. It also can be the name of a file that resides in the
same folder as the requested page.
If your script has written any content to the HTTP response body,
that content is ignored by the script once the call to the Redirect
method is executed.
Calling the Redirect method is conceptually the same as setting the
Status property to "302 Object Moved" and sending the
user to a new location using the Location HTTP
header.
Note that upon redirection, some older (HTTP 1.0) client browsers
will mistakenly change POST requests to
GET requests when the new URL is called. This is
an important consideration when the client's
POSTed information contains more data than the
GET method can handle. It is assumed that new
browsers supporting the HTTP 1.1 protocol have fixed this problem.
If your ASP file is running under IIS 5.0, you should consider using
the Server method Execute or Transfer. Neither of these methods
involve the costly trip to the client and back to the server that
Redirect requires.
Write
Response.WritevntData
Writes information directly to the HTTP response body.
Parameters
vntData
The information to be inserted into the HTML text stream that will be
received by the client browser. This includes text, HTML tags,
client-side script, and so on. The data variables in the ASP script
itself are of the data type variant. The value cannot contain the
%> character sequence; the web server will
interpret it as the end of your active server script. If your script
requires this character sequence, use the escape sequence
%\> instead.
Example
<%
strDirCommand = "Dir /w"
' The following code writes an entire HTML table to the HTTP
' response body.
Response.Write "<TABLE>"
Response.Write "<TR>"
Response.Write "<TD WIDTH = 50%\>"
Response.Write "Command"
Response.Write "</TD>"
Response.Write "<TD WIDTH = 50%\>"
Response.Write "Description"
Response.Write "</TD>"
Response.Write "</TR>"
Response.Write "<TR>"
Response.Write "<TD WIDTH = 50%\>"
Response.Write Chr(34) & strDirCommand & Chr(34)
Response.Write "</TD>"
Response.Write "<TD WIDTH = 50%\>"
Response.Write "This allows you to see a list of the "
Response.Write "files in <BR> your current folder."
Response.Write "</TD>"
Response.Write "</TR>"
Response.Write "</TABLE>"
%>
Notes
As demonstrated in the example program, you can use the Write method
to write HTML and client-side script to the response body that the
client browser will interpret as plain HTML.
To send a carriage return/line feed or a quotation
mark, use the Chr function, as demonstrated the
following code:
' Note: Chr(34) is a quotation mark. Chr(13) & Chr(10) is
' the equivalent of a carriage return, followed by a
' linefeed.
Response.Write "Hamlet said, " & Chr(34) & _
"To be, or not to be." & Chr(34) & Chr(13) & Chr(10)
Finally, you can use the Write method to send the value of a
server-side script to the client browser. This method is sometimes
cleaner in your code than going back and forth between server-side
code and client code using the
<%=...%> notation. For
example, the following code displays the value of the
strHighestPrice data value using both the
<%=...%> and the
Response.Write methods:
%>
<%
Response.Write "The highest price is " & strHighestPrice
Response.Write ".<BR>"
' The same line as the preceding using the other format:
%>
The highest price is <%=strhighestPrice%>.<BR>