FAQ - SSI - Server Side Includes

Server-side include (SSI) files add text, graphic, or application information to an HTML document just before sending the HTML file to a user. SSI can be used to include, for example, a time/date stamp, a "tip of the day," or a form for a recipient to fill out and return.

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

Directive

Description

#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 inserts 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) and Microsoft Peer Web Services (PWS) version 2.0 to NCSA HTTPd and other Web servers.

In IIS and PWS 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 the Web server.

Note SSI works only on Microsoft Windows NT version 4.0.

Setting Up SSI

Requests for .stm files (include 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. To set up SSI, you must:

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

DLL Mapping

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

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 a 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 Internet Service Manager or append the following value to the 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

The Basic Include Statement

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 graphic, a form, or an application.
Write an include statement in the HTML documents in which you want the common text or form inserted.
Make sure that the documents with the include statements have an .stm extension.

The format for the basic include statement is:

Note The Active Server Pages 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 by use of 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:

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:

#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).

#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> = "string" later on this page.

#ECHO <VAR> = "variable"

Includes the value of the variable specified by VAR into 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_UNESCA PED

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:

inserts the current time into the stream.

#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, 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, the system path is searched. The following example invokes Rm.exe -?:

If ISA is specified, the command description must be the virtual path of the ISAPI extension DLL to execute. As with CGI scripts, parameters can 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:

Sample SSI Script

<HTML>

<HEAD>

<TITLE>TEST1.STM - Shallow test of SSI functionality</TITLE>

</HEAD>

<BODY>

 

 

 

 

 

 



 

 

</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" 

Friday May 31 1996 

0 

/test1.stm 

06/03/96 11:18:12 

33 

This is output of Testcgi.exe 

</BODY>

</HTML>


	To Order Call 1-250-276-4349 or use our Sales Inquiry Form. © Secure Information Systems Ltd. All Rights Reserved.