Server-Side Includes

Server-side include (SSI) files add the same text or other information to HTML documents just before sending the HTML files to users. The common information can be anything, for example:

Text
Graphics
Applications

This version of SSI gives you more flexibility in creating include statements, with special preprocessing directives in addition to the #INCLUDE directive:

Directive	Decription
#FLASTMOD	Retrieves the last modification time of a file.
#FSIZE	Retrieves the size of a file.
#ECHO	Inserts the value of various Common Gateway Interface (CGI)-system environment variables.
#CONFIG	Configures how variables and commands are displayed.
#EXEC	Executes CGI-system command scripts and pipes output into an HTML document.

To make SSI work, the Web server must parse the HTML document and process any directives before sending the final HTML file to the client. These new directives extend support for SSI in Microsoft Internet Information Server (IIS) version 2.0 to NCSA HTTPd and other Web servers.

In IIS version 2.0, support for SSI exists in the actual service code; but in this version of SSI, support has been moved into a separate Internet Server Application Programming Interface (ISAPI) dynamic link library (DLL). This change makes the design modular, allowing SSI to work independently of IIS.

Note SSI works only on Microsoft Windows NT version 4.0.

Setting Up SSI

Requests for .stm files are mapped into a call to the SSI ISAPI DLL. When this DLL is executed, it processes an HTML file and sends the output to the client through ISAPI. So, to set up SSI, you must:

Map appropriate file extensions to execute ISAPI DLLs.
Grant Execute permission to the virtual root where the include files (.stm files) are stored.

DLL Mapping

By editing the Microsoft Windows NT registry, you can map file extensions (such as .stm) to execute ISAPI DLLs. In the same way, you can map .stm files to the SSI DLL. The mapping key is stored along the following path:

HKEY_LOCAL_MACHINE \SYSTEM \CurrentControlSet \Services \W3SVC \Parameters \Script Mapping

To map the .stm extension to the SSI DLL

Add the following key and value to the Script Mapping entry:

.STM : REG_SZ : "Path of SSI DLL"

where Path of SSI DLL is the Universal Naming Convention (UNC) path to the appropriate DLL.

Disabling SSI Support

To disable SSI support, you must remove the .stm key from the Script Mapping registry entry. See the previous section, “DLL Mapping,” for the registry path.

Directory Permission

For a source file to be mapped into an DLL call, the file must exist in a virtual root, a directory that has Execute permission. For example, if you store .stm files in the same place as regular .htm files, you should add execute permissions to this virtual mapping (by default, /). To add this permission, use the Internet Service Manager or append the following value to end of the directory map value where .htm files currently exist:

,,5

The registry key for directory mapping is:

HKEY_LOCAL_MACHINE

 \SYSTEM
  \CurrentControlSet
   \Services
    \W3SVC
     \Parameters
      \Virtual Root

SSI Basics

In general, including the same information or application in all HTML documents sent out is a three-step procedure.

Create an HTML file with the common information.
The common information can be text, a form, an application, or whatever you want.
Write an include statement in the HTML documents in which you want the common text or form to go.
Make sure the documents with the include statements have an .stm extension.

The format for the basic include statement is:

Note The ActiveX delimiters <% and %> can also delimit the directives in .stm files, but not in .asp files.

The value can contain a relative path or the full path, from the home directory of your WWW service.

Common Directive Format

SSI is supported by IIS through special preprocessing directives in HTML documents. These directives are parsed by the SSI DLL and processed. All directives are contained in HTML comment tokens and take the following general form:

<!--#<PREPROCESSING_DIRECTIVE>-->

Note All keywords are case-insensitive.

The following sections summarize the SSI directives based on HTTPd implementation.

#INCLUDE <VIRTUAL / FILE> = "filename"

Includes the contents of the given file into the HTML stream. This directive allows include files to import other files.

If the VIRTUAL tag is specified, the file name represents a path that is relative to the base directory of the server. The following example will include the file Winnt\System32\Inetsrv\Scripts\Tools\Myfile.txt in all HTML files sent out:

If the FILE tag is specified, the file name is relative to the directory of the current document. The following example will include the file Winnt\System32\Inetsrv\Wwwroot\Myfile.txt in all HTML files sent out:

See this sample file for another example.

#FSIZE <VIRTUAL / FILE> = "filename"

Includes the size of the given file into the HTML stream. For example:

The specification of the file name follows the same conventions as the #INCLUDE directive.

By default, the size is expressed in terms of kilobytes. You can change the unit of measurement by reconfiguring the #CONFIG SIZEFMT directive. See #CONFIG <OPTION> = "strng" later on this page.

The number string contains commas (,) as thousands placeholders (for example, 1,245,231).

See this sample file for another example.

#FLASTMOD <VIRTUAL / FILE> = "filename"

Includes the time the given file was last modified into the HTML stream. For example:

The specification of the file name follows the same conventions as #INCLUDE directive.

By default, the time is expressed in “Weekday MonthName DayNumber YearNumber” (for example, Monday June 3 1996). For examples, see #CONFIG <OPTION> = "strng" later on this page, and this sample file.

#ECHO <VAR> = "variable"

Includes the value of the variable specified by VAR in to the HTML stream. Available variables are shown in the following table.

Variable	Meaning
AUTH_TYPE	The type of authorization in use. If the user name has been authenticated by the server, this will contain Basic. Otherwise, it will not be present.
CONTENT_LENGTH	The number of bytes that the script can expect to receive from the client.
CONTENT_TYPE	The content type of the information supplied in the body of a POST request.
DOCUMENT	The current file name.
DOCUMENT_URI	The virtual path to the current document..
DATE_GMT	The current date in Greenwich Mean Time (GMT).
DATE_LOCAL	The current date in the local time zone.
GATEWAY_INTERFACE	The revision of the CGI (Common Gateway Interface) specification with which this server complies.
HTTP_<header field name>	All HTTP headers that were not already parsed into one of the listed variables. These variables are of the form HTTP_<header field name>, for example: HTTP_ACCEPT: List of MIME types that the remote browser accepts. Values of the Accept: fields are concatenated, separated by a comma (,); for example, if the following lines are part of the HTTP header: accept: /; q=0.1 accept: text/html accept: image/jpeg then the HTTP_ACCEPT variable will have a value of: /; q=0.1, text/html, image/jpeg HTTP_USER_AGENT: The name of the remote client browser software. HTTP_REFERER: The uniform resource locator (URL) of the HTML document that referred the remote client to the current document. HTTP_ACCEPT_LANGUAGE: List of the human languages that the remote client can accept. HTTP_COOOKIE: Any cookie sent from the remote client.
LAST_MODIFIED	The date that the current document was last edited.
LOGON_USER	The user’s Windows NT account.
PATH_INFO	Additional path information, as given by the client. This information constitutes the trailing part of the URL after the script name but before the query string (if any).
PATH_TRANSLATED	The value of PATH_INFO, but with any virtual path name expanded into a directory specification.
QUERY_STRING	The information that follows the question mark (?) in the URL that referenced this script.
QUERY_STRING_UNESCAPED	The unescaped version of the search string.
REMOTE_ADDR	The IP address of the client.
REMOTE_HOST	The hostname of the client.
REMOTE_IDENT	The hostname of the client if it supports RFC931 identification.
REMOTE_USER	The user name supplied by the client and authenticated by the server.
SCRIPT_NAME	The name of the script program being executed.
SERVER_NAME	The server’s hostname (or IP address) as it should appear in self-referencing URLs.
SERVER_PORT	The TCP/IP port on which the request was received.
SERVER_PORT_SECURE	The value of 0 or 1. The value 1 indicates the request is on the encrypted port.
SERVER_PROTOCOL	The name and version of the information-retrieval protocol relating to this request, usually HTTP/1.0.
SERVER_SOFTWARE	The name and version of the Web server under which the Internet Server Extension is running.

Note You need to format DATE_LOCAL and DATE_GMT in the same way as the #FLASTMOD directive. For example:

This example inserts the current time into the stream.

See this sample file for another example.

#CONFIG <OPTION> = "string"

Sets the following three options to format output for various directives and situations:

ERRMSG: Controls the message returned to the client when an error occurs during the parsing or sending of the SSI. By default, the error message contains useful information and details about what went wrong. If the #CONFIG ERRMSG directive is called, the new message is a static string and will not contain any useful details on the error. The following example sets a standard error message:

TIMEFMT: Specifies the format in which dates should be sent to the client and takes the format specification the same way as the ANSI strftime function in C. With the strftime functionality, individual portions of the date (that is, the day of the week, month of the year) can be extracted. The following formatting tokens are available:

Token Description

%a Abbreviated weekday name.

%A Weekday name spelled out.

%b Abbreviated month name.

%B Month name spelled out.

%c Date and time representation appropriate for the locale.

%d Day of the month as a decimal number (01–31).

%H Hour in 24-hour format (00–23).

%I Hour in 12-hour format (01–12).

%j Day of the year as a decimal number (001–366).

%m Month as a decimal number (01–12).

%M Minute as a decimal number (00–59).

%p Current locale's A.M./P.M. indicator for 12-hour clock.

%S Second as a decimal number (00–59).

%U Week of year as a decimal number, with Sunday as first day of week (00–51).

%w Weekday as a decimal number (0–6; Sunday is 0).

%W Week of year as decimal, with Monday as first day of week (00–51).

%x Date representation for the current locale.

%X Time representation for the current locale.

%y Year without the century, as a decimal number (00–99).

%Y Year with century, as a decimal number.

%z, %Z Time-zone name or abbreviation; no characters if the time zone is unknown.

%% Percent sign.

Examples

The following example sets time to be displayed as hh:mm:ss (for example, 23:59:59):



The following example sets time to be displayed as mm/dd/yyyy (for example, 06/31/1996):



SIZEFMT: Displays the file size in either of two formats. The default value ABBREV displays file sizes as a count of kilobytes, and the value BYTES displays any file sizes as a count of bytes (1,234,567). The following example displays file sizes in bytes:

#EXEC <CGI / CMD / ISA> = "command description"

Executes the given CGI script, shell command, or ISAPI extension, and sends the output (standard output or ISAPI WriteClient data) into the HTML stream. The HTTP header (if it exists) in the output is read and interpreted, and any URL redirection messages are replaced by the message “This document has moved to ‘x’”. Any other header variables are ignored and not sent into the stream.

If the CGI tag is specified, then the command description is the virtual path of the CGI script. This script can be followed by a question mark (?) and parameters separated by plus (+) signs. The following example invokes Mkilog.exe parm1 parm2:

If CMD is specified, then the command description is the shell program to execute, followed by any command line parameters separated by spaces. The full path (a Windows NT path) of the program may be specified. If the full path is not specified, then the system path is searched. The following example invokes Rm.exe -?:

If ISA is specified, then the command description is the virtual path of the ISAPI extension DLL to execute. As with CGI scripts, parameters may be passed by using a question mark (?) followed by parameters separated by plus (+) signs. Because the execution of the ISAPI extension is only part of the .stm document, there are certain restrictions and issues to consider when writing the extension.
Any application attempting to send a URL or redirect through ServerSupportFunction will cause a message to be placed in the HTML stream, but the send-redirect will not be performed.
The SSI DLL will wait (indefinitely) for applications returning HSE_STATUS_PENDING until ServerSupportFunction is called to finish the session. The following example invokes W3test.dll:

See this sample file for another example.

Sample SSI Script

<HTML>
<HEAD>
<TITLE>TEST1.STM - Shallow test of SSI functionality</TITLE>
</HEAD>
<BODY>
<!--#include file="inc.txt"--><BR>
<!--#flastmod file="inc.txt"--><BR>
<!--#fsize file="test1.stm"--><BR>
<!--#echo var="DOCUMENT_URI"--><BR>
<!--#config timefmt="%m/%d/%y %H:%M:%S"--><BR>
<!--#echo var="DATE_LOCAL"--><BR>
<!--#config sizefmt="bytes"-->
<!--#fsize file="inc.txt"--><BR>
<!--#exec cgi="/scripts/testcgi.exe" --><BR>
</BODY>
</HTML>

Output of Sample SSI Script

This is the output of SSI script described in the “Sample SSI Script” section. For this example:

fsize( TEST1.STM ) = 661 bytes
fsize( INC.TXT ) = 33 bytes
content( INC.TXT ) = This is text from “inc.txt”
stdout( TESTCGI.EXE ) = This is output of TESTCGI.EXE

<HTML>
<HEAD>
<TITLE>TEST1.STM - Shallow test of SSI functionality</TITLE>
</HEAD>
<BODY>
This is text from "inc.txt"<BR>
Friday May 31 1996<BR>
0<BR>
/test1.stm<BR>
06/03/96 11:18:12<BR>
33<BR>
This is output of TESTCGI.EXE<BR>
</BODY>
</HTML>

Token	Description
%a	Abbreviated weekday name.
%A	Weekday name spelled out.
%b	Abbreviated month name.
%B	Month name spelled out.
%c	Date and time representation appropriate for the locale.
%d	Day of the month as a decimal number (01–31).
%H	Hour in 24-hour format (00–23).
%I	Hour in 12-hour format (01–12).
%j	Day of the year as a decimal number (001–366).
%m	Month as a decimal number (01–12).
%M	Minute as a decimal number (00–59).
%p	Current locale's A.M./P.M. indicator for 12-hour clock.
%S	Second as a decimal number (00–59).
%U	Week of year as a decimal number, with Sunday as first day of week (00–51).
%w	Weekday as a decimal number (0–6; Sunday is 0).
%W	Week of year as decimal, with Monday as first day of week (00–51).
%x	Date representation for the current locale.
%X	Time representation for the current locale.
%y	Year without the century, as a decimal number (00–99).
%Y	Year with century, as a decimal number.
%z, %Z	Time-zone name or abbreviation; no characters if the time zone is unknown.
%%	Percent sign.