<html>
<head>
<title>Server-Side Includes</title>
</head>
<body bgcolor="#FFFFFF" text="#000000">
<div id="Description">
<table cellpadding="0" cellspacing="0" border="0" width="100%" class="main">
<tr>
<td valign="top" class="NAME">Server-Side Includes</td>
<td valign="top" class="COMPATIBILITY">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="divider"><img src="dwres:18084" width="100%" height="1"></td>
</tr>
<tr>
<td valign="top" colspan="2" class="description">





<p><!--<primary>server-side
includes</primary>--> <!--<primary>SSI (server-side
includes)</primary>-->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:</p>




<dl>
<dt><span class="LITERAL">#config</span></dt>
<dd><p>Configures the format for error messages, dates, and file sizes as
they are returned to the client browser</p></dd>




<dt><span class="LITERAL">#echo</span></dt>
<dd><p>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</p></dd>




<dt><span class="LITERAL">#exec</span></dt>
<dd><p>Inserts the results of a command-line shell command or application</p></dd>




<dt><span class="LITERAL">#flastmod</span></dt>
<dd><p>Inserts the last modified date/time for the current page</p></dd>




<dt><span class="LITERAL">#fsize</span></dt>
<dd><p>Inserts the file size of the current file</p></dd>




<dt><span class="LITERAL">#include</span></dt>
<dd><p>Includes the contents of another file into the current file</p></dd>

</dl>




<p>All directives are allowed in HTML. Only the
<span class="LITERAL">#include</span> directive, however, is allowed in both
HTML and ASP pages. The <span class="LITERAL">#include</span> directive is the
only one detailed here.</p>
</td></tr>
</table>
</div>
<div id="ServerSideIncludesCommentsTroubleshooting">
<table border="0" cellspacing="0" cellpadding="0" width="100%">
<tr valign="top">
<td class="NAME">
Server-Side Includes: Comments/Troubleshooting</td>
<td class="COMPATIBILITY">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="divider"><img src="dwres:18084" width="100%" height="1"></td>
</tr>
<tr>
<td class="usage" colspan="2">&nbsp;</td></tr>
<tr><td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
<tr><td colspan="2" class="description">




<p><!--<primary>comments and
troubleshooting</primary><secondary>server-side
includes</secondary>-->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
<filename>.INC</filename><!--<primary sortas="INC file extension">.INC file extension</primary>--> 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.</p>
</td>
</tr>
</table>
</div>
<div id="include">
<table border="0" cellspacing="0" cellpadding="0" width="100%">
<tr valign="top">
<td class="NAME">
#include</td>
<td class="COMPATIBILITY">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="divider"><img src="dwres:18084" width="100%" height="1"></td>
</tr>
<tr>
<td class="usage" colspan="2"><span class="PROGRAMLISTING"><pre>&lt;!-- #include <var class="replaceable">PathType</var> = "<var class="replaceable">strFileName</var>" --&gt;</pre></span></td></tr>
<tr><td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
<tr><td colspan="2" class="description">
<span class="PROGRAMLISTING"><pre>&lt;!-- #include <var class="replaceable">PathType</var> = "<var class="replaceable">strFileName</var>" --&gt;</pre></span>




<p><!--<primary>files,
inserting into scripts/content</primary>--> <!--<primary>inserting files
into scripts/content</primary>--> <!--<primary sortas="include directive">#include directive</primary>-->The
<span class="LITERAL">#include</span> Server-Side Include allows you to insert
the contents of a given file into the HTML content or ASP script. You
must surround the <span class="LITERAL">#include</span> Server-Side Include
statement in an HMTL comment. Otherwise, the text of the Server-Side
Include will be displayed as straight text.</p>




</td>
</tr>
<tr><td colspan="2" class="CLEARSEPARATION">&nbsp;</td></tr>
<tr>
<td colspan="2" class="DESCRIPTIONTITLE">Parameters</td>
</tr>
<tr>
<td colspan="2" class="description">




<dl>
<dt><var class="replaceable">PathType</var></dt>
<dd><p>The type of path specified in the
<var class="replaceable">strFileName</var> parameter. The possible values
for <var class="replaceable">PathType</var> are described in the
following table:</p></dd>

</dl>




<table border="1">



<thead>
<tr valign="top">
<td>
<p><em>PathType Value</em></p></td>
<td>
<p>Description</p></td>
</tr>



</thead>



<tbody>
<tr valign="top">
<td>
<p><span class="LITERAL">File</span></p></td>
<td>
<p>Treats the value of the <var class="replaceable">strFileName</var>
parameter as a relative path from the current directory</p></td>
</tr>



<tr valign="top">
<td>
<p><span class="LITERAL">Virtual</span></p></td>
<td>
<p>Treats the value of the <var class="replaceable">strFileName</var>
parameter as a full virtual path</p></td>
</tr>



</tbody>

</table>

<dl>
<dt><var class="replaceable">strFileName</var></dt>
<dd><p>The <var class="replaceable">strFileName</var> parameter represents the
name of the file whose contents you want inserted into the HTML
content.</p></dd>

</dl>




<p>Introduced with IIS 5.0, there is a second way to include a file. You
can use the <span class="LITERAL">&lt;SCRIPT&gt;</span> tag combined with the
SRC attrribute using the following format:</p>




<span class="PROGRAMLISTING"><pre>&lt;SCRIPT LANGUAGE = "VBScript" RUNAT=SERVER SRC="<var class="replaceable">strFileName</var>"&gt;
&lt;/SCRIPT&gt;</pre></span>




<p>In the preceding code, the <var class="replaceable">strFileName</var>
parameter is the same as that used with the INCLUDE directive and can
be an absolute or relative path.</p>




</td>
</tr>
<tr>
<td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="DESCRIPTIONTITLE">Example 1</td>
</tr>
<tr>
<td colspan="2" class="description">




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




<span class="PROGRAMLISTING"><pre>&lt;!--ReturnTop.INC --&gt;
&lt;CENTER&gt;
&lt;HR&gt;
Click &lt;A HREF = #top&gt;here&lt;/A&gt; to go back to the top of the page.&lt;BR&gt;
&lt;IMG SRC = "/Images/CorpLogo.GIF"&gt;&lt;/CENTER&gt;&lt;BR&gt;</pre></span>




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




<span class="PROGRAMLISTING"><pre>&lt;HTML&gt;
&lt;HEAD&gt;&lt;TITLE&gt;Include Example&lt;/TITLE&gt;&lt;/HEAD&gt;
&lt;BODY&gt;
&lt;%
[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
%&gt;
    Term: &lt;%=adoRecGlossary("GlossTerm")%&gt;&lt;BR&gt;
    Definition: &lt;%=adoRecGlossary("GlossDef")%&gt;&lt;BR&gt;
&lt;%  
    adoRecGlossary.MoveNext
Loop

' Next include the link to top file:
%&gt;
&lt;!-- #include virtual = "/Includes/ReturnTop.INC" --&gt;

&lt;%
' Repeat for the next letter...
<lineannotation>. . . [additional code]</lineannotation></pre></span>




<span class="PROGRAMLISTING"><pre>%&gt;
&lt;/BODY&gt;
&lt;/HTML&gt;</pre></span>




</td>
</tr>
<tr>
<td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="DESCRIPTIONTITLE">Example 2</td>
</tr>
<tr>
<td colspan="2" class="description">




<p>The following script contains ASP code that will be included in a
file using the <span class="LITERAL">&lt;SCRIPT&gt;</span> tag combined with
the SRC method:</p>




<span class="PROGRAMLISTING"><pre>' ReturnTop2.INC
Response.Write "&lt;CENTER&gt;"
Response.Write "&lt;HR&gt;"
Response.Write "Click &lt;A HREF = #top&gt;here&lt;/A&gt; to go back to the top of the page.&lt;BR&gt;"
Response.Write "&lt;IMG SRC = "/Images/CorpLogo.GIF"&gt;&lt;/CENTER&gt;&lt;BR&gt;"</pre></span>




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




<span class="PROGRAMLISTING"><pre>&lt;HTML&gt;
&lt;HEAD&gt;
&lt;TITLE&gt;Include Example 2&lt;/TITLE&gt;
&lt;/HEAD&gt;
This page will now include a file...&lt;BR&gt;
&lt;SCRIPT LANGUAGE="VBScript" RUNAT="SERVER" SRC="ReturnTop2.INC"&gt;
&lt;/SCRIPT&gt;
.
.
.</pre></span>




</td>
</tr>
<tr>
<td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
<tr>
<td colspan="2" class="DESCRIPTIONTITLE">Notes</td>
</tr>
<tr>
<td colspan="2" class="description">




<p>Using the INCLUDE directive, you can include files containing HTML or
ASP code or a combination of the two. Using the
<span class="LITERAL">SCRIPT</span> tag method to include a file (as in the
preceding example) the file you include must contain only ASP code.</p>




<p>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.</p>




<p>If you use the <span class="LITERAL">#include</span> Server-Side Include to
incorporate the contents of an ASP, you must use the
<span class="LITERAL">&lt;%...%&gt;</span> pair around any script. Otherwise,
the contents of the file are treated as regular HTML code.</p>




<p>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 <span class="LITERAL">#include</span>
Server-Side Include in this manner, ensure that whatever file you
include is secured properly.</p>




<p>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:<!--<primary>errors</primary><secondary>handling
of</secondary><tertiary>include files for</tertiary>--></p>




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




<p>This file (named <filename>ERROR.INC</filename> in this example)
could then be included into your script anywhere you think an error
might arise. For example, in the following code,
<filename>ERROR.INC</filename> 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 <span class="LITERAL">True</span>):</p>




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




<span class="PROGRAMLISTING"><pre>%&gt;
&lt;/BODY&gt;</pre></span>




<p>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 <filename>ERROR.INC</filename> file, containing a
standard error notice and a help line phone number.</p>




<p>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.</p>




<p>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:</p>




<span class="PROGRAMLISTING"><pre>&lt;%
Dim strFileName
strFileName = "/Apps/CustomConstants.INC"
%&gt;
&lt;!-- #include file="&lt;%=strFileName%&gt;"--&gt;</pre></span>




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




<span class="PROGRAMLISTING"><pre>&lt;%
Dim strLastName
strLastName = "Weissinger"

&lt;!-- #include file="/Apps/CustomConstants.INC"--&gt;</pre></span>




<p>The following code will also fail:</p>




<span class="PROGRAMLISTING"><pre>&lt;SCRIPT LANGUAGE="VBScript"&gt;
Sub btnHello_Click( )
   Dim strLastName
    strLastName = "Weissinger"

    &lt;!-- #include file="/Apps/CustomConstants.INC"--&gt;

End Sub
&lt;/SCRIPT&gt;</pre></span>




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



</td>
</tr>
<tr>
<td colspan="2" class="CLEARSEPARATION">&nbsp;</td>
</tr>
</table>
</div>
</body>
</html>