Server-side Include directives

Server

What can be done with server-side include (SSI) statements (or directives)? Not much, unless you intend to create an executable file that runs on a Web server and access the ISAPI through STDIN and STDOUT functions. This means that you can use C, C + + or other languages (such as Delphi) to write them, but VB is not suitable. What's more, what you can do with SSI directives can do just as well in the ASP. In many ways, the SSI features of IIS are backward compatible with the original web site and Web pages that use these features.
However, you may sometimes want to use SSI instead of ASP on your site. In IIS 5.0, server-side include directives can be more easily integrated into ASP pages at a remote site than before, and they are useful, especially as a way to execute operating system commands or legacy CGI applications. The instructions that are available will be described in great detail later.
#include指令是这些指令之一, it has been in use with ASP for some time and also in SSI pages. In fact, this has caused a lot of confusion for ASP developers who don't have traditional web development backgrounds.

4.2.1 an incredible ASP #include指令
In an ASP page, you can use the #include directive to insert the contents of another file into the current page:
<!--#include file= "/scripts/usefulbits.inc"-->
This instruction reads the entire contents of the file and inserts it into the page, replacing the <!--#include ... --> line. This is a very useful technique for inserting HTML paragraphs that can be reused. You also use this directive to insert code snippets. For example, if you have a file that contains several scripting functions (or just a single line of scripting code) that are used in several pages at the same time, you can use the #include directive to insert it into each page that requires it.
By separating the scripts from the content, you provide a level of composition for the page. This means that if the script is modified, the script's modifications are automatically reflected in each page that uses the containing file when the client opens the page again. Including files is also a simple way to insert server-specific information, so moving the site to another server does not mean you must edit all pages that involve the original server (the obvious example is a database connection string or a link that specifies a complete URL or server name). This can greatly reduce maintenance costs.
For example, you can name the following as a containing file named Connect.inc:
<%
strconnect = "Server=myserver;database=mydb;driver={sql SERVER};" _
& "Uid=username; Pwd=secretpassword "
%>
You can then use this file on any page:
<!--#include file= "Path_to_fileconnect.inc"-->
<%
...
strtheconnectionstring = StrConnect ' from include file
...
%>
Another situation where you use the include file is that some of the content needs to be modified at a specified time interval. For example, a Web page that displays a bibliography list on the Wrox Web deverloper site contains a table with all the cover pages, titles, and buttons, as shown in Figure 4-2:

The HTML and text of this table remain in a separate file, which is included in the home page through a separate #include statement. Each time a new book is added to the database on which the page is based, the containing text file is recreated based on the database and written to disk as a text file.
This technology greatly reduces the amount of work on the Web server and the database server, and responds faster to visitors to the site.
1. Include Files and ASP
The #include directive used in an ASP Web page (that is, a Web page with an. asp file name extension) cannot be handled like a real SSI instruction, it is only a special instruction that an ASP can recognize and parse. Ssinc.dll is used directly to perform SSI #include指令. However, the page that replaces the #include instruction by the contents of the corresponding file is explained by ASP.
This means that the ASP does not control the operation of the #include directive. For example, you might experiment with the following code:
<%
' This'll *not* work
Strincludeurl = Request.Form ("FileName")
%>
...
<!--#include file= "<% = Strincludeurl%>"-->
Ssinc.dll will look for files named <% = Strincludeurl%> and cannot be found, so this code will not work.
2. Include security for files
If no executable script is included, ASP pages on the Web server cannot be downloaded to a client via the IIS Web Service program. However, someone has discovered occasional security vulnerabilities, such as the famous $data problem, where all Web servers that retain Web content on NTFS-formatted disks have problems. This problem has been resolved in IIS 5.0.
$DATA problem occurs because all files on a Windows NTFS drive have a default value, which is the contents of the file, and is indicated by the filename plus the suffix ":: $DATA". Adding it to the end of the URL of an ASP page will disrupt the script mapping relationship in IIS and allow the server to not process the script contained in it without loading the page. For IIS 4.0 and earlier versions, there is a way to resolve this problem, or you can simply add a few mappings to force IIS to perform the Web page properly: Add the ". asp:: $DATA" and ". Asa:: $DATA" mappings, both pointing to the Asp.dll file.
The extensions for include files are typically. inc or. txt. If you find a path and file name for a containing file on your site, you can download the included file by typing the URL of the containing file into the browser's address bar instead of performing it as part of the ASP Web page. To prevent this, especially if the file contains sensitive information such as a database link string, you might want to include the file with an. asp extension. In this case, if you attempt to download a containing file, it will first be routed to Asp,asp to execute all the script code in the file and send only the results. A link string, as defined in the include file, is as follows:
<%
strconnect = "Server=myserver;database=mydb;driver={sql SERVER};" _
& "Uid=username; Pwd=secretpassword "
Response.Write VbCrlf ' Output a carriage return character
%>
The client can only accept a single carriage return rather than scripting code because the file has been executed by ASP on the server. If you do not include a carriage return, the browser hangs and waits for a response (this is not our problem because we do not intend to allow users to access the file directly).
Access control lists for IIS 5.0 and Windows
In IIS 5.0, Microsoft has changed the way that Web servers and operating systems Access server-side include files.
In earlier versions of IIS, when Ssinc.dll loaded a virtual URL (that is, using virtual = "FileName" instead of file = "filename") to locate a containing file, The security check for Windows itself is bypassed and any security settings on the file and the stored directory are ignored. Now, in IIS 5.0, the account that runs the current ASP or SSI page must be consistent with the permissions set on the file and directory in the Windows access Control List (ACL). If this is not the case, the SSI instruction will fail to run.

4.2.2 server-side Include directives overview
In addition to the #include statements that have been discussed, there are five server-side include directives that IIS supports (remember that these statements cannot be executed in an ASP Web page except for #include). These server-side contains instructions and instructions as shown in table 4-1:
Table 4-1 Server-side contains instructions and instructions
Instructions
Description

#include
Inserts the contents of a specified file into the response stream that will be sent to the client and replaces the instruction. For example:
<!--#include FILE = "Usefulbits.inc"-->
This instruction inserts the contents of the name Usefulbits.inc file into the response. This file can be described by a combination of relative or full path and filename, such as file=. Scriptsmyscr.inc ". By using the Virtual property, you can use a fictitious relative or absolute path to describe it, for example:
<!--#include virtual= "/mysite/ussefulbits.inc"-->
<!--#include virtual= ". /.. /thisbit/usefulbits.inc "-->

#config
Describes the format of text that will be used in subsequent directives for data, time and file size, and general SSI error messages that are returned to the client. For example:
<!--#config errmsg= "SSI processing Error"-->
Set SSI error message content to ' SSI processing error '.
<!--#config timefmt= "%a,%b%d%Y%h:%m:%s"-->
Sets the format of the date and time returned by the subsequent SSI instruction. This example sets a format style: Saturday, August 14 1999 10:34:50. A list of flags that can be used for format strings is given in Appendix C.
<!--#config sizefmt= "BYTES"-->
Sets the unit for the size of the file returned by the subsequent IIS directive. This example sets the unit to bytes. The value available to Sizefmt is "abbrev", indicating that the calculated value returns kilobytes (KB) to the size of the file

#echo
Inserts the value of an HTTP environment variable into the response stream sent to the client and replaces the directive. For example:
<!--#echo var= "SERVER_NAME"-->
Write the name of the server that is executing instructions to the page

#exec
Executes a program or a server shell command, for example:
<!--#exec cgi= "/scripts/myapp.exe?value1=this&value2=that-->
Executes a CGI program called Myapp.exe, which allows you to pass a query string that executes in separate memory.
<!--#exec cmd= "cmd.exe/c iisreset/stop"-->
Starts a specific operating system command interpreter (Cmd.exe) and executes a command iisreset/stop. /c indicates that the command interpreter also ends when the command ends. Use CMD to add the following registry key:
Hkey_local_machine/system/currentcontrolset/services/w3svc
/parameters/ssienablecmddirective
Set the value to 1 and restart the WWW service to allow the CMD flag to be used in the #exec directive. Value is 0, the use is prohibited and unauthenticated use is prevented

#flastmod
Inserts the last modified date and time of a specified file into the response stream sent to the client and replaces the directive.
For example:
<!--#flastmod file= "Default.asp"-->
As with the #include directive, you can also use a virtual path to define the file, such as:
Virtual= "/mysite/usefulbits.inc"
Or
Virtual= ". /thisbit/usefulbits.inc "

#fsize
Inserts the size of a specified file into the response stream sent to the client and replaces the instruction. For example:
<!--#fsize file= "Default.asp"-->
As with the #include directive, you can also use a virtual path to define the file, such as:
Virtual= "/mysite/usefulbits.inc"
Or
Virtual= ". /thisbit/usefulbits.inc "


1. IISReset utility
Iisreset.exe is a new utility that is provided by IIS 5.0. As a command-line utility, if the account that is used to execute the utility has administrator privileges, it is useful for controlling Internet-connected servers running on a local or a networked computer. It can be used to stop or start all services in the correct order, to display the status of the service, to reboot the server, and to allow or disallow the administration of the service. For example:
Iisreset/restart/timeout:30/rebootonerror
This will stop and restart all Internet services in the correct order. If a service fails to stop or reboot within the specified timeout period (30 seconds), the server reboots. You can use some of the switches in the CMD-type #echo SSI directive to make the page inaccessible and require users to provide details of a valid account with administrator privileges on the target server. The full description of this utility and the available command switches are in Appendix C.
2. net stop and net start command
If the account used to execute the utility Net.exe has administrator privileges, it can be used to manage any services running on the server (that is, it can be local or from another computer). Although this program is not advocated for use with Internet services, such as WWW or FTP services, it is useful to stop and start the functionality of other services. In fact, the net command can also be used in a series of other network-related commands.
The syntax is:
NET [start | stop] Service_Name
For example, you can use the command net stop cisvc and net start Cisvc to stop and start the Miscrosoft indexing Service. You can use the cmd-type #echo SSI directive to make the page inaccessible and require users to provide details of a valid account with administrator privileges on the target server. You'll see an example of this later.
A complete list of all options and switches for the net command can be found in the Windows 2000 Help file. Select the Help item from the Start menu and look for "netcommands" in the Help Window's index page.
Examples of 4.2.3 server-side include directives
This section provides sample pages that you can use to experiment with a variety of server-side include statements. Opens the subdirectory Chapter04 for the sample Web page, displaying the SSI directives and the ASP Server Object home page (that is, default.asp in the subdirectory Chapter04), as shown in Figure 4-3:

All of the examples in this book can be downloaded from our web site. Readers will find all the sample pages in the remainder of this chapter in the subdirectory Chapter04 of the sample.
1. Using ssi/cgi processing instructions
Click the link to enter the Server-side Include and CGI statements page, which opens the Ssi_cgi.stm page. Note that the file name extension for this page is. stm, which indicates that this is not an ASP Web page. The page uses all of the SSI directives that were previously discussed except for the #exec directive (see later), and shows how and how the instructions are used, as shown in Figure 4-4:

(1) #include指令
The beginning of the page, "Include Files with SSI", displays the contents of another separate file named Intro.inc. The following is the entire contents of the file:
Note that we must use the HTML entry "<" and ">" to display the angle brackets in the Web page. If this is not done, they cannot be treated as part of the annotation element and cause the instructions in them to be executed.
In the main ssi_cgi.stm page, the code to insert this file into the page is simple:
<!--#include file= "Intro.inc"-->
(2) #config, #fsize和 #flastmod instructions
The next section of the page shows the size of the file default.asp and the last modified time in the same directory as the page. #config instructions are used three times here:
· One time is to set the SSI error message.
· One time is to format the date and time.
· The format of the file size calculation is set once.
Insert values into the Web page using the #fsize and #fiastmod directives:
<p><div class= "subhead" >ssi statements</div>
<!--#config errmsg= "SSI processing Error"-->
(sets error message in case of SSI error) <BR>
<!--#config errmsg= "SSI processing Error"--><p>

Details of file ' Default.asp ':<br>
<!--#config sizefmt= "BYTES"-->
(Sets Fsize to return size in bytes) <BR>
<!--#config sizefmt= "BYTES"-->

<!--#fsize file= "Default.asp"-->
Returns: <B><!--#fsize file= "Default.asp"--> bytes</b><br>

<!--#config timefmt= "%A,%B%d%Y%h:%m:%s"-->
(sets format for date/time results) <BR>
<!--#config timefmt= "%A,%B%d%Y%h:%m:%s"-->

<!--#flastmod file= "Default.asp"-->
Returns: <B><!--#flastmod file= "Default.asp"--></b><p>
(3) #echo instruction
The last part of the page (see only a portion of the screen) shows the contents of all HTTP headers that can be accessed using the #echo directive. The code for each line is the same, only the value of the var attribute changes. A complete list of all allowable values for the Var attribute is given in Appendix G.
<div class= "subhead" >http variables</div>
<!--#echo var= "Auth_type"-->
Returns: <B><!--#echo var= "Auth_type"--></b><br>
<!--#echo var= "Auth_password"-->
Returns: <B><!--#echo var= "Auth_password"--></b><br>
... etc...
2. Using the #exec directive
#exec指令与其他的SSI指令相比使用起来困难一些, because of this, put it on the other page independently. You can access the startup page from the ASP Server Object and SSI Directives main menu.
On this page, select the Using the #echo server-side Include Directive link. This operation opens the "SSI #exec Directive" page, as shown in Figure 4-5:

This is an ASP page ssi_exec.asp. Two buttons to open the. stm page, which performs the action described in the #exec instruction.
(1) Run this example on the server
In SSI #exec指令示例能够在服务器上工作之前, some configuration modifications must be made. First, you need to create the SSIEnableCmdDirective entry (type DWORD) in the registry of the Web server, in the following key name:
Hkey_local_machinesystemcurrentcontrolsetservicesw3svcparameters
The value is then set to 1, as shown in Figure 4-6:

This allows the #exec instruction to be used in conjunction with the Cmd property.
Second, anonymous access must be disabled for the directory containing the. stm file with the #exec directive, and the client will be forced to provide details of the account, which should be an account with Administrator level permissions. This is also the requirement that net commands work correctly.
Activate the Internet Services Manager application and select the directory containing the. stm files that use the #exec directive (in the example, these files are start_cisvc.stm and stop_cisvc.stm in the EXEC directory). Then open the Properties dialog box for the directory. In the Directory Security tab, click the Edit button in the anonymous access and authentication control area to open the Authentication Methods dialog box, as shown in Figure 4-7:

This dialog box does not select the Anonymous access check box. If you do not use Internet Explorer to access this page, open the Basic authentication option to allow non-ie browsers to access the page by submitting a username/password. When setting, a security warning appears, and click Yes. The browser will now be forced to produce the appropriate account number and identity certificate, because the Web page cannot be accessed anonymously.
To see the results of the start and end service, open the Services MMC plug-in to terminate the Indexing Service, as shown in Figure 4-8:

(2) Start and terminate indexing Service
Click the button on the sample Web page to start the Microsoft Indexing Service.
The short name for this service is cisvc, which is often called the Microsoft Index Server, and the "CI" character in the name actually represents "content indexer".
When prompted, enter the username and password of an account with administrator privileges on the Web server. When the page (start_cisvc.stm) opens, you will feel a certain delay because the #exec instruction loads an instance of a window command interpreter (Cmd.exe) and executes the net START command. Once the service is started (or if it is already running), the remainder of the page is displayed, as shown in Figure 4-9:

The code for this page is very simple. You can see that the #exec directive has the cmd attribute, which is set to "cmd.exe/c net start cisvc". The form contains a submit button that goes back to the previous page:
<p>processing the SSI directive:</p>
<P><B><!--#exec cmd= "cmd.exe/c net stop cisvc"--></b></p>
<!--#exec cmd= "cmd.exe/c net stop cisvc"-->

<form action= ". /ssi_exec.asp ">
<input type= "SUBMIT" name= "Cmdok" "value=" ">
Return to the previous page<p>
</FORM>
Other. stm pages can be opened from the previous page, such as stop_cisvc.stm to terminate the service again, except that the net stop command is used instead of the net start command.
...
<!--#exec cmd= "cmd.exe/c net stop cisvc"-->
...