7.1.4- Request Object Collections

by NT Community Manager.
Last Updated by NT Community Manager.

Public Categorized as 07. The Request and Response Objects.

Not tagged.

7.1.5- Request Object Collection Shorthand >>

Request Object Collections

The Request object has five collections. We'll explain these in detail later in this chapter, but we will quickly introduce them here:

QueryString: When sending a request, the client can include name/value pairs of information within the URL, after the file name. This collection stores any values provided in the URL. For example, this is sent when the METHOD attribute of a FORM is set to GET and the ACTION attribute is set to the URL we wish to transfer to.
Form: If the client sends a Form request, and sets the METHOD attribute to POST then the values of the form elements are stored in this collection.
ServerVariables: The web server itself holds a great deal of information about the request, contained in HTTP server variables. This information is made available as a collection.
Cookies: If the client is accepting cookies from the server, it sends the information to the server and the server stores it in the Cookies collection. While being able to create and access cookies with the Request and Response objects is a major feature, we will ignore this collection in this chapter as it has a more logical home in the next chapter on applications, sessions, and keeping track of users.
ClientCertificate: A client certificate is a digital certificate exchanged between client and server to verify the identity of the user attempting to contact the server. If the client sends any security certificates to the server, then they are stored in this collection.

Let's now take a look at each of the collections (minus Cookies) in the Request object.

The QueryString Collection

A querystring is information that is passed to the server, in the form of a name/value pair. It could contain the client's username, an e-mail address, or personal information. A querystring is appended to a URL with a question mark, '?'. A typical querystring might look like this:

?username=DaddyKool

A querystring's name/value pair is composed of two strings: the name and the value. These two strings are separated by an equal sign, '='. If the request generates more than one querystring name/value pair, then subsequent name/value pairs are separated from each other by an ampersand, '&':

?username=DaddyKool&email=DaddyKool@kool.com

When this information is appended to a URL, it looks something like this:

http://chrisu/BegASP/demo.asp?username=DaddyKool&email=DaddyKool@kool.com

ASP retrieves the values of the variables that are given in the HTTP query string and stores them in the QueryString collection. The QueryString collection returns exactly the same information as the Query_String variable in the same format. So, <%=Request.Querystring%> returns:

username=DaddyKool&email=DaddyKool@kool.com

and

<%= Request.ServerVariables ("QUERY_STRING")%> also returns:

username=DaddyKool&email= DaddyKool@kool.com.

How are Querystrings Generated?

There are three main situations in which a querystring can be generated.

The first is by clicking on a hyperlink generated with an anchor tag, <A>, which already has an in-built querystring:

<A href="somepage.ext?name=value">a querystring example</A>

This hyperlink, when clicked, generates a querystring variable named "name", with the value "value".

The second situation is when a form is sent to the server by the GET method. Take a look at the following code:

Type your first name:   <INPUT TYPE="TEXT" NAME="FIRST"> <BR>

Type your last name:   <INPUT TYPE="TEXT" NAME="LAST"> <BR>

When the browser displays an ASP page containing this code, it might look something like this:

Chapter7_image003

When the user enters his username and password, and clicks on the Login button, two querystring name/value pairs are generated. They correspond to the names of the form's input textboxes and their respective VALUE attribute values. In other words, a name/value pair is generated for every named INPUT element Hence, the URL requested by these actions might look like this:

http://chrisu/BegASP/RequestQuery.asp?first=john&last=doe

It's important to note that the POST form method won't allow you to retrieve querystring name/value pairs, because this stores information in a different collection. We'll look into the POST form method shortly.

The main difference between POST and GET is that POST sends the information as part of the request body, while GET sends information by appending it to the Uniform Resource Locator, (URL).

The final method is, very simply, via a user-typed HTTP address:

When the Enter key is pressed, two name/value pairs are generated, namely first=john and last=doe.

Retrieving a QueryString using the Response Object!

You can retrieve the contents of a querystring and place it in a variable as follows:

strUserInput = Request.QueryString

You can display the contents of a querystring in several different ways. In its simplest form, you could display it with just the following statement:

<%= Request.QueryString%>

We've already discovered that the equal sign was just a shorthand notation for Response.Write. So equally you could write the above as:

<% Response.Write(Request.QueryString) %>

We'll use the equal sign shorthand for the time being, as it distracts less from the querystring code. Either of the above lines will return all of the querystring name/value pairs. Thus, if the name/value pair was equal to username=DaddyKool&pass=ChangeMe then this command would return

"username=DaddyKool&pass=ChangeMe".

In fact, it's more common to use the following:

<%= Request.QueryString("property_name")%>

This will return a specific value, corresponding to the property_name, providing it holds a single value. Thus, you can retrieve information for the string variable name using the following code:

<%= Request.QueryString("username")%>

In the example above, the result "DaddyKool" is returned.

Retrieving the contents of several name/value pairs

What happens though if you have several name/value with different names on the page, each generated by a different form element (e.g. one from a textbox, one from a check box etc)? Perhaps the best way is to employ the For Each notation that we looked at briefly in Chapter 4. You can reference each item separately using the following loop:

For Each Item in Request.QueryString

Response.Write "Item – " & Request.QueryString(Item)

As this goes through the loop, it displays the values for each name/value pair in the QueryString collection, for example:

Item – DaddyKool

Item – ChangeMe

Counting the number of name/value pairs

If another value is subsequently assigned to name, then (unlike variables) the original value persists, and the second value is appended to the name/value pair. For example, by assigning the value "Junior" to the name variable, the name/value pair passed as the querystring appended to the URL would be extended to "name=DaddyKool&name=Junior". Where more than one value exists for the same name, the values are returned by Request.QueryString separated by commas, thus: "DaddyKool,Junior".

In such a situation, you might need more than just a name/value pair to keep track of your data. Help is at hand in the form of the Count property, which is used to track the number of querystring name/value pairs. Let's see an example of this:

<%= Request.QueryString("name").Count %>

This line of code will return the number of querystring name/value pairs that have the name "name". So if the name/value pair was name=DaddyKool, then this code would return the value 1. If the name/value pair was name=DaddyKool,Junior then the code would return 2; and so on.

Note that there is also a global count which returns the number of query strings held in total:

Request.QueryString.Count

How can we use this to get hold of one specific value from a set of values? The answer is to use an index. An index enables you to retrieve one of multiple values for a given property name, and can be any integer value in the range 1 to Request.QueryString("property_name").Count.

To use an index for the property name would require code with the following format:

<%= Request.QueryString("name")(index_val)%>

Of course, index_val is an integer value between 1 and the value held in Count (this is different from a conventional array which starts from 0.) If the value of index_val doesn't correspond to a valid index value (that is, index_val doesn't fall between 1 and Count), then ASP returns an error similar to the following:

Request object error 'ASP 0105 : 80004005'

Index out of range

/directory/somefile.asp, line xxx

An array index is out of range

Let's now build an example using concepts we have looked at so far.

Try it Out – Using Request.QueryString

In this example, we'll request a holiday destination or several destinations from the user. We'll then place these values in a querystring and display the values, along with some complementary information, on a separate web page.

1. Open your HTML editor, create a new file, and type in the following:

<HTML>

<HEAD>

</HEAD>

<BODY>

<H3>Holiday Form</H3>

Please select one or more destinations that you would like brochures for:

<OPTION>Madrid</OPTION>

<OPTION>Paris</OPTION>

<OPTION>Berlin</OPTION>

<OPTION>Moscow</OPTION>

<OPTION>Birmingham</OPTION>

</SELECT>

</FORM>

</BODY>

</HTML>

2. Save the file as RequestQueryString.htm in your BegASPFiles directory.

3. Now enter the following code into your editor:

<%Option Explicit%>

<HTML>

<HEAD>

</HEAD>

<BODY>

<H3>Holiday Response Form</H3>

If Request.QueryString("HolidayLocation").Count=0 then

Response.Write "We won't send you any details "

Else

Response.Write "We will send you details on "

Response.Write Request.QueryString("HolidayLocation")

End If

as requested.

</BODY>

</HTML>

4. Save this as ResponseQueryString.asp

5. Start your browser and open the file RequestQueryString.htm. The resulting HTML output for this script is:

Chapter7_image005

6. Now select one or more destinations (Hold down the Ctrl button while clicking to select more than one) and click on the Submit button. The result is:

Chapter7_image006

The full URL displayed on this example is:

http://My_Server_Name/BegASP/ResponseQueryString.asp?

HolidayLocation=Madrid&
HolidayLocation=Rome&HolidayLocation=Berlin

How It Works

We'll now look at how the ASP code works, and what is contained in the querystring. In the first page RequestQueryString.htm we set the ACTION attribute to the page we wish to transfer control to, and we set the METHOD attribute to GET. By setting the METHOD to GET we ensured that our information is transferred by query string:

<OPTION>Madrid</OPTION>

<OPTION>Paris</OPTION>

<OPTION>Berlin</OPTION>

<OPTION>Moscow</OPTION>

<OPTION>Birmingham</OPTION>

</SELECT>

</FORM>

The rest of the code is straightforward. If you're unfamiliar with how forms transmit information via list boxes, radio buttons or the like, we suggest that you look at Appendix F where there is a detailed tutorial on the subject. One thing to note is that we name the list box HolidayLocation in the code for the form, this is important as we reference it in the next page.

In ResponseQuerySting.asp we set up a simple conditional structure, which first checks the count property of locations, to see if any locations have been selected:

If Request.QueryString("HolidayLocation").Count=0 then

Notice that we reference our querystring using the name assigned to the <SELECT> element created in the previous form, here. If the count is zero then we display the appropriate details:

Response.Write " won't send you any details "

Otherwise, we get the server to display the contents of the HolidayLocation query string:

Else

Response.Write "We will send you details on "

Response.Write Request.QueryString("HolidayLocation")

End If

as requested.

In the example above, this will hold the values "Madrid, Rome,Berlin" – this of course will be different if you entered different places.

Amending Our Program

The property name stores several values associated with one name. In the above example we have three values stored with one name. However, what happens if you want to be able to access each value separately? After all, it stands to reason that if you're requesting brochures on three separate destinations, they might have to be dealt with separately.

This is where index values come in. We can use an index to query the name property: these queries allow us access to each of the values within name separately. Therefore, you could access the first element with the line:

<%= Request.QueryString("HolidayLocation")(1)%>

Here, Request.QueryString("HolidayLocation")(1) holds the value "Madrid". The second value can be accessed using:

<%= Request.QueryString("HolidayLocation")(2)%>

where Request.QueryString("HolidayLocation")(2) holds the value "Rome". You could then store each one in a separate variable:

strHolidayChoice1 = Request.QueryString("HolidayLocation")(1)

However, if you were using a long list of locations, this wouldn't be practical. So one proposed amendment to our program would be to loop through the QueryString collection, using the index property. As previously noted though if you access an invalid index value, you'll generate an error. The way to avoid this is to then loop only as far as the maximum number of items in the querystring. We can use the Count property to do this. If you were to replace the following code in our last example like this:

Dim intLoop

If Request.QueryString("HolidayLocation").Count=0 then

Response.Write "We won't send you any details "

Else

For IntLoop = 1 To Request.QueryString("HolidayLocation").Count

Response.Write "<BR>We will send you details on "

Response.Write (Request.QueryString("HolidayLocation")(IntLoop))

End If

This will separate out each value in the querystring as follows:

We will send you details on Madrid

We will send you details on Rome

We will send you details on Berlin as requested

Alternately, if you didn't want to separate out each value, you could access the whole value contained within the querystring:

<%= Request.QueryString%>

This holds the complete QueryString collection, which is shown on the resulting output: "Name=Chris&Name=Ullman&Pass=secret". The final line of the script does exactly the same thing:

<%= Request.ServerVariables("QUERY_STRING")%>

This holds the complete QueryString collection which is shown on the resulting output: "HolidayLocation=Madrid&HolidayLocation=Rome&HolidayLocation=Berlin"

Now that we've covered every facet of the QueryString collection, we'll move on to a related collection, Form.

The Form Collection

The Form collection holds the values of form elements sent to the HTTP request body via the POST method. In other words, when you fill in the text boxes on a form and pressed the Submit button, all of the values you have typed in can be stored in the Form collection.

Of course, text boxes aren't the only method of passing information on forms. In fact there are many different elements that you can use within a form to send information, such as:

qText Boxes

qCheckboxes

qOption buttons

qLists and their variations

qHidden fields

qText Area

If you're unsure of how any of these work within a form in HTML, we suggest you go to Appendix F, which provides a comprehensive tutorial on all of these features in forms and how the Form collection can be used to extricate information from them.

Assuming you are familiar with these form elements, then we'll only be looking at one example here of how you can retrieve information from the Form collection, as the method of retrieval is almost identical to that used with the QueryString collection. While there are several differences between GET and POST forms in terms of sending data, the only difference between them in using the data once it is in the Request object is the name of the collection itself. All other aspects are same.

Again, this collection can be used together with the Count property, which enables the calculation of the number of values in a given name/value pair; also, the Form collection can use an index to access the individual values within a set of multiple values.

Items in the Form collection are also, like the QueryString collection, composed of name/value pairs. To construct items in a Form collection we follow a similar procedure to that used when creating items in the QueryString collection – that is, with two strings separated by an equal sign, "=". The first string is the form element's name, and the second string is the element's value. Again, multiple form name/value pairs in the form collection are separated by an ampersand, "&".

The main difference between a QueryString collection and a Form collection is that while the QueryString collection gets appended to a URL (with a question mark), the Form collection is sent as part of the HTTP request body and hence will not show up in the URL window in the browser. Note, also, that there's only one way to generate a form collection – by submitting the form using the POST method.

The best way to understand the Form collection is to dive in and take a look at another example.

Try It Out – Using Request.Form

In this example, we're going to do exactly the same thing as we did in the QueryString example – except that we'll be storing our values in the Form collection.

1. Open your HTML editor, open RequestQueryString.htm, and amend the following line:

Please select one or more destinations that you would like brochures for:

2. Save the file as RequestForm.htm in your BegASPFiles directory.

3. Open the file ResponseQueryString.asp and amend the following lines:

If Request.Form("HolidayLocation").Count=0 then

Response.Write "We won't send you any details "

Else

Response.Write "We will send you details on "

Response.Write Request.Form("HolidayLocation")

End If

Note: This assumes that you didn't make the amendments as suggested to our previous example.

4. Save this amended file as ResponseForm.asp.

5. Start your browser and type in the following URL into the address line: http://my_server_name/BegASP/RequestForm.htm

Chapter7_image007

6. As in the first example, select some appropriate destinations then click the Submit button. The result is:

Chapter7_image008

How It Works

The program looks the same, and it runs in the same way; it even returns the same answers. So, what's different? The answer is, very little. All we've done is changed every occurrence of Request.QueryString to read Request.Form:

If Request.Form("HolidayLocation").Count=0 then

Response.Write "We won't send you any details "

Else

Response.Write "We will send you details on "

Response.Write Request.Form("HolidayLocation")

End If

The only noticeable difference in the whole program is that the information is no longer passed to the server as part of the URL. Behind the scenes, you might also notice that you don't get a querystring attached to the URL.

Amending The Program

Again, we can separate out the values from the name/value pairs in the form collection, by using the index values:

Dim intLoop

If Request.Form("HolidayLocation").Count=0 then

Response.Write "We won't send you any details "

Else

For IntLoop = 1 To Request.Form("HolidayLocation").Count

Response.Write "<BR>We will send you details on "

Response.Write (Request.Form("HolidayLocation")(IntLoop))

End If

As expected (just like in the querystring example), that code displays the contents of HolidayLocation on separate lines:

We will send you details on Madrid

We will send you details on Rome

We will send you details on Berlin as requested

For explanations on how to extract information from different form elements and how to use it in the Form collection, we refer you to Appendix F.

The ServerVariables Collection

The ServerVariables collection holds all of the HTTP headers and also additional items of information about the server and the request. We looked at the function of HTTP headers in chapter 2. They are sent by the browser along with a request for a web page, and contain extra information, about the contents of the request. Every time an ASP page is executed the web server creates a set of server variables to accompany that page. These server variables can be interrogated and manipulated using ASP.

It's probably best to start with a list of all the ServerVariables available, but rather than list them all in the book, you'll learn more by physically retrieving the contents of the ServerVariables collection in an example.

Try It Out – Retrieving the Request.ServerVariables Collection

In this example, we'll list all of the variables contained in the ServerVariables collection in a two column table. The left-hand column lists the variables' names and the right-hand column their values.

1. Open your HTML editor, create a new file, and key in the following:

Option Explicit

Dim Key

<HTML>

<HEAD>

<TITLE>The HTTP Server Variables Collection</TITLE>

</HEAD>

<H2>The HTTP Server Variables Collection</H2>

</CENTER>

<TR>

<TD><B>Variable Name</B></TD>

<TD><B>Value</B></TD>

</TR>

For Each Key in Request.ServerVariables

Response.Write "<TR><TD>" & Key & "</TD><TD>"

If Request.ServerVariables(key) = "" Then

Response.Write " "

Else

Response.Write Request.ServerVariables(key)

End If

Response.Write "</TD></TR>"

</TABLE>

</BODY>

</HTML>

2. Save the file as ServVars.asp in your BegASP directory.

3. Start your browser and open the file: http://my_server_name/BegASP/ServVars.asp

Chapter7_image009

How It Works

The ServerVariables collection holds all HTTP header variables as well as lots of general information variables. For the querystring values to show, a form must be submitted, and the form's method must be GET.

To retrieve individual variables in the collection, the syntax is:

<%= Request.ServerVariables("variablename") %>

You must know the specific name of the variable you want to see. You can get the names from the table above or from Appendix I.

In our example, to retrieve every ServerVariable within the collection, we use a For Each...Next loop to iterate through each of the items in the collection.

<% For Each key in Request.ServerVariables

In this case, the variable key is used to store each different Server Variable name in the collection – so for the first iteration, the value in key is ALL_HTTP, in the second iteration it's ALL_RAW, and so on. For each unique value of key this loop will execute the following lines:

If Request.ServerVariables(key) = "" Then

Response.Write " "

Else

Response.Write Request.ServerVariables(key)

End If

If the variable key is empty then this displays a space, otherwise the formatting will be messed up; otherwise, it displays the value stored within the Server Variable contained by key.

What do Server Variables do?

ServerVariables are informative. SERVER_SOFTWARE, for example, tells you the name of the Server's software. For IIS 4.0 or PWS 4.0, it returns "Microsoft-IIS/4.0". You can use them to trigger a certain set of actions, so by checking say the HTTP_USER_AGENT value, you can determine which browser is viewing your pages. This could allows you to customize the page's content to take advantage of specific browser features, or to prevent scripting errors if a browser supports a different scripting engine from the one you usually script for. Consult the whole list in Appendix I for more details.

The ClientCertificate Collection

When the client makes contact with a web server over a secured channel, either end can gain high levels of assurance over the identity of the other by inspecting their digital certificate. A certificate contains a number of items of information about the individual or organization, and this is generated by a trusted third party known as a Certificate Authority (CA). The certificate allows a server to identify the user, so that the server can send sensitive information to a certified user via secure transmission methods. A client certificate is an encrypted number that is stored in a file on the user's computer. The browser sends the number along with a request for an ASP page.

In order to do that, the secure sockets layer (SSL) protocol must be used. SSL is a variation of the HTTP protocol that has much higher levels of security. The latest version of the SSL protocol is SSL3.0/PCT1. The acronym PCT stands for Private Communication Technology.

Using SSL/PCT allows server and client authentication, encryption, and the use of data integrity methods. Authentication ensures that the data is being sent from an 'approved' client to the correct server. Encryption ensures that the data can only be read by the server it is intended for or read by the client it is intended for. Data Integrity ensures that the information sent arrives unaltered, exactly as it was sent. When the SSL protocol is used, URLs are prefixed by https:// (instead of http://). You will also need to connect to the server through a different port.

Before you can use the ClientCertificate collection, you must configure the web server (In IIS 5, from the Default Properties dialog, and select the Directory Security tab) so it can request client certificates, otherwise the ClientCertificate collection will be empty.

MS Certificate Server (CS) will not run on PWS/Win95 or Win98 because Windows95/98 cannot provide a secure environment. CS will run on Win 2000, NT 4.0 Server or Workstation. Coverage of this subject is beyond the scope of this book, but you can find more details in Professional ASP 3.0 – ISBN –1-861002-61-0, from Wrox Press. (This book is no longer available from Wrox but you might find it from a store that sells used books.)

Once the web server is enabled and configured, only SSL-enabled clients will be able to communicate with the SSL-enabled WWW folders.

Two constants need to be declared when working with the ClientCertificate collection:

Const ceCertPresent = 1

Const ceUnrecognizedIssuer = 2

As with all Request object collections, you can iterate through the ClientCertificate collection's values:

For Each key in Request.ClientCertificate

Response.Write( key & ": " & Request.ClientCertificate(key) & "<BR>")

To retrieve an individual value, use the following syntax:

Request.ClientCertificate(key[SubField])

Here, key specifies the name of the certification field to retrieve. A client certificate may have these fields:

Key	Meaning
Certificate	A string containing the binary stream of the entire certificate content in ASN.1 format (a list of numbers separated by a period, e.g. (168.77.243.12)

Flags	A set of flags that provide additional client certificate information. CeCertPresent - A client certificate is present. CeUnrecognizedIssuer - The last certification in this chain is from an unknown issuer.
Issuer	A string that contains a list of subfield values containing information about the issuer of the certificate. If this value is specified without a SubField, the ClientCertificate collection returns a comma-separated list of subfields. For example, C=US, O=Verisign, etc.
SerialNumber	A string that contains the certification serial number as an ASCII representation of hexadecimal bytes separated by hyphens (-). For example, 04-67-F3-02.
Subject	A string that contains a list of subfield values which contain information about the subject of the certificate. If this value is specified without a SubField, the ClientCertificate collection returns a comma-separated list of subfields. For example, C=US, W=Wrox, and so on.
ValidFrom	A date specifying when the certificate becomes valid. This date follows VBScript format and varies with international settings. For example, in the U.S., it could be: 6/31/98 11:59:59 PM.
ValidUntil	A date specifying when the certificate expires.

SubField is an optional parameter you can use to a retrieve an individual field in either the Subject or Issuer keys, or both. This parameter is added to the Key parameter as a suffix. For example, IssuerC, SubjectCN, SubjectS, SubjectL, etc.

This table lists some SubField values:

Value	Meaning
C	The name of the country of origin.
CN	The common name of the user. (This subfield is only used with the Subject key.)
GN	A given name.
I	A set of initials.
L	A locality.
O	The company or organization name.
OU	The name of the organizational unit.
S	A state or province.
T	The title of the person or organization.

The following script examples display all the fields of a client certificate:

Issuing organization: <%= Request.ClientCertificate("IssuerO")%><br>

Subject Name: <%= Request.ClientCertificate("SubjectCN")%><br>

Valid from: <%= Request.ClientCertificate("ValidFrom")%><br>

Valid until: <%= Request.ClientCertificate("ValidUntil")%><br>

Serial Number: <%= Request.ClientCertificate("SerialNumber")%><br>

Issuer: <%= Request.ClientCertificate("Issuer")%><br>

Subject: <%= Request.ClientCertificate("Subject")%><br>

<% TheCompleteCertificate = Request.ClientCertificate("Certificate") %>

Certificate Raw Data: <%= TheCompleteCertificate %><BR>

Certificate Length: <%= len(TheCompleteCertificate)%><BR>

Certificate Hex Data:

For x = 1 to 100

Response.Write Hex(Asc(Mid(TheCompleteCertificate,x,1))) & "&nbsp"

Further discussion of this collection is beyond the scope of this book. For further information on the ClientCertificate collection, we suggest you consult Professional Active Server Pages 3.0 (ISBN –1-861002-61-0), available from Wrox Press. (This book is no longer available from Wrox but you might find it from a store that sells used books.)

<< 7.1.3- The Request Object

Chapter7

7.1.5- Request Object Collection Shorthand >>