Using Server Side Directives

Everyone knows about the #include directive that allows a file's contents to be inserted into another page before execution. But did you know that there are several other directives available as well?

There is a catch though... You can't use any of the other directives in an ASP page. Instead you need to use one of three special html extensions on any file that you want to use server side directives. The downside is, these files will no longer be ASP files and will be unable to execute server-side code. There is a way around that though which I will get into later...

Acceptable File Extensions

As I mentioned above, there are three extensions that are set to use Server Side Directives by default in IIS. They are *.stm *.shtm and *.shtml. You can set up other extensions to use SSI's but that is out of the scope of this document. Just to make your life easier and begin testing, use the default extensions since they will work on most IIS Servers (including PWS!).

Once you have created a new file with one of the three extensions above, you have nothing more than a simple HTML file with one special catch: before IIS serves this document, it will process any server-side directives found in the HTML. Enough of this background info... Let's get into the directives.

Server Side Directives

There are five other directives available to a programmer (not including #include) using server-side directives:

#config
#echo
#fsize
#flastmod
#exec

The #config Directive

The #config directive allows you to format error messages, dates and file sizes. While this is useless on it's own, formatting dates, times, error messages and file sizes will be important later when using other server-side directives to return information.

errmsg

Whenever a server-side include is executed, if an error occurs, the system will return a text error message specifying the problem in place of the directive when serving the document to a user. This message is usually very specific to aid a developer in debugging code. These descriptive error messages can be supressed with the #config directive like so:

	<-- #config errmsg = "This feature is unavailable!" -->

Setting the above #config directive at the top of an SSI document will replace the useful error message with the new message specified above if an error occurs processing any directives following this one. This is useful to hide errors from users when a document is served.

sizefmt

To change the format of file sizes returned by other directives, you can also use the #config directive. There are two ways to display file sizes: as bytes or kilobytes (k). Changing the format of file sizes is achieved like this:

sets the default for file sizes to bytes
	<-- #config sizefmt = "bytes" -->


sets the default for file sizes to kilobytes
	<-- #config sizefmt = "abbrev" -->

timefmt

The timefmt parameter of the #config directive provides a very flexible way to extract and format dates and times. The functionality of this parameter makes ASP's FormatDateTime() function look pretty weak by comparison but offers relatively the same formatting tools as the DateTimeFormatInfo class in .NET has.

The following table explains the available arguments for timefmt: (You can use as many arguments as you need to in the same #config directive)

formatting token	description
%a	Abbreviated name for day of the week (for example, Mon).
%A	Complete name for day of the week (for example, Monday).
%b	Abbreviated month name (for example, Feb).
%B	Complete month name (for example, February).
%c	Date and time representation that is appropriate for the locale (for example, 05/06/91 12:51:32).
%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. or P.M. indicator for 12-hour format (for example, PM).
%S	Second as a decimal number (00-59).
%U	Week of the year as a decimal number, with Sunday as the first day of the week (00-51).
%w	Day of the week as a decimal number, with Sunday as the first day (0-6).
%W	Week of the year as a decimal number, with Monday as the first day of the week (00-51).
%x	Date representation for the current locale (for example, 05/06/91).
%X	Time representation for the current locale (for example, 12:51:32).
%y	Year without the century as a decimal number (for example, 69).
%Y	Year with the century as a decimal number (for example, 1969).
%z, %Z	Time-zone name or abbreviation; no characters if time zone is unknown.
%%	Percent sign.

Some example usage of timefmt:

sets the default date display to:
    DayName MonthName DayNumber, FullYear
    like: Monday January 14, 2000
	<-- #config timefmt = "%A %B %d, %Y" -->


sets the default time to:
    hour:minutes:seconds AM/PM
    like: 12:10:00 PM
	<-- #config timefmt = "%X %p" -->

sets the default to:
    the number of day's since Jan 1 for this day.
    like: 32 for February 1st
	<-- #config timefmt = "%j" -->

The #echo Directive

The #echo directive provides access to enviromental variables. What are environmental variables? They are the same set of variables returned by ASP's Request.ServerVariables collection. The #echo directive provides access to this collection outside of an ASP page. There are a couple of items available through using #echo that cannot be used via ASP's ServerVariables collection and vice-versa.

Environmental variables available via Request.ServerVariables method in ASP

Environmental variables available via the #echo directive in non-ASP pages

ALL_HTTP ALL_RAW APPL_MD_PATH APPL_PHYSICAL_PATH AUTH_PASSWORD AUTH_TYPE AUTH_USER CERT_COOKIE CERT_FLAGS CERT_ISSUER CERT_KEYSIZE CERT_SECRETKEYSIZE CERT_SERIALNUMBER CERT_SERVER_ISSUER CERT_SERVER_SUBJECT CERT_SUBJECT CONTENT_LENGTH CONTENT_TYPE GATEWAY_INTERFACE HTTPS HTTPS_KEYSIZE HTTPS_SECRETKEYSIZE HTTPS_SERVER_ISSUER HTTPS_SERVER_SUBJECT INSTANCE_ID INSTANCE_META_PATH LOCAL_ADDR LOGON_USER PATH_INFO PATH_TRANSLATED QUERY_STRING REMOTE_ADDR REMOTE_HOST REMOTE_USER REQUEST_METHOD SCRIPT_NAME SERVER_NAME SERVER_PORT SERVER_PORT_SECURE SERVER_PROTOCOL SERVER_SOFTWARE URL HTTP_ACCEPT HTTP_ACCEPT_LANGUAGE HTTP_CONNECTION HTTP_HOST HTTP_USER_AGENT HTTP_COOKIE HTTP_ACCEPT_ENCODING

ALL_HTTP AUTH_PASSWORD AUTH_TYPE AUTH_USER CONTENT_LENGTH CONTENT_TYPE DOCUMENT_NAME DOCUMENT_URI DATE_GMT DATE_LOCAL GATEWAY_INTERFACE HTTP_ACCEPT LAST_MODIFIED PATH_INFO PATH_TRANSLATED QUERY_STRING QUERY_STRING_UNESCAPED REMOTE_ADDR REMOTE_HOST REMOTE_USER REQUEST_METHOD SCRIPT_NAME SERVER_NAME SERVER_PORT SERVER_PORT_SECURE SERVER_PROTOCOL SERVER_SOFTWARE URL

Some example usage of the #echo directive:

returns the last modified date of this file
	<-- #echo var = "LAST_MODIFIED" -->


get the URI path of this file
	<-- #echo var = "DOCUMENT_URI" -->


show the query-string used on this page (not url-encoded)
	<-- #echo var = "QUERY_STRING_UNESCAPED" -->

The #exec Directive

Remember when I said an SSI page couldn't execute ASP code? Well the #exec directive can execute anything from an ASP page or other script to a shell command and places the results in the HTML file. #exec is usually DISABLED by most ASP hosts on the WWW due to the danger of using an #exec directive but some will allow use of the cgi parameter. I don't think you will find any that allow the cmd parameter though. The default IIS setup on an NT box allows the cgi parameter of #exec but not the cmd parameter. By default PWS on Windows 98 allows both so be careful!

cgi

Normally a programmer includes ASP files using the #include directive. This works great on an ASP page since all the code will execute via your favorite scripting engine (VBScript, JScript, PerlScript...) but a non-ASP page can't handle server-side code so using the #include directive in this case is worthless.

The #exec directive can handle this problem. Say you had an ASP file that you needed to execute but didn't want to directly call that file... (if it wasn't in your public web-site directory space, for example) you can use the #exec directive to execute the ASP file and put the results of the execution into the SSI web page.

This method works out sweetly if you need to execute a *.VBS file or other script that IIS will not process when requested via the web. To use the #exec directive to process a SCRIPT, the format is as follows:

	<-- #exec cgi = "./script.asp" -->

	<-- #exec cgi = "C:\windows\desktop\script.vbs" -->

There is an important exceptions when using #exec to execute a script: server-side redirects will not work ...

cmd

The #exec directive also allows access to the Windows Shell. This isn't the only way to access the Windows Shell. I wrote a VBScript shell statement that will do almost the same thing via ASP (assuming your server has Windows Script 5.5 installed and light [default] security permissions). You can get it here: Shell Statement

Before we go on... Shell access is DANGEROUS. You can re-format the hard drive, delete files, etc... anything you can do from the Windows command prompt. If you don't know DOS, don't play around with this one. Haphazardly typing commands can result in SEVERE DAMAGE to your server that may require reformatting and re-installation of everything. Still, you should at least know about it, even though it should be used very sparingly and as a last resort ...

As a result of these security issues, the #exec cmd directive is DISABLED by default in IIS (not in PWS though!).

open notepad (on the server) and open the file "script.asp" on the server's desktop...
	<-- #exec cmd = "C:\windows\notepad C:\windows\desktop\script.asp" -->

You should note that the #exec directive would not stop processing until the file opened above in Notepad was closed manually by the user. #exec will keep processing until something is returned to the html page by the executed command.

The #flastmod Directive

The #flastmod directive returns the last modified date of any file on the server. You can modify the display of #flastmod with the #config directive.

Some example usage of the #flastmod directive:

	<-- #flastmod File = "../../directory/database.mdb" -->

	<-- #flastmod File = "c:\WINNT\system\scrrun.dll" -->

	<-- #flastmod Virtual = "/directory/directory/database.mdb" -->

The #fsize Directive

The #fsize directive returns the size of any file on the server. You can modify the display of #fsize with the #config directive.

Some example usage of the #fsize directive:

	<-- #fsize File = "../../directory/database.mdb" -->

	<-- #fsize File = "c:\WINNT\system\scrrun.dll" -->

	<-- #fsize Virtual = "/directory/directory/database.mdb" -->

The #include Directive

The #include directive includes the contents of a file into another file. The #include directive is the only directive that can be used in an ASP page as well as in an SSI enabled HTML page.

	<-- #include File = "../../directory/file.txt" -->

	<-- #include File = "c:\WINNT\system\file.asp" -->

	<-- #include Virtual = "/directory/directory/file.asp" -->