Server-side include commands for HTTP Server

config

This command configures output formats and controls various aspects of the parsing. The valid attributes are:

echomsg

The value is a message that is sent back to the client if the echo element attempts to echo an undefined variable. This overrides any SSIUndefinedEcho directives.

For example:

<!--#config echomsg="[Value Undefined]" -->

errmsg

The value is a message that is sent back to the client if an error occurs while parsing the document. This overrides any SSIErrorMsg directives.

For example:

<!--#config errmsg="[Oops, something broke.]" -->

sizefmt

The value sets the format to be used when displaying the size of a file. Valid values are bytes for a count in bytes, or abbrev for a count in Kb or Mb as appropriate, for example a size of 1024 bytes will be printed as "1K"

For example:

<!--#config sizefmt="abbrev" -->

timefmt

The value is a string to be used by the strftime(3) library routine when printing dates.

For example:

<!--#config timefmt=""%R, %B %d, %Y"" -->

echo

This command prints one of the SSI variables defined below or environment variables. If the variable is unset, the result is determined by the SSIUndefinedEcho directive. Dates are printed using config timefmt. The attributes are:

var

Specifies a SSI variable name or standard CGI environment variable name.

See the Environment variables on HTTP Server topic for a list of environment variables.

For example:

<!--#echo var="DATE_GMT" -->

Table 1. SSI variables for the echo command, for if and elif, and to any program invoked by the document

Variable Name	Description
DATE_GMT	The current date in Greenwich Mean Time.
DATE_LOCAL	The current date in the local time zone.
DOCUMENT_ARGS	This variable contains the query string of the active SSI document, or the empty string if a query string is not included. For subrequests invoked through the include SSI directive, QUERY_STRING will represent the query string of the subrequest and DOCUMENT_ARGS will represent the query string of the SSI document.
DOCUMENT_NAME	The filename (excluding directories) of the document requested by the user.
DOCUMENT_URI	The (%-decoded) URL path of the document requested by the user. Note that in the case of nested include files, this is not the URL for the current document. Note also that if the URL is modified internally (e.g. by an Alias or DirectoryIndex), the modified URL is shown.
LAST_MODIFIED	The last modification date of the document requested by the user.
QUERY_STRING_UNESCAPED	If a query string is present in the request for the active SSI document, this variable contains the (%-decoded) query string, which is escaped for shell usage (special characters like & etc. are preceded by backslashes). It is not set if a query string is not present. Use DOCUMENT_ARGS if shell escaping is not desired.

decoding

Specifies whether HTTP Server should strip an encoding from the variable before processing the variable further. The default is none, where no decoding is done. If set to url, then URL decoding (also known as %-encoding) is performed. If set to urlencoded, application/x-www-form-urlencoded compatible encoding (found in query strings) is stripped. If set to base64, base64 is decoded, and if set to entity, HTML entity encoding is stripped. Decoding is done prior to any further encoding on the variable. Multiple encodings can be stripped by specifying more than one comma separated encoding. The decoding setting will remain in effect until the next decoding attribute is encountered, or the element ends.

The decoding attribute must precede the corresponding var attribute to be effective.

For example:

<!--#echo decoding="none" var="QUERY_STRING" -->

encoding

Specifies how the HTTP Server encodes special characters contained in the variable before outputting them. If set to none, no encoding is done. If set to url, then URL encoding (also known as %-encoding) is performed. If set to urlencoded, application/x-www-form-urlencoded compatible encoding is performed instead, and should be used with query strings. If set to base64, base64 encoding is performed. At the start of an echo element, if set to the default of entity, then entity encoding is performed. This can be changed by adding an encoding attribute, which will remain in effect until the next encoding attribute is encountered or the element ends, whichever comes first.

The encoding attribute must precede the corresponding var attribute to be effective.

For example:

<!--#echo encoding="entity" var="QUERY_STRING" -->

Note: In order to avoid cross-site scripting issues, you should always encode user supplied data.

exec

This command calls a CGI program. If Options IncludesNOEXEC is set, this command is completely disabled. The attributes are:

cgi

Specifies the relative path and file name using URL encoding. If the path does not begin with a slash (/), then it is taken to be relative to the current document.

For example:

<!--#exec cgi="/cgi-bin/counter.pgm" -->

If the script returns a Location: header instead of output, then this will be translated into an HTML anchor.

The include virtual element should be used in preference to exec cgi. In particular, if you need to pass additional arguments to a CGI program, using the query string, this cannot be done with exec cgi, but can be done with include virtual, for example:

<!--#include virtual="/cgi-bin/example.pgm?argument=value" -->

fsize

This command prints the size of the specified file according to config sizefmt. The attributes are:

file

Specifies the relative path and file name. For example:

<!--#fsize virtual="/include/include.htm" -->

Note: The value of file cannot start with a slash (/), nor can it contain ../ so as to refer to a file above the current directory or outside of the document root.

virtual

Specifies the relative path and file name using URL encoding. If it does not begin with a slash (/) then it is taken to be relative to the current document. For example:

Note: This does not print the size of any CGI output, but the size of the CGI script itself.

<!--#fsize virtual="/include/include.htm" -->

flastmod

This command prints the last modification date of the specified file according to config timefmt. The attributes are:

file

Specifies the relative path and file name. For example:

<!--#flastmod file="/include/include.htm" -->

Note: The value of file cannot start with a slash (/), nor can it contain ../ so as to refer to a file above the current directory or outside of the document root.

virtual

Specifies the relative path and file name using URL encoding. If it does not begin with a slash (/) then it is taken to be relative to the current document.

Note: This does not print the size of any CGI output, but the size of the CGI script itself.

For example:

<!--#flastmod virtual="/include/include.htm" -->

global

This command is the same as the set command.

include

This command inserts the text of another document or file into the parsed file. Included files can be nested. The attributes are:

file

Specifies the relative path and file name. It cannot contain ../, nor can it be an absolute path. Therefore, you cannot include files that are outside of the document root, or above the current document in the directory structure. The virtual attribute should always be used in preference to this one.

For example:

<!--#include file="/include/include.htm" -->

virtual

Specifies the relative path and file name using URL encoding. The value cannot contain a scheme or hostname, only a path and an optional query string. If it does not begin with a slash (/) then it is taken to be relative to the current document.

For example:

<!--#include virtual="/include/include.htm" -->

If the specified value is a CGI program, the program will be executed and its output inserted in place of the directive in the parsed file. You may include a query string in a CGI url.

For example:

<!--#include virtual="/cgi-bin/example.pgm?argument=value" -->

include virtual should be used in preference to exec cgi to include the output of CGI programs into an HTML document.

If the KeptBodySize directive is correctly configured and valid for this included file, attempts to POST requests to the enclosing HTML document will be passed through to subrequests as POST requests as well. Without the directive, all subrequests are processed as GET requests.

onerror

Using (%-encoded) URL-path to show a previous attempt to include a file or virtual attribute failed. For example:

<!--#include virtual="/not-exist.html" onerror="/error.html" -->

printenv

This command prints all existing environment variables and their values. Special characters are entity encoded (see the echo element for details) before being output. There are no attributes. For example:

<!--#printenv -->

set

This command sets the value of an environment variable. The attributes are:

var

Specifies an environment variable name.

See Environment variables set by HTTP Server for a list of environment variables.

value

Specifies the value to assign to the environment variable name. For example:

<!--#set var="var1" value="yes" -->

If you want to use the value of standard environment variables or SSI variables like LAST_MODIFIED to set your environment variable, use the dollar sign ($) before the name of the variable. For example:

<!--#set var="modified" value="$LAST_MODIFIED" -->

If you want to insert a special character(i.e. dollar sign) in a string, precede it with a backslash . For example:

<!--#set var="cost" value="\$100" -->

decoding

Specifies whether HTTP Server should strip an encoding from the variable before processing the variable further. The default is none, where no decoding is done. If set to url, urlencoded, base64 or entity, URL decoding, application/x-www-form-urlencoded decoding, base64 decoding or HTML entity decoding is performed respectively. More than one decoding can be specified by separating with commas. The decoding setting will remain in effect until the next decoding attribute is encountered, or the element ends. The decoding attribute must precede the corresponding var attribute to be effective.

For example:

<!--#set decoding="none" var="val" value="$QUERY_STRING" -->

encoding

Specifies how HTTP Server encodes special characters contained in the variable before setting them. The default is none, where no encoding is done. If set to url, urlencoding, base64 or entity, URL encoding, application/x-www-form-urlencoded encoding, base64 encoding or HTML entity encoding is performed respectively. More than one encoding can be specified by separating with commas. The encoding setting will remain in effect until the next encoding attribute is encountered, or the element ends. The encoding attribute must precede the corresponding var attribute to be effective. Encodings are applied after all decodings have been stripped.

For example:

<!--#set encoding="entity" var="val" value="$QUERY_STRING" -->

Conditional commands

The basic flow control commands are:

<!--#if expr="test_condition" -->
<!--#elif expr="test_condition" -->
<!--#else -->
<!--#endif -->

There are four conditional or flow control commands. The if command tests a value. If the value is true, then processing continues with the next line. If the value is not true then processing continues with an elif, else, or endif command. The elif and else commands are optional. The if and elif commands have a parameter of expr. The expr parameter contains the test condition. An endif command is required for every if command. For example:

<!--#if expr="$USER_AGENT = /MSIE/" -->
<P>You are using Internet Explorer.</P>
<!--#elif expr="$USER_AGENT = /Mozilla/" --> 
<P>You are using Netscape.</P> 
<!--#else -->
<P>You are not using Internet Explorer or Netscape.</P>
<!--#endif -->

The test_condition of expr parameter is a boolean expression which now follows the new ap_expr syntax. The syntax can be changed to be compatible with HTTP server on older IBM i releases by using directive SSILegacyExprParser.

The SSI variables set with the var element are exported into the request environment and can be accessed with the reqenv function. As a short-cut, the function name v is also available inside mod_include . The below example will print "from local net" if client IP address belongs to the 10.0.0.0/8 subnet.

<!--#if expr='-R "10.0.0.0/8"' -->
from local net
<!--#else -->
from somewhere else
<!--#endif --> 

The below example will print "foo is bar" if the variable foo is set to the value "bar".

<!--#if expr='v("foo") = "bar"'-->
foo is bar
<!--#endif --> 

Legacy expression syntax

This section describes the syntax of the #if expr parameter if SSILegacyExprParser is set to on.

<!--#if expr="-A /private" -->
Click <a href="/private">here</a> to access private information.
<!--#endif -->

<!--#if expr="$QUERY_STRING = /^sid=([a-zA-Z0-9]+)/" -->
<!--#set var="session" value="$1" -->
<!--#endif -->

Variable substitution

Values can be supplied in the following ways:

• Test can be supplied within a quoted string. For example:

  <!--#config timefmt="%b%d%y" -->

• A literal dollar sign can be supplied in a string using a backslash. For example:

  <!--#ifexpr="$a=\$test" -->

• A variable reference can be supplied within a character sequence using braces. For example:

  <!--#set var="ABC" value="${REMOTE_HOST}_${REQUEST_METHOD}" -->

  If REMOTE_HOST is equal to X and REQUEST_METHOD is equal to Y, then $ABC is equal to X_Y.

Additional notes

Server-side includes look for the variable, echoes where the variable is found, and proceeds with the function. You can have multiple variable references. When server-side includes encounter a variable reference inside a server-side include directive, it attempts to resolve it on the server side. The following example escapes the & so that server-side includes do not recognize it as a variable. In the second line of the example, the variable "&index" is a server-side variable and is used to construct the variable name "var1". The variable ê is a client side variable, so the & is escaped to create the value ":frêd" or "fred" with a circumflex over the e.

<!--#set var="index" value="1"  --> 
<!--#set var+"var&index;" value+"fr\&ecirc;d" --> 
<!--#echo var="var1" --> 

The following characters can be escaped. Escape variables must be preceded with a backslash (\).