[next] [previous] [contents] [full-page]4.1 - Virtual Documents
4.2 - Last-Modified Information
4.3 - Pre-Expiring Documents
4.4 - Directive Syntax
4.5 - Directives
4.5.1 - #ACCESSES
4.5.2 - #CONFIG
4.5.3 - #DIR
4.5.4 - #DCL
4.5.5 - #ECHO
4.5.6 - #ELIF
4.5.7 - #ELSE
4.5.8 - #ENDIF
4.5.9 - #EXEC
4.5.10 - #EXIT
4.5.11 - #FCREATED
4.5.12 - #FLASTMOD
4.5.13 - #FSIZE
4.5.14 - #IF
4.5.15 - #INCLUDE
4.5.16 - #MODIFIED
4.5.17 - #ORIF
4.5.18 - #PRINTENV
4.5.19 - #SET
4.5.20 - #SSI
4.5.21 - #STOP
4.6 - Variables
4.7 - Flow Control
4.8 - Query Strings
4.9 - File and Virtual Specifications
4.9.1 - THE_FILE_NAME
4.10 - Time Format
4.11 - OSU Compatibility
The HTML pre-processor is used to provide dynamic information inside of an otherwise static, HTML (HyperText Markup Language) document. The HTTPd server provides this as internal functionality, scanning the input document for special pre-processor directives, which are replaced by dynamic information based upon the particular directive.
As of version 5.1 WASD SSI has been enhanced to provide flow-control statements, allowing blocks of the document to be conditionally processed, see 4.7 - Flow Control. These extensions allow quite versatile documents to be created without resorting to script processing.
Two documents are provided as examples of SSI processing.
By default the HTML pre-processor is invoked when the document file's extension is ".SHTML". As there is a significant overhead with pre-processed HTML compared to normal HTML, it should only be used when it serves a useful documentary purpose, and not just for the novelty.
Essential compatibility with OSU Server Side Includes is provided. This
may ease any transition between the two. See 4.11 - OSU Compatibility for
further information.
4.1 - Virtual Documents
One effective use for pre-processed HTML is the creation of single
virtual documents from two or more physical documents. That is, the
pre-processed document is used to include multiple physical documents, that
may even be independently administered, to return a composite document to the
client. This is a relatively low-overhead activity as SSI goes, but because it
is a dynamic document, without some extra considerations (see
4.2 - Last-Modified Information).
Example 1
This provides an example of the efficient use of SSI processing to create
virtual documents. Each page will comprise a header (containing the body tag
and page header, etc), the document proper and a footer (containg the
end-of-page information, modification date, and end-body tag, etc).
<HTML>
<HEAD>
<TITLE>Just an example!</TITLE>
</HEAD>
<!--#include virtual="header.shtml" -->
<P> This is the document information.
<P> Blah, blah, blah.
<!--#include virtual="/web/common/footer.shtml" -->
</HTML>
A more efficient variant places the document proper in it's own, plain HTML
file which is then #included (it is much, much, much more efficient for the
server to throw a file at the network, than parse every character
in one ;^)
<HTML>
<HEAD>
<TITLE>Just an example!</TITLE>
</HEAD>
<!--#include virtual="header.shtml" -->
<!--#include virtual="example.html" -->
<!--#include virtual="footer.shtml" -->
</HTML>
Example 2
This example provides a seemingly more convoluted, but very much more powerful configuration, that uses recursion to greatly simplify maintenance of common-layout documents for the end-user.
File 1; the document accessed via the browser URL, doesn't matter what
it's name is, this configuration is completely naming independent.
<!--#ssi
#if var={PARENT_FILE_NAME} eqs=""
#set var=TITLE value="Just an Example"
#include virtual="/web/common/template.shtml"
#else
#include virtual="document.html"
#endif
-->
File 2; the TEMPLATE.SHTML refered to by the first include above.
<!--#ssi
#include virtual="/web/common/header.shtml"
#include virtual="{DOCUMENT_ROOT}header.html" fmt="?"
#include virtual="{DOCUMENT_URI}"
#include virtual="{DOCUMENT_ROOT}footer.html" fmt="?"
#include virtual="/web/common/footer.shtml"
-->
File 3; the DOCUMENT.HTML refered to by the second include in file 1.
<P> This is just a <B>bunch of HTML</B>!
This is an explanation of how it works ...
The following link provides an example of a
such a virtual document.
4.2 - Last-Modified Information
SSI documents generally contain dynamic elements, that is those that may change with each access to the document (e.g. current date/time). This makes evaluation of any document modification date difficult and so by default no "Last-Modified: timestamp" information is supplied against an SSI document. The potential efficiencies of having document timestamps, so that requests can be made for a document to be returned only if modified after a certain date/time ("If-Modified-Since: timestamp"), are significant against the CPU overheads of processing SSI documents.
WASD allows the document author to determine whether or not a last-modified header field should be generated for a particular document and which contributing file(s) should be used to determine it. This is done using the #modified directive. If a virtual document is made up of multiple source documents (files) each can be assessed using multiple virtual= or file= tags, the most recently modified will be used to determine if the virtual document has been modified, and also to generate the last-modified timestamp.
The if-modified-since tag compares the determined revision date/time of the document file(s) with any "If-Modified-Since:" timestamp supplied with the request. If the virtual document's revision date/time is the same or older than the request's then a not-modified (304 status) header is generated and sent to the client and document processing ceases. If more recent an appropriate "Last-Modified:" header field is added to the document and it continues to be processed.
If a request has a "Pragma: no-cache" field (as with Navigator's
reload function) the document is always generated (this is
consistent with general WASD behaviour).
The following example illustrates the essential features.
<!--#ssi
#modified
#modified virtual="/web/common/header.shtml"
#modified virtual="header.html" fmt="?"
#modified virtual="index.html" fmt="?"
#modified virtual="footer.html" fmt="?"
#modified virtual="/web/common/footer.shtml"
#modified if-modified-since
-->
This construct should be placed at the very beginning of the SSI document,
and certainly before there is any chance of output being sent to the browser.
Once output to the client has occured there can be no change to the response
header information (not unreasonably).
4.3 - Pre-Expiring Documents
SSI preprocessed documents are dynamic in the sense that the information presented can be different every time the document is generated (e.g. if time directives are included). If it is important that each time the document is accessed it is regenerated then an HTML META tag can be included in the HTML header to cause the document to expire. This will result in the document being reloaded with each access. This can be accomplished two ways.
<!--#modified expires="Fri, 13 Jan 1978 14:00:00 GMT" -->
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN"> <HTML> <HEAD> <META HTTP-EQUIV="expires" CONTENT="Fri, 13 Jan 1978 14:00:00 GMT"> <TITLE> etc. </TITLE> </HEAD> <BODY> etc. </BODY> </HEAD>
The syntax follows closely that used by the other implementations, but
some directives are tailored to the WASD and VMS environment. The directive is
enclosed within an HTML comment and takes the form:
<!--#directive [[tag1="value"] [tag2="value"] ...] -->
A tag provides parameter information to the directive. A directive may have zero, one or more parameters. Values supplied with any tag may be literal or via variable substitution (see 4.6 - Variables. A value must be encolosed by quotation marks if it contains white-space.
A directive can be split over multiple lines provided the
new line begins naturally on white-space within the directive. For example,
this is correctly split
<!--#echo
created[="<EMPHASIS>(time-format)"] -->
while the following is not (and would produce an error)
<!--#echo creat
ed[="<EMPHASIS>(time-format)"] -->
Directive and tag keywords are case insensitive. The tag value may or
may not be case sensitive, depending upon the command/tag. Generally the
effect of a command is to produce additional text to be inserted in the
document, although it is possible to control the flow of processing in a
document with decision structures.
4.5 - Directives
|
The #accesses directive allows the number of times the document has been accessed to be included. It does this by creating a counter file in the same location and using the same name with a dollar symbol appended to the type (extension). The count may be reset by deleting the file. This is an expensive function (in terms of file system activity) and so should be used appropriately. It can be disabled by server configuration. Three tags provide additional functionality:
<!--#accesses ordinal -->
Provides the count as 1st, 2nd, 3rd, 4th, 5th ... 10th, 11th, 12th ... 120th, 121st, 122nd, etc.
<!--#accesses since="text" -->
This tag includes the specified text immediately after the access count is displayed, then adds the creation date of the counter file.
<!--#accesses since="text" timefmt="[time-format]" -->Allows the time format of the since tag to be supplied, where time-format is specified according to 4.10 - Time Format.
The #config directive allows time and file size formats to be specified for all subsequent directives providing these values. Optional specifications for individual directives may still be made, and override, do not supercede, any specification made using a config directive. A config directive may be made once, or any number of times in a document, and applies until another is made, or until the end of the document.
<!--#config errmsg="string" -->
This directive allows the error message generated if a problem problem processing the SSI document occurs (e.g. miss-spelled directive) to be specified in the document.
<!--#config timefmt="time-format" -->Where time-format is specified according to 4.10 - Time Format.
<!--#config sizefmt="size-format" -->Where size-format is specified using the following keywords:
<!--#config trace="1|0" -->
Switches document processing trace on or off, intended for use when debugging more complex or flow-controlled SSI documents.
Output from a trace is colour-coded.
The following link provides an example of a document trace.
The #dir directive generates an Index of ... directory listing inside an HTML document. Apart from not generating a title (it is up to the pre-processed document to title, or otherwise caption, the listing) it provides all the functionality of the WASD HTTPd directory listing (see 3 - Directory Listing), including query string format control via the "par=" parameter (note that from the "?httpd=index" introducer used with directory listings is not necessary from SSI). It is an WASD HTTPd extension to pre-processed HTML.
Listing specified using a VMS file path.
<!--#dir file="file-name" [par="server-directive(s)"] -->
Listing specified using URL-style syntax.
<!--#dir virtual="path" [par="server-directive(s)"] -->
For example:
<!--#dir /ht_root/src/httpd/" -->
<!--#dir /ht_root/src/httpd/*.c" par="layout=UL__S&nops=yes" -->
4.5.4 - #DCL
The #dcl directive executes a DCL command and incorporates the output into the processed document. It is an WASD HTTPd extension to the more common exec directive, which is also included.
By default, output from the DCL command has all HTML-forbidden characters
(e.g. "<", "&") escaped before inclusion in
the processed document. Thus command output cannot interfere with document
markup, but nor can the DCL command provide HTML markup. This behaviour may be
changed by appending the following tag to the directive:
type="text/html"
Some #dcl directives are for privileged documents only, documents defined as those being owned by the SYSTEM account, and not being world-writeable. The reason for this should be obvious. There are implicit security concerns about any document being able to execute any DCL command(s), even if it is being executed in a completely unprivileged process. Hence only innocuous commands are allowed in standard documents.
Execute the DCL "WRITE SYS$OUTPUT" command, using the
specified parameter.
<!--#dcl say="hello." -->
Execute the DCL "SHOW" command, using the specified
parameter.
<!--#dcl show="device/full tape1:" -->
Execute the DCL "DIRECTORY" command, using the
supplied file specification. Qualifiers may be included in the optional
"par" tag to control the format of the listing.
<!--#dcl dir="web:[000000]" -->
<!--#dcl dir="web:[000000]" par="/nohead/notrail" -->
<!--#dcl dir="web:[000000]" par="/size/date" -->
Execute the specified DCL command.
<!--#dcl exec="show device/full tape1:" -->
Execute the DCL command procedure specified as a VMS file path, with any
specified parameters applied to the procedure.
<!--#dcl file="HT_ROOT:[SHTML]TEST.COM" par="PARAM1 PARAM2" -->
Execute the DCL command procedure specified in URL-style syntax, with any
specified parameters applied to the procedure.
<!--#dcl virtual="../shtml/test.com" par="PARAM1 PARAM2" -->
The #echo directive incorporates the specified information into the processed document. Multiple tags may be used within the one directive.
Any SSI variable (e.g. CREATED), CGI variable (e.g. HTTP_USER_AGENT),
or document assigned variable (e.g. EXAMPLE1), see
4.6 - Variables.
<!--#echo value={created} var={example1} -->
The date/time of the current document's creation.
<!--#echo created[="time-format"] -->
Include the current date/time.
<!--#echo date_local[="time-format"] -->
Include the current Greenwich Mean Time (UTC) date/time.
<!--#echo date_gmt[="time-format"] -->
The current document's URL-style path.
<!--#echo document_name -->
The current document's VMS file path.
<!--#echo file_name -->
The date/time of the current document's last modification.
<!--#echo last_modified[="time-format"] -->
The #elif directive (else-if) allows blocks of HTML markup and
SSI directives to be conditionally processed, see
4.7 - Flow Control and 4.5.14 - #IF. This
directive effectively allows a case statement to be constructed.
<!--#elif var="[{variable}|literal" -->
4.5.7 - #ELSE
The else directive allows blocks of HTML markup and
SSI directives to be conditionally processed, see
4.7 - Flow Control. It is the default block after an
"#if", "#orif" or "#elif".
<!--#else -->
4.5.8 - #ENDIF
The #endif directive marks the end of a block of document text
being conditionally processed, see 4.7 - Flow Control.
<!--#endif -->
4.5.9 - #EXEC
The #exec directive executes a DCL command and incorporates the
output into the processed document. It is the VMS equivalent of the
exec shell directive of some Unix implementations. It is
implemented in the same way as the #DCL directive, and so the general detail
of that directive applies. It supports only the cmd tag, the
cgi tag, allowing execution of CGI scripts, is not supported.
<!--#exec cmd="show device/full tape1:" -->
The exec directive is for privileged documents
only, documents defined as those being owned by the SYSTEM account, and not
being world-writeable. The reason for this should be obvious. There are
implicit security concerns about any document being able to execute any DCL
command(s), even if it is being executed in a completely unprivileged process.
4.5.10 - #EXIT
The #exit directive causes the server to stop processing the
current SSI file. If the current file was an #included SSI file, processing
continues back with the parent file. Note that the #stop directive
also is available, it stops processing of the entire virtual document.
<!--#exit -->
4.5.11 - #FCREATED
The #fcreated directive incorporates the creation date/time of a specified file/document into the processed document.
Document specified using a VMS file path.
<!--#fcreated file="file-name" [fmt="time-format"] -->
Document specified using URL-style syntax.
<!--#fcreated virtual="path" [fmt="time-format"] -->
The #flastmod directive incorporates the last modification date/time of a specified file/document into the processed document.
Document specified using a VMS file path.
<!--#flastmod file="file-name" [fmt="time-format"] -->
Document specified using URL-style syntax.
<!--#flastmod virtual="path" [fmt="time-format"] -->
The #fsize directive incorporates the size, in bytes, kbytes or Mbytes, of a specified file/document into the processed document.
Document specified using a VMS file path.
<!--#fsize file="file-name" [fmt="size-format"] -->
Document specified using URL-style syntax.
<!--#fsize virtual="path" [fmt="size-format"] -->
The #if directive allows blocks of HTML markup and SSI directives to be conditionally processed, see 4.7 - Flow Control.
Variable the decision will be based upon.
<!--#if var="[{variable}|literal]" -->
Is the string the same as in the variable?
If the variable is a number is it the same as this?
If the variable is a number is it greater than this?
If the variable is a number is it less than this?
Search the variable for this string. May contain the "*" wildcard, matching one or more characters, and the "%", matching any single character.
As in the following examples:
<!--#if value={DOCUMENT_URI} eqs="/ht_root/doc/env/xssi.shtml" -->
<!--#if value={COUNT} lt=10 -->
<!--#if value="This is a test!" eqs={STRING} -->
<!--#if value={PATH_INFO} srch="*/env/*" -->
4.5.15 - #INCLUDE
The #include directive incorporates the contents of a specified file/document into the processed document.
Include the contents of the document specified using a VMS file
specification.
<!--#include file="file-name" -->
Include the contents of the document specified using URL-style syntax.
<!--#include virtual="path" -->
The contents of the specified file are included differently depending on
the MIME content-type of the file. Files of text/html content-type
(HTML documents) are included directly, and any HTML tags within them
contribute to the markup of the document. Files of text/plain
content-type (plain-text documents) are encapsulated in
"<PRE></PRE>" tags and have all HTML-forbidden
characters (e.g. "<", "&") escaped before
inclusion in the processed document. An HTML file can be forced to be included
as plain-text by using the following syntax:
<!--#include virtual="example.html" type="text/plain" -->
To "force" a file to be considered as text regardless of it's actual
content (as determined by the server from the file type), use on of the
following depending on whether it should be rendered as plain or HTML text.
<!--#include virtual="example.html" content="text/plain" -->
<!--#include virtual="example.html" content="text/html" -->
Other SSI files may be included and their content dynamically included in
the resulting document. To prevent a recursive inclusion of documents the
nesting level of SSI documents is limited to five.
4.5.16 - #MODIFIED
The #modified directive allows a document author to control the "Last-Modified:"/"If-Modified-Since:"/"304 Not modified" behaviour of an SSI document. See 4.1 - Virtual Documents.
Get the last-modified date/time of the current document.
<!--#modified -->
Get the last-modified date/time of the document specified using VMS file
specification.
<!--#modified file="file-name" -->
Get the last-modified date/time of the document specified using URL-style
syntax.
<!--#modified virtual="path" -->
Compares any "If-Modified-Since:" request header timestamp to the
revision date time obtained using file or virtual (most
recent if multiple). If the document timestamp is more recent (has been
modified) an appropriate "Last-Modified" response header field is
generated and added to the response, and document processing continues. If it
has not been modified a "304" response header is return (document not
modified) and document processing stops.
<!--#modified if-modified-since -->
Adds a "Last-Modified:" response header field using a timestamp
retrieved using file or virtual (note: unnecessary if
the if-modified-since tag is used).
<!--#modified last-modified -->
Adds a "Expires:" response header field. The string literal should be a legitimate RFC-1123 date string. This can be
used for pre-expiring documents (so they are always reloaded), set it to a date
in the not-too-distant past (as in the example below). Of course it could also
be used for setting the legitimate future expiry of documents.
<!--#modified expires="Fri, 13 Jan 1978 14:00:00 GMT" -->
The #orif directive (or-if) allows blocks of HTML markup and
SSI directives to be conditionally processed, see
4.7 - Flow Control and 4.5.14 - #IF. In the
absence of any real expression parser this directive allows a block to be
processed if one of multiple conditions are met.
<!--#orif var="[{variable}|literal" -->
4.5.18 - #PRINTENV
The #printenv directive prints a plain-text list of all
SSI-specific, then CGI, then document-assigned variables (see
4.6 - Variables). This directive is intended for use when
debugging flow-controlled SSI documents.
<!--#printenv -->
The following link uses the example SSI document HT_ROOT:[DOC.ENV]XSSI.SHTML to demonstrate this.
xssi.shtml?httpd=ssi&printenv=yes&test1=one&test2=two&test3=three
The #set directive allows a user variable to be assigned or
modified, see 4.6 - Variables.
<!--#set var="variable-name" value="whatever" -->
Variables are always stored as strings and have a finite but generally
usable length. Some comparison tags provided in the flow-control directives
treat the contents of variables as numbers. A numeric conversion is done at
evaluation time.
4.5.20 - #SSI
The #ssi directive allows multiple SSI directives to be used
without the requirement to enclose them in the normal HTML comment tags (i.e.
<!-- -->). This helps reduce the clutter in an SSI document that
uses the extended capabilities of variable assignment and flow control.
Document HTML cannot be included between the opening and closing comment
elements of the "#ssi" tag, although of course document output can be
generated using the "#echo" tag.
<!--#ssi
#set var=HOUR value={DATE_LOCAL,12,2}
#if var={HOUR} lt=12
#set var=GREETING value="Good morning"
#elif var={HOUR} lt=19
#set var=GREETING value="Good afternoon"
#else
#set var=GREETING value="Good evening"
#endif
-->
The example SSI document
HT_ROOT:[DOC.ENV]XSSI.SHTML
illustrates this concept.
4.5.21 - #STOP
The #stop directive causes the server to stop processing the
virtual document. It can be used with flow control structures to conditionally
process only part of a virtual document. Note that the #exit
directive also is available, it stops processing of the current file (for
nested #includes, etc.).
<!--#stop -->
4.6 - Variables
The SSI processor maintains information about the server, date and time, request path, request parameters, etc., accessable via variable name. Although these server variables cannot be modified by the document the processor also allows the author to create and assign new document variables by name. SSI variables have global scope, with a small number of exceptions listed below. That is, the same set of variables are shared with the parent document by any other SSI documents #included, and any included by those, etc.
Local variables:
One other special-purpose variable, THE_FILE_NAME, see 4.9.1 - THE_FILE_NAME.
Server assigned variables comprise some SSI-specific as well as the same CGI variables available to CGI scripts. These may be found listed in the "CGI Scripting" chapter of the Technical Overview.
The following link provides a list of the SSI and CGI variables available to SSI documents.
Whenever a directive uses information from a tag (see
4.4 - Directive Syntax) values from variables may be
substituted as as a whole or partial value. This is done using curly braces
to delimit the variable name. For example
<!--#include virtual={FILENAME} -->
would include the file named by the contents of a variable named
"FILENAME". When using a variable in a tag it is not necessary to
enclose the tag parameter in quotation marks unless there is additional
literal text. Variables may also be used within literal strings,
producing a compound, resultant string, as in the following example
<!--#echo var="Hello {REMOTE_HOST}, time here is {LOCAL_TIME}" -->
Variables are considered numeric when they begin with a digit. Those beginning with an alphabetic are considered to have a numeric value of zero.
Variables are considered to be boolean false if empty and
true when not empty.
Substrings
It is also possible to extract substrings from variables using the
following syntax,
{variable-name,start-index,count}
where the start-index begins with the zeroth character and numbers up to the last character in the string, and count may be zero or any positive number. If only one number is supplied it is regarded as a count and the string is extracted from the zeroth character.
To illustrate,
<!--#set var=EXAMPLE value="This is an example!" -->
<!--#echo "{EXAMPLE,2}at was {EXAMPLE,8,999}" -->
would output
That was an example!
Other "Functions"
{variable-name[,start-index],count]],length}
For example
<!--#set var=EXAMPLE value="This is an example!" -->
<!--#echo "\"{EXAMPLE}\" is {EXAMPLE,length} characters long." -->
<!--#echo "\"{EXAMPLE,5,2}\" is {EXAMPLE,5,2,length} characters long!" -->
would output
"This is an example!" is 19 characters long.
"is" is 2 characters long!
var={variable-name,exists}
For example
<!--#set var=BOGUS_VARIABLE value="irrelevant" -->
<!--#if var={BOGUS_VARIABLE,exists} -->
"BOGUS_VARIABLE" exists!
<!--#else -->
"BOGUS_VARIABLE" does NOT exist!
<!--#endif -->
The example SSI document
HT_ROOT:[DOC.ENV]XSSI.SHTML
illustrates these concepts.
4.7 - Flow Control
WASD SSI allows blocks of document to be conditionally processed. This uses constructs in a similar way to any programming language. The emphasis has been on simplicity and speed of processing. No complex expression parser is provided. Despite this, complex document constructs can be implemented. Flow control structures may be nested up to eight levels.
The "#if", "#orif" and "#elif" directives must provide an evaluation. This can be single variable, which if numeric and non-zero is considered true, if zero if false, or can be a string, which if empty is false, and if not empty is true. Tests can be made against the variable which when evaluated return a true or false. Multiple tests may be made against the one variable, or against more than one variable. Multiple tests act as a logical AND of the results and terminate when the first fails.
Any evaluation can have it's result negated by prefixing it with an
exclamation point. For instance, the first of these examples would produce a
false result, the second true.
<!--#if value="test" !eqs="test" -->
<!--#if value=20 !lt=10 -->
The following is a simple example illustration of variable setting, use
of variable substrings, and conditional processing of document blocks.
<!--##config trace=1 -->
<HTML>
<!--#set var=HOUR value={DATE_LOCAL,12,5} -->
<!--#if var={HOUR} lt=12 -->
<!--#set var=GREETING value="Good morning" -->
<!--#elif var={HOUR} lt=19 -->
<!--#set var=GREETING value="Good afternoon" -->
<!--#else -->
<!--#set var=GREETING value="Good evening" -->
<!--#endif -->
<HEAD>
<TITLE><!--#echo var={GREETING} -->
<!--#echo var="{REMOTE_HOST}!" --></TITLE>
</HEAD>
<BODY>
<H1>Simple XSSI Demonstration</H1>
<!--#echo var={GREETING} --> <!--#echo var={REMOTE_HOST} -->,
the time here is <!--#echo var={DATE_LOCAL,12,5} -->.
<!--#if var={REMOTE_HOST} eqs={REMOTE_ADDR} -->
(Sorry, I do not know your name, DNS lookup must be disabled!)
<!--#endif -->
</BODY>
</HTML>
The example SSI document
HT_ROOT:[DOC.ENV]XSSI.SHTML
further illustrates these concepts.
4.8 - Query Strings
A query string may be passed to an SSI document in much the same way as to
a CGI script. In this way the behaviour of the document can be varied in
accordance to information explicitly passed to it when accessed. To prevent
the server's default query engine being given the request precede any query
string with "?httpd=ssi". The server detects this and passes the
request instead to the SSI processor. Just append the desired query string
components to this as if they were form elements. For example:
?httpd=ssi&printenv=no
?httpd=ssi&printenv=yes
?httpd=ssi&trace=yes&test2=one&test2=two&test3=three
The following link uses the example SSI document
HT_ROOT:[DOC.ENV]XSSI.SHTML
to demonstrate this. Look for the Documents may be specified using either the "FILE" or
"VIRTUAL" tags.
The "FILE" tag expects an absolute VMS file
specification.
The "VIRTUAL" tag expects an URL-style path to a
document. This can be an absolute or relative path. See
2.3 - Document Specification for further details.
Generally, when an error are encountered document processing halts and
and an error report is generated. For some common circumstances, in particular
the existance or not of a particular file, may require an alternative action.
For file activities (e.g. #include, #flastmod, #created, #fsize) the optional
fmt="" tag provides some measure of control on error behaviour. If the format
string begins with a "?" files not found are not reported as errors and
processing continues. Other file systems errors, such as directory not found,
syntax errors, etc., are always reported.
Every time a file is accessed (e.g. #include, #flastmod) the server
variable THE_FILE_NAME gets set to that name if successful, or reset to empty
if unsuccessful. This variable can be checked to determine success or
otherwise.
Whenever a time directive is used an optional tag can be included to
specify the format of the output. The default looks a little VMS-ish. If a
format specification is made it must confirm to the C programming language
function strftime().
The format specifier follows a similar syntax to the C standard library
printf() family of functions, where conversion specifiers are
introduced by percentage symbols. Here are some example uses:
A problem with any supplied time formatting specification will be reported.
The following table provides the general conversion specifiers. For
futher information on the formatting process refer to a C programming library
document on the strftime() function.
Essential compatibility with OSU Server Side Includes directives is
provided. This is intended to ease any transition to WASD, as existing SSI
documents will not need to be changed unless any of the WASD capabilities are
required. To provide transparent processing of OSU ".HTMLX" files
ensure the following WASD configuration is in place.
In HTTPD$CONFIG file:
Note that the content description must contain the string "OSU" to activate
some compliancy behaviours.
In HTTPD$MAP file:
This provides a mechanism for the OSU part-document facility.
(Yes, the "__part" has two leading underscores!)
The following OSU directives are provided specifically for OSU
compatibility, although there is no reason why most of these may not also be
deployed in general WASD SSI documents if there is a requirement. Note that
these are OSU-specifics, other OSU directives are provided by the standard WASD
SSI engine.
If WASD is configured for OSU SSI compatibility the following link provides
an online demonstration as well as further explanation of the OSU SSI engine
using an OSU preprocessor document from the distribution (included within
copyright compliance).
How do we know WASD is processing it? Look for the
#echo var="GETENV=SYS$REM_ID" towards the end of the
document. It should indicate "[VARIABLE_DOES_NOT_EXIST!]" because it's
attempting to output a DECnet-related logical name!
The OSU processor allows for delimited subsections of an
#included document, or a URL referenced document for that matter,
to be included in the output. This is supported, but only for compatibility.
It is only enabled for ".HTMLX" documents and if otherwise used may
interact unexpectedly with WASD SSI flow-control.
(FORM_TEST1=one), etc.
xssi.shtml?httpd=ssi&printenv=yes&test1=one&test2=two&test3=three
4.9 - File and Virtual Specifications
4.9.1 - THE_FILE_NAME
<!--#fcreated virtual="TEST.TXT" fmt="?" -->
<!--#if var={THE_FILE_NAME} eqs="" -->
File does not exist!
<!--#else -->
File exists!
<!--#endif -->
4.10 - Time Format The date is <!--#echo date_local fmt="%d/%m/%y" -->.
The time is <!--#echo date_local fmt="%r" -->.
The day-of-the-week is <!--#echo date_local fmt="%A" -->.
Specifier Replaced by
a The locale's abbreviated weekday name
A The locale's full weekday name
b The locale's abbreviated month name
B The locale's full month name
c The locale's appropriate date and time representation
C The century number (the year divided by 100 and truncated
to an integer) as a decimal number (00 - 99)
d The day of the month as a decimal number (01 - 31)
D Same as %m/%d/%y
e The day of the month as a decimal number (1 - 31) in a
2 digit field with the leading space character fill
Ec The locale's alternative date and time representation
EC The name of the base year (period) in the locale's
alternative representation
Ex The locale's alternative date representation
EX The locale's alternative time representation
Ey The offset from the base year (%EC) in the locale's
alternative representation
EY The locale's full alternative year representation
h Same as %b
H The hour (24-hour clock) as a decimal number (00 - 23)
I The hour (12-hour clock) as a decimal number (01 - 12)
j The day of the year as a decimal number (001 - 366)
m The month as a decimal number (01 - 12)
M The minute as a decimal number (00 - 59)
n The newline character
Od The day of the month using the locale's alternative
numeric symbols
Oe The date of the month using the locale's alternative
numeric symbols
OH The hour (24-hour clock) using the locale's alternative
numeric symbols
OI The hour (12-hour clock) using the locale's alternative
numeric symbols
Om The month using the locale's alternative numeric symbols
OM The minutes using the locale's alternative numeric symbols
OS The seconds using the locale's alternative numeric symbols
Ou The weekday as a number in the locale's alternative
representation (Monday=1)
OU The week number of the year (Sunday as the first day of the
week) using the locale's alternative numeric symbols
OV The week number of the year (Monday as the first day of the
week) as a decimal number (01 -53) using the locale's
alternative numeric symbols. If the week containing January 1
has four or more days in the new year, it is considered
as week 1. Otherwise, it is considered as week 53 of the
previous year, and the next week is week 1.
Ow The weekday as a number (Sunday=0) using the locale's
alternative numeric symbols
OW The week number of the year (Monday as the first day of
the week) using the locale's alternative numeric symbols
Oy The year without the century using the locale's alternative
numeric symbols
p The locale's equivalent of the AM/PM designations associated
with a 12-hour clock
r The time in AM/PM notation
R The time in 24-hour notation (%H:%M)
S The second as a decimal number (00 - 61)
t The tab character
T The time (%H:%M:%S)
u The weekday as a decimal number between 1 and 7 (Monday=1)
U The week number of the year (the first Sunday as the first
day of week 1) as a decimal number (00 - 53)
V The week number of the year (Monday as the first day of the
week) as a decimal number (00 - 53). If the week containing
January 1 has four or more days in the new year, it is
considered as week 1. Otherwise, it is considered as week 53
of the previous year, and the next week is week 1.
w The weekday as a decimal number (0 [Sunday] - 6)
W The week number of the year (the first Monday as the first
day of week 1) as a decimal number (00 - 53)
x The locale's appropriate date representation
X The locale's appropriate time representation
y The year without century as a decimal number (00 - 99)
Y The year with century as a decimal number
Z Timezone name or abbreviation. If timezone information is
not available, no character is output.
% %
4.11 - OSU Compatibility [AddType]
.HTMLX text/x-shtml - OSU SSI HTML
redirect /*.*.htmlx /*.htmlx?httpd=ssi&__part=*
OSU Directives
Directive Description
#begin label [label]
delimit a part-document (see OSU "Part"s)
#config verify=1
enable commented-tag trace output
#echo accesses document access count
#echo accesses_ordinal document access count
#echo getenv="" output logical or symbol
#echo hw_name system hardware name
#echo server_name HTTPd server host name
#echo server_version HTTPd software version
#echo vms_version HTTPd system version of VMS
#end label [label]
delimit a part-document (see OSU "Part"s)
#include [file|virtual]="" part="label"
include only part of a virtual document
/ht_root/src/osu/preproc.htmlx
OSU "Part"s
[next] [previous] [contents] [full-page]