Server-Side Includes

Similar to preprocessing directives, Server-Side Includes allow you to include various values (for instance, the last modified date of a file) or a complete file in your script. The following are the Server-Side Include directives supported by IIS:

#config: Configures the format for error messages, dates, and file sizes as they are returned to the client browser
#echo: Inserts the value of an environment variable (equivalent to the various elements of the Request object's ServerVariables collection) into a client's HTML page
#exec: Inserts the results of a command-line shell command or application
#flastmod: Inserts the last modified date/time for the current page
#fsize: Inserts the file size of the current file
#include: Includes the contents of another file into the current file

All directives are allowed in HTML. Only the #include directive, however, is allowed in both HTML and ASP pages. The #include directive is the only one detailed here.

Server-Side Includes: Comments/Troubleshooting



Including files is an excellent method for writing reusable code. We use it often for code we use in almost every script, such as establishing a connection to a database or closing the connection once your code has no more need of it. Your Server-Side Include files need not end with any specific file extension, but Microsoft suggests the .INC file extension as a way of maintaining easily manageable sets of ASP scripts and include files for your projects. Remember that your Server-Side Include files cannot perform cyclical includes (a set of files cannot include each other), nor can they contain preprocessing directives described earlier in this chapter.

#include

<!-- #include PathType = "strFileName" -->

<!-- #include PathType = "strFileName" -->

The #include Server-Side Include allows you to insert the contents of a given file into the HTML content or ASP script. You must surround the #include Server-Side Include statement in an HMTL comment. Otherwise, the text of the Server-Side Include will be displayed as straight text.

Parameters

PathType: The type of path specified in the strFileName parameter. The possible values for PathType are described in the following table:

PathType Value	Description
File	Treats the value of the `strFileName` parameter as a relative path from the current directory
Virtual	Treats the value of the `strFileName` parameter as a full virtual path

strFileName: The strFileName parameter represents the name of the file whose contents you want inserted into the HTML content.

Introduced with IIS 5.0, there is a second way to include a file. You can use the <SCRIPT> tag combined with the SRC attrribute using the following format:

<SCRIPT LANGUAGE = "VBScript" RUNAT=SERVER SRC="strFileName">
</SCRIPT>

In the preceding code, the strFileName parameter is the same as that used with the INCLUDE directive and can be an absolute or relative path.

Example 1

The following script contains only a simple "back to top" line of code and a horizontal line with a graphic.

<!--ReturnTop.INC -->
<CENTER>
<HR>
Click <A HREF = #top>here</A> to go back to the top of the page.<BR>
<IMG SRC = "/Images/CorpLogo.GIF"></CENTER><BR>

We could now include this file anywhere we needed a return to the top of a page:

<HTML>
<HEAD><TITLE>Include Example</TITLE></HEAD>
<BODY>
<%
[CODE TO RETRIEVE GLOSSARY TERMS FROM SQL SERVER DATABASE]
' Filter the recordset to include only the A's.
adoRecGlossary.Filter = "UPPER(SUBSTRING(GlossTerm, 1)) = 'A'"

' Iterate through the items in the filtered recordset.
Do While Not adoRecGlossary.EOF
%>
    Term: <%=adoRecGlossary("GlossTerm")%><BR>
    Definition: <%=adoRecGlossary("GlossDef")%><BR>
<%  
    adoRecGlossary.MoveNext
Loop

' Next include the link to top file:
%>
<!-- #include virtual = "/Includes/ReturnTop.INC" -->

<%
' Repeat for the next letter...
. . . [additional code]

%>
</BODY>
</HTML>

Example 2

The following script contains ASP code that will be included in a file using the <SCRIPT> tag combined with the SRC method:

' ReturnTop2.INC
Response.Write "<CENTER>"
Response.Write "<HR>"
Response.Write "Click <A HREF = #top>here</A> to go back to the top of the page.<BR>"
Response.Write "<IMG SRC = "/Images/CorpLogo.GIF"></CENTER><BR>"

We could now include this file anywhere we needed a return to the top of a page:

<HTML>
<HEAD>
<TITLE>Include Example 2</TITLE>
</HEAD>
This page will now include a file...<BR>
<SCRIPT LANGUAGE="VBScript" RUNAT="SERVER" SRC="ReturnTop2.INC">
</SCRIPT>
.
.
.

Notes

Using the INCLUDE directive, you can include files containing HTML or ASP code or a combination of the two. Using the SCRIPT tag method to include a file (as in the preceding example) the file you include must contain only ASP code.

The examples demonstrate how using include files can reduce the amount of redundant work you are required to do, but these examples are very simple. Suppose, as another example, that you have an include file containing the DSN of your database, the username, and the password. You could use that include file all over your site. It would then be a very simple matter to change username and password: you'd just change it in the include file.

If you use the #include Server-Side Include to incorporate the contents of an ASP, you must use the <%...%> pair around any script. Otherwise, the contents of the file are treated as regular HTML code.

One use for this Server-Side Include is to localize the portions of your script that are used often, such as database access information. This also allows you to change usernames and passwords quickly and efficiently. If you choose to use the #include Server-Side Include in this manner, ensure that whatever file you include is secured properly.

You can include files within files that are, in turn, included in other files. You can also include the contents of a given file multiple times in the same script. One example of this is in a simple error-handling script. For example, consider the following file:

<%
If Err.Number <> 0 Then
%>
<HTML>
<HEAD><TITLE>Error Notice</TITLE></HEAD>
<BODY>
There has been an error in your script (<%=Request.
ServerVariables("SCRIPT_NAME")%>.<BR>
Please contact customer service at 1-800-555-HELP and tell 
them that you've experienced an error in (<%=Request.
ServerVariables("SCRIPT_NAME")%> and that the parameters sent to the 
script were the following:<BR>
(<%=Request.ServerVariables("QUERY_STRING")%>.<BR><BR>
We apologize for the inconvenience.
</BODY>
</HTML>
<%
End If
%>

This file (named ERROR.INC in this example) could then be included into your script anywhere you think an error might arise. For example, in the following code, ERROR.INC is included after the ADO connection is established and after the recordset object is created (note that for this form of error trapping to work, the Buffer property of the Response object must be set to True):

<%Response.Buffer = True%>
<HTML>
<HEAD><TITLE>Database Info Page</TITLE></HEAD>
<BODY>
<%
Set adoCon = Server.CreateObject("ADODB.Connection")
AdoCon.Open "MyDatabase"
%>
<!-- #include virtual = "/Accessory/ERROR.INC" -->
<%
Set adoRec = adoCon.Execute ("SELECT * FROM TopSales")
%>
<!-- #include virtual = "/Accessory/ERROR.INC" -->
<%
. . . [additional code]

%>
</BODY>

In this script, if an error is raised when opening the database connection or when creating the recordset, the user will see the contents of the ERROR.INC file, containing a standard error notice and a help line phone number.

When you include a file, make sure that the included file does not include the current file. This will result in a service-stopping error on the web server, requiring that you stop and restart the web service.

You must also remember that Server-Side Includes are processed before any script code. For this reason, you cannot dynamically determine which file to include. For example, the following script will result in a runtime error:

<%
Dim strFileName
strFileName = "/Apps/CustomConstants.INC"
%>
<!-- #include file="<%=strFileName%>"-->

Finally, Server-Side Includes must be placed outside script delimiters (<%...%>), <SCRIPT></SCRIPT> tags, and <OBJECT></OBJECT> tags. For example, the following code will result in a runtime error (there is no closing %> delimiter):

<%
Dim strLastName
strLastName = "Weissinger"

<!-- #include file="/Apps/CustomConstants.INC"-->

The following code will also fail:

<SCRIPT LANGUAGE="VBScript">
Sub btnHello_Click( )
   Dim strLastName
    strLastName = "Weissinger"

    <!-- #include file="/Apps/CustomConstants.INC"-->

End Sub
</SCRIPT>

This is the only Server-Side Include that you can use in both HTML and ASP files. If you use the #include Server-Side Include in a file, that file's extension must be one of those mapped to SSINC.DLL, the dynamic link library that interprets Server-Side Includes.