APPENDIX E

The next sections describe each of these commands and how they work; entries in italics are variables to be set by the document author. Table E.1 summarizes the commands and the allowed forms.

As of the Apache 1.3.12 server, this directive also takes an encoding argument to specify how special characters in the string should be encoded before they are output. There are three possible values:

encoding="none". No encoding of the data is done.

encoding="url". The data will be encoded as if it were URL data (e.g., spaces will be encoded as the sequence %20).

encoding="entity". Any special HTML characters are encoded using entity references. This is the default encoding value.

Once an encoding value is set, any subsequent var is encoded as indicated. This means that if you want to set the encoding for a specific variable, then the encoding argument must be set before you name the variable. That is, the statement must be written as:

<!--#echo encoding="type" var="var_name" -->

Back to top

E.1.3 Fsize: Include Size of Listed File

This includes the size, in bytes, of a file—the file can be specified using either the file or virtual arguments, as described in the include command section. Fsize is useful for presenting information about a file to be downloaded, particularly when the size varies often. For example:

archive: (<!--#fsize file="main.html" --> bytes)

The output format is set by the sizefmt argument of the config command.

Back to top

E.1.4 Flastmod: Include Last Modification Time of Listed File

This includes the last modification time of a file specified using the file or virtual arguments, as described in the include command section. Like fsize, flastmod is useful for providing up-to-date information about files that are periodically changed. For example:

<!--#flastmod virtual="/path/dir1/dir2/main.html" -->

The output format is determined by the timefmt argument of the config command.

Back to top

E.1.5 Exec: Execute Shell Script of CGI Program

This directive executes the indicated Bourne shell command or CGI program, and includes the program output inline in the document. The two possible arguments are:

cmd="cmd_string". Causes the string cmd_string to be executed using the Bourne shell (sh). Cmd_string can be a simple one-line shell program that does simple tasks, such as listing directory contents or running a program to filter data for inclusion. The SSI directive is replaced by the output of the shell program. This form is allowed only to support legacy SSI programs—newer SSI pages should avoid cmd and should use cgi instead.

cgi="cgi_program". Executes the given CGI program, where the location of the program is given by the virtual path to the program. Recall that the SSI directive is replaced by the output of the program. Also note that the script must return a valid Multipurpose Internet Mail Extensions (MIME) content type. You cannot pass query strings or path information to the script using the standard URL mechanisms. Thus, expressions like

are invalid. The only way you can access the script is with the command:

However, suppose the parsable script stuff.shtml contains the command

and you access the file stuff.shtml via a URL of the form:

In this case, the query_string and /extra/path information are available to the script script.cgi called from stuff.shtml. This is illustrated in an example at the end of this section.

The exec cgi mechanism is supported for legacy reasons only: New documents should use the include virtual directive instead.

Back to top

Environment Variables Within Exec’ed CGIs

The variables defined in Table E.2 are also available within gateway or shell programs that are executed using the exec command. In addition, any extra path or query information appended to the parsed HTML document name is passed to the CGI program within the PATH_INFO and QUERY_STRING variables, as per standard practice. At the same time, several servers define additional environment variables to provide information about the executing script. The most common of these additional variables are given in Table E.3. These variables are defined by Apache (Version 1 and greater) and Netscape/iPlanet servers (and probably by others), but not by NCSA servers prior to version 1.5.

Back to top

E.1.6 Config—Set SSI Configuration Settings

This directive controls aspects of the output of the other parsed commands, such as the formats of the date and size output strings, or the error message string to include if parsing fails. Config can take three different arguments, one argument per command. These are

errmsg="error_string". Sets the error message to use if there is an error in parsing the parsable commands.

timefmt="format". Sets the format for printing dates. This format is specified as per the C strftime library (strftime is commonly found on Unix computers).

sizefmt="bytes","abbrev". Sets the format for the specification of file sizes. The value bytes prints file sizes in bytes, while abbrev uses kilobytes or megabytes as abbreviated forms, where applicable.

Some examples of config format specifications are:

<!--#config errmsg="Unable to parse scripts" -->

Back to top

E.1.7 Printenv: Print All Environment Variables

This directive, added with the Apache 1.2 server, prints out all the environment variable names and their values, one per line, using the format

VARIABLE_NAME=value. This is useful when diagnosing problems with SSI documents.

Back to top

E.1.8 Set: Set Value for a Variable

This directive, added with the Apache 1.2 server, lets you create a variable and assign it a string value. The syntax is:

<!--#set var="var_name" value="var_value" -->

where the meanings are obvious. These variables can be referenced by name from within echo statements. For example:

Value for "stuff" is: <!--#echo var="stuff" -->

These values (and any defined environment variables) can also be referenced within config, exec, flastmod, fsize, include, and set directives, but only by prepending a dollar sign in front of the variable name. For example, the directive

<!--#set var="test" value="This is $stuff$DATE_GMT" -->

sets the variable test to be equal to the string "This is" followed by the value of the variable stuff, followed by the value of the DATE_GMT environment variable. If the variable name appears inside a string, then the start and end of the variable name can be delimited by curly brackets, as in:

<!--#set var="test" value="This is ${DATE_GMT}easy " -->

Back to top

E.2 Conditional SSI Blocks

Apache 1.2 and later versions support conditional SSI directives, where only the markup inside "true" blocks is included when the document is served out. The blocks work like regular if and else if statements, as in the following simple example:

First block of markup

Second block of markup

Third block of markup

<!--#endif -->

If test-expression-1 is true, then the first block of markup is included in the document, while the second and third blocks are discarded. On the other hand, if test-expression-1 is false and test-expression-2 is true, then the second block of markup is included in the document, while the first and third blocks are discarded. Finally, if both test-expression-1 and test-expression-2 are false, then the third block of markup is included, and the first and second are discarded.

The test expressions test the value of strings (there are no numeric operations or comparisons). For details, please see the Apache server document listed in the references.

Back to top

E.3 References