RSS |
7.1.8- Controlling How Information is Returned
Created
by Brendan Doss.
|
| << 7.1.7- The Response Object | Chapter7 | 7.1.9- Using the Response Object to Control what the Browser does >> |
Controlling How Information is Returned
Before we can look at how to control the return of information, we need to look at how information is normally returned. At the beginning of this chapter, we hinted that there was more going behind the scenes when we used the Response.Write method, and indeed there is. We need to discuss exactly what happens now. When this method is called, the Response object will take the information that the user has requested and add it to the HTML output stream.
HTML Output Stream
Let's step back a bit and take a look at what the HTML output stream is. It's a dynamically created queue of information that is waiting to be sent back to the browser. If you go back to our initial definition of what ASP is supposed to do, then you know that its primary job is to create an HTML page that can be displayed by a client. Although an ASP script can do much more than static HTML, whatever we want to put on the client's screen has to be displayed through the creation of an HTML page. ASP dynamically builds HTML pages to be displayed on the client's browser.
When an ASP script begins, it also creates an empty HTML output stream ready for the HTMLpage to be created in. So the stream can be thought of as a holding bin, where the web server builds a dynamic HTML page, and then the stream is sent down to the client. This temporary storage space where the stream is held is known as a buffer. The first method that ASP scripts use to add information to the output stream is using the Response object to set the HTTP headers. We will cover that later in the chapter. First, let's talk about the HTML output stream in general terms.
At the simplest level, the HTML output stream is always built in the same way: the stream is created with the first bit of data sent, and when new information is added to it, it can only be added to the end. It's like a simple queuing mechanism. If you got to the local bank, and join the queue, the people who got in before you are served before you. The HTML output stream is also a queue, one that is waiting to be sent to the client. Therefore, it has to be created in order, with required tags being sent in order to the browser.
This means that when we send the HTTP headers to the buffer, the HTTP header information has to be written to the buffer first. Once the headers have been sent to the buffer, we can start to send the contents of the HTML page to the buffer. The easiest way to do this is with native HTML in the ASP script file. Any HTML that is not created by the code within the <%…%> tags will be added to the HTML output stream. The diagram here illustrates this:
So the buffer is the place where the ASP uses the ASP script to generate a dynamic HTML page. As we just mentioned, the buffer starts out as empty when the script begins. As the script is run, information that is destined for the client is placed in the buffer, along with static HTML. The order in which information is placed in the stream is the same order that it will be sent to the browser. Once all of the ASP scripts have been processed, then the contents of the buffer is sent to the browser in one fell swoop.
This is fine for most pages, but what if your ASP script is going to take a long time to process? For example, maybe you are trying to access information from a remote system. Since the HTML output stream will not be sent to the client until the script has completed, the browser will just appear to be spinning its wheels waiting for the server to respond. In this case, we may want to send some information to the client, to let the user know that the script is processing. Then once the processing has completed, we can send all of the information back to the client.
To do this, we will be manually controlling the way that ASP buffers the HTML output stream. There are one property and three methods that will allow us to control when the output stream is sent to the client. These are: Buffer, Flush, Clear, and End. We'll look at each in turn.
Buffer
The Buffer property of the Response object is used to tell ASP that we will be manually controlling when the HTML output stream is sent back to the browser. Buffering is, by default, turned on. To turn it off, we would need to set the value of the property to False:
Response.Buffer = false
Response.Buffer has to be inserted after the language declaration (if one is used), but before any HTML is written (that is, before any output is generated):
<%@ LANGUAGE="scriptinglanguage"
Response.buffer = false %>
<HTML>
...
The Buffer property cannot be set after the server has sent output to the client. For this reason, the call to Response.Buffer should be the first line of your asp script (not the first line of the file though).
Flush
The Flush method sends any previously buffered output to the client immediately, but continues processing the script. This can be useful for displaying partial results before your script finishes processing so that your user does not get impatient while waiting for the full result of a long query.
To call this method, simply use:
<% Response.Flush %>
Flush causes a run-time error if the Response.Buffer property has not been set to true.
Clear
The Response.Clear method erases any already-buffered HTML. However, it only erases the response body and does not erase HTTP response headers. It will only erase information that has been added to the HTML output stream since the last call to Response.Flush. If you have not called Response.Flush, then it will erase all of the information that has been added since the beginning of the page, except the headers.
To call this method, simply use:
<% Response.Clear %>
Clear will cause a run-time error if Response.Buffer has not been set to true.
End
The End method causes the server to stop processing the script and send the buffered output. Any further script instructions are not processed, nor is any remaining HTML sent. Calling Response.End flushes the buffer, if Response.Buffer has been set to true.
To call this method, simply use:
<% Response.End %>
Try It Out – Controlling the Output Buffer
In this example, we will look at how you can use the buffer control in an ASP script to control when – and if – information is sent back to the browser.
1. Using NotePad or your editor of choice, create the BufferOutput.asp file with the following source code.
<% Response.Buffer = true %>
<HTML>
<HEAD>
<TITLE>Testing the Response Buffer</TITLE>
</HEAD>
<BODY>
Let's send some text to the HTML output stream.<P>
It is waiting to be sent - Let's send it.<P>
<% Response.Flush %>
Now we want to send this to client<P>
Oops, we just changed our minds - let's clear it<P>
<% Response.Clear %>
<%
Response.Write "We can control the output of Response.Write method too<P>"
Response.Flush
%>
I think we are finished - let's end it.<P>
<% Response.End %>
Wait a minute - I wanted to say this, but it is too late!
</BODY>
</HTML>
2. Save the BufferOutput.asp file in your BegASP directory.
3. View the page in your web browser - you should see something like this:
|
|
4. View the source of the ASP file so that you can see exactly where the Response.End was called, as no further HTML was sent either.
|
|
How It Works
The first step in taking control over how the HTML output stream is sent back to the browser is to turn buffering on:
<% Response.Buffer = true %>
<HTML>
By setting the Buffer property of the Response object to true, we are telling ASP that we will be controlling when information should be sent to the browser. This statement needs to be before any statements that may cause information to be written to the HTML output stream:
Let's send some text to the HTML output stream.<P>
It is waiting to be sent - Let's send it.<P>
<% Response.Flush %>
Now we want to output some HTML text to the browser. We are doing this by inserting our HTML code at a point in our code that is after the start of the ASP code and before the end of the ASP code. To do this we have to make sure we close and reopen our <% ... %> script delimiters appropriately. Even though we are not using one of the Response object's methods to send information back to the client, this HTML is still being written to the HTML output stream.
Once we have written some text, we want to send it immediately to the browser. This is done by calling Response.Flush. When ASP encounters this statement, it will immediately send whatever information is in the HTML output stream to the client, before clearing that information from the stream.
Now we want to send this to client<P>
Oops, we just changed our minds - let's clear it<P>
<% Response.Clear %>
Next, we want to output some more text to the browser. But this time, after adding the text to the HTML output stream, we decide that we really didn't want that text after all. There is no way to selectively remove it from the output stream, but we can erase everything that is already in the stream. To do this, we will call the Clear method of the Response object. If you look at what the browser is displaying, or even the source HTML for what the browser is displaying, you won't find these two lines of text there.
<%
Response.Write "We can control the output of Response.Write method too<P>"
Response.Flush
%>
All of the information that is sent to the HTML output stream, whether from a method of the Response object, such as Write, or from native HTML, is under our control when we have enabled buffering. In this step, we are adding information to the output stream by using the Response.Write method. After outputting the line of text, we will send it to the client by again using the Flush method.
I think we are finished - let's end it.<P>
<% Response.End %>
Wait a minute - I wanted to say this, but it is too late!
</BODY>
</HTML>
We then want to send some final information to the browser. Once we have added it to the output stream, we call the End method of the Response object. This tells ASP that we have sent all of the information that we want to the client. Its job is to send the remaining contents of the HTML output stream to the browser, then stop processing any more script.
If you look at the source HTML for the page that ASP generated, you will see that the last line of code is the line just before the call to Response.End. None of the other information that was in the ASP script, and neither the terminating </BODY> and </HTML> tags, have been sent to the client. So, in this case, calling End really does mean the end.
| << 7.1.7- The Response Object | Chapter7 | 7.1.9- Using the Response Object to Control what the Browser does >> |
