Next: Security Up: Dynamic Documents Previous: Security aspects

NCSA server side includes

Server side includes are a non-standard server extension implemented in the NCSA server, and allow dynamically generated information to be inserted into HTML documents. The information to be inserted is specified by special directives embedded in HTML comments. The directives take the form:

    <!-#directive tag="value" ... ->

Server side includes are described in NCSA's online documentation.

The directives recognized by the NCSA server are:

echo

Includes the value of an environment variable, whose name is specified by the var tag. These variables can be CGI variables or one of the following variables defined by the NCSA server:

DATE_GMT

The current date and time in Greenwich Mean Time, formatted according to the format string specified with the config timefmt directive.

DATE_LOCAL

The date and time in the local time zone, formatted according to the format string specified with the config timefmt directive.

DOCUMENT_NAME

The filename of the current document.

DOCUMENT_URI

The virtual path of the current document.

LAST_MODIFIED

The date and time at which the current document was last updated, formatted according to the format string specified with the config timefmt directive.

QUERY_STRING_UNESCAPED

Contains the same information as stored in the standard CGI QUERY_STRING environment variable, but all shell meta-characters are escaped with a backslash.

If a variable that does not exist is specified, the string `(None)' is output.

include

Includes a file or virtual document in the output. The file tag is used to specify the name of a file, which must be a relative pathname from the current directory of the script and cannot use the ../ to refer to parent directories. The virtual tag is used to specify the URL of a virtual document.

fsize

Inserts the file size of a file or virtual document. The file or virtual tags are used and have the same meaning as for the include directive.

flastmod

Inserts the last-modified time of the file or virtual document. The file or virtual tags are used and have the same meaning as for the include directive.

exec

Inserts the output from a shell command if the cmd tag is specified, or from a CGI script if the cgi tag is specified, into the output.

Certain aspects of these directives can be configured by the config directive, which can take the following tags:

errmsg

Specifies the error message that is printed if an error is detected in a directive. By default this is:

    [an error occurred while processing this directive]

sizefmt

Specifies the format in which file sizes are output with the fsize directive. Legal values are bytes to output the number of bytes, or abbrev to express the size in whole kilobytes or megabytes.

timefmt

Specifies the format used for printing times. This is a UNIX strftime format string. The string can contain literal text and date component specifiers, which consist of a per cent symbol (%) followed by a single character. These strings are expanded as follows:

%%

A literal per cent symbol (%).

%a

The abbreviated name of the day of the week.

%A

The full name of the day of the week.

%b

The abbreviated name of the month.

%B

The full name of the month.

%c

An appropriate date and time representation.

%C

The date and time representation as produced by the UNIX date command.

%d

The numeric day of the month (single digit days are preceded by a zero).

%D

The date expressed as %m/%d/%y.

%e

The numeric day of the month (single digit days are preceded by a blank).

%h

The abbreviated name of the month.

%H

The hour (two digits, 00-23).

%I

The hour (two digits, 01-12).

%j

The day number within the year (three digits, 001-366).

%m

The month number (01-12)

%M

The minute (00-59)

%n

A new-line character.

%p

AM or PM, or a local equivalent.

%r

The time expressed as %I:%M:%S %p.

%R

The time expressed as %H:%M.

%S

Seconds (00-61), allows for leap seconds.

%t

A tab character.

%T

The time represented as %H:%M:%S.

%U

The week number of the year (00-53, where Sunday is the first day of week 1).

%w

The weekday number (0-6, where Sunday is represented by 0).

%W

The week number of the year (00-53, where Monday is the first day of week 1).

%x

An appropriate date representation.

%X

An appropriate time representation.

%y

The year within the current century (two digits, 00-99).

%Y

The four digit year.

%Z

The time zone name or no characters if the time zone is unknown.

Note that although new-lines and tab characters can be represented in a date specification, they are only significant if the server include directive occurs in pre-formatted text.

The default time format is:

    "%A, %d-%b-%y %T %Z"

which expands to a date and time of the form:

    Wednesday, 16-Nov-94 19:26:31 GMT

The full and abbreviated names of months and years and what is regarded as an appropriate representation of the date and/or time depends on the operating system configuration; for example if configured for a German site the %x date component specifier may output the string:

    Freitag, den 13. Januar 1995

for Friday, 13th January 1995.

There are a number of problems with NCSA server side includes. The NCSA server is very unforgiving about the syntax of server side includes. Error handling is not consistent and invalid directives may cause an error message to be inserted in the HTML document or even prevent the rest of the document from being delivered. Server side includes are a non-standard extension and consequently restrict the portability of Web documents to other types of server. They can put a considerable load on the server, in performance terms, if heavily used or enabled for all documents on the server, and for all these reasons I would recommend that they be used with restraint, if at all.

Spinning the Web by Andrew Ford
© 1995 International Thomson Publishing
© 2002 Andrew Ford and Ford & Mason Ltd
Note: this HTML document was generated in December 1994 directly from the LaTeX source files using LaTeX2HTML. It was formatted into our standard page layout using the Template Toolkit. The document is mainly of historical interest as obviously many of the sites mentioned have long since disappeared.