<COMMENT>(--------------------------------------------------------------------)

<FRONT_MATTER>
<TITLE_PAGE>

<TITLE>(WASD Hypertext Services\- Environment Overview)

<COMMENT>(HTML/OFF)
<LINE>
<COMMENT>(HTML/ON)

<HEAD>(November 2000\head_date)

<P> For version 7.1 release of the WASD VMS Hypertext Services HTTP server.

<P> Supercedes: 

<CODE_EXAMPLE>
      June 2000
      December 1999
      April 1999
      June 1998
      March 1998
      November 1997
      August 1997
      June 1997,
      May 1996 (initial freeware release),
      July 1995,
      May 1995,
      December 1994
<ENDCODE_EXAMPLE>

<HEAD>(Please Note\head_please_note)

<P> As of July 1997 High Frequency Radar Division (HFRD) underwent a change of
role and name.  It is now Wide Area Surveillance Division (WASD).  This package
has been renamed in accordance with that.

<HEAD>(Abstract\head_abstract)

<P> This document is a guide to supporting hypertext documentation within the 
WASD Hypertext Services environment.  It is <EMPHASIS>(not\BOLD) a tutorial on 
writing HTML documents. 

<P> It covers the environment supported by the version 5 release of the WASD 
VMS Hypertext Services (March 1998).  It could revised and expanded
considerably (if only I prefered to document rather than code :^)

<COMMENT>(HTML/OFF)
<P> It is strongly suggested those using printed versions of this document 
also access the hypertext version.  It provides online demonstrations of some 
concepts.
<COMMENT>(HTML/ON) 

<HEAD>(Author\head_author)

<P> Mark G. Daniel
<LINE> Surveillance Systems Division
<LINE> Defence Science and Technology Organisation

<P> For WASD-related email please use
<LINE>

<COMMENT>(HTML=
<A HREF="mailto:Mark.Daniel@vsm.com.au">Mark.Daniel@vsm.com.au</A>
)

<COMMENT>(HTML/OFF)
<UNDERLINE>(Mark.Daniel@vsm.com.au)
<COMMENT>(HTML/ON)

<P> Should the above address present problems or provide no response for an
extended period then use
<LINE><UNDERLINE>(Mark.Daniel@dsto.defence.gov.au)

<P> +61 (8) 82596189 (bus) 
<LINE> +61 (8) 82596673 (fax)

<P> PO Box 1500
<LINE> Salisbury
<LINE> South Australia 5108

<COMMENT>(--------------------------------------------------------------------)

<HEAD>(Online Search\head_search_online)
                  
<COMMENT>(HTML=
<P> Search this document using WASDquery (if available at this site):

<P><FORM ACTION="/cgi-bin/query/ht_root/doc/env/*.html" TARGET="_top">
<TABLE CELLSPACING=0 CELLPADDING=5 BORDER=1>
<TR><TD BGCOLOR="#ffffcc">
<INPUT TYPE=submit VALUE="Search for:">&nbsp;
<INPUT TYPE=text NAME=search SIZE=20>&nbsp;
<INPUT TYPE=reset VALUE="Reset">
</TD></TR>
</TABLE>
</FORM>
)

<COMMENT>(HTML/OFF)
<P><BOX>(online search)
<COMMENT>(HTML/ON)

<HEAD>(Online PostScript\head_postscript)

<COMMENT>(HTML=

<P> This document is also available in
<A HREF="/ht_root/doc/env/env.ps">PostScript</A>  
for access by suitable viewers (e.g. GhostScript), and printing from the
location HT_ROOT:[DOC.ENV]ENV.PS  
)

<COMMENT>(HTML/OFF)
<P> This book is available in PostScript for access by suitable viewers (e.g.
GhostScript).  Use a browser to access a print menu in this same location.
It can be reprinted from the location HT_ROOT:[DOC.ENV]ENV.PS  
<COMMENT>(HTML/ON) 

<HEAD>(Online Demonstrations\head_demonstrations_online)

<P> Some of the online demonstrations may not work due to the local
organisation of the Web environment differing from WASD where it was
originally written. 

<COMMENT>(--------------------------------------------------------------------)

<PAGE>

<INCLUDE>([-.htd]copyright.sdml)

<ENDTITLE_PAGE>

<CONTENTS_FILE>

<ENDFRONT_MATTER>

<COMMENT>(--------------------------------------------------------------------)

<CHAPTER>(Introduction\chapter_introduction)

<P> As of July 1997 High Frequency Radar Division (HFRD) underwent a change of
role and name.  It is now Wide Area Surveillance Division (WASD).  This package
has been renamed in accordance with that.

<P> This document primarily written for use internal to WASD and assumes that 
perpsective without apology.  Any additional usage is subordinate to its role 
within WASD.  The hypertext software has been written expressly for supporting 
an intra-organisational hypertext environment on a VMS platform.  It too, is 
unreservedly tailored to this purpose and the requirements of WASD. 

<P> The document <EMPHASIS>(assumes\BOLD) a basic understanding of hypertext 
technologies and uses some terms without explaining them (e.g. HTTP, HTML, 
URL, CGI, etc.)  It is <EMPHASIS>(not\BOLD) a tutorial on writing HTML 
documents.   The reader is refered to documents specifically on these topics 
(some are available 

<COMMENT>(HTML=
<A HREF="/web/technical/">on-line within WASD</A>,
)

<COMMENT>(HTML/OFF)
on-line within WASD,
<COMMENT>(HTML/ON) 

but are often best consulted from the Internet WWW). 

<COMMENT>(HTML=
<P> This document contains a number of on-line, hypertext 
demonstrations and examples.
)

<P> WASD is using hypertext technologies (a.k.a. Web and WWW) to assist in 
providing an integrated and commonly-accessable information environment.  The 
VMS implementation of this has gone to considerable lengths to integrate as 
much as possible, all forms of VMS information.  This includes plain-text 
documents such as programming sources and environment/include files, release 
notes, etc., as well as non-plain-text information like HELP, Bookreader, etc. 

<P> The purpose of this document is to describe some of the facilities within 
the WASD VMS hypertext environment that can be used from within WASD HTML 
documents.  The WASD VMS hypertext infrastructure conforms to all the basic 
conventions of Web technology, although having some facilities specific-to, or 
tailored-for its VMS environment.

<COMMENT>(HTML/OFF)
<P> It is strongly suggested those using printed versions of this document 
also access the Hypertext version.  It provides online demonstrations of some 
concepts.
<COMMENT>(HTML/ON) 

<P> Some of the online demonstrations may not work due to the local 
organisation of the hypertext environment differing from WASD where it was 
originally written. 

<COMMENT>(--------------------------------------------------------------------)

<CHAPTER>(HyperText Transport Protocol Daemon\chapter_httpd)

<P> The most fundamental component of the WASD VMS hypertext environment is 
the HTTPd, or HyperText Protocol Transport Daemon, a program serving the 
hypertext environment to the browser <EMPHASIS>(clients).

<P> The WASD version provides a complete implementation of a basic HTTP 
<EMPHASIS>(server), including: 

<LIST>(UNNUMBERED)

<LE> concurrent, multi-threaded client support

<LE> <QUOTE>(DELETE), <QUOTE>(GET), <QUOTE>(HEAD), <QUOTE>(POST) and
<QUOTE>(PUT) HTTP method support

<LE> <QUOTE>(If-Modified-Since:) / <QUOTE>(304 Not Modified) functionality 
(document is only sent if modified since time specified by client)

<LE> HTTP/1.0 de-facto persistent connections (i.e. <QUOTE>(Keep-Alive:),
reducing the number of TCP/IP connects required)

<LE> versatile directory listing (generic and VMS-style)

<LE> CGI-compliant scripting
(with configurable, automatic, MIME content-type initiated activation)

<LE> <EMPHASIS>(CGIplus\BOLD) scripting
(offering reduced latency, increased throughput and reduced system impact when
scripting)

<LE> script processor (e.g. PERL) configurable on file type (extension)

<LE> Server Side Includes (HTML pre-processing)

<LE> configurable cache, with automatic, time-based and forced re-validation
(reload)

<LE> clickable-image support (both NCSA and CERN formats)

<LE> <EMPHASIS>(smart) rule mapping (conditional rules)

<LE> <QUOTE>(Basic) and <QUOTE>(Digest) user authentication and
path/group-based authorization

<LE> Optional SYSUAF-authentication and VMS user security profile based file
access control (only for the most secure of LAN environments!)

<LE> Web-standard, <QUOTE>(common) and <QUOTE>(combined) access log formats
(allowing processing by most log-analysis tools), along with a user-definition
capability, allowing custom log formats

<LE> logging periods, where log files automatically change on a daily,
weekly or monthly basis (keeps log files ordered and at a managable size)

<LE> host-level access control, on per-host or per-domain acceptance or 
rejection 

<LE> single server can support multi-homed (host name) and multiple port
services

<LE> on-line server configuration, including reports on requests,
loaded configuration, mapping rules, authorization information and graphical
activity displays

<LE> <EMPHASIS>(cookie) support (<QUOTE>(Cookie:) HTTP header field)

<LE> customizable message database
(capable of supporting non-English and concurrent, multiple languages)

<LE> configurable, automatic conversion of documents from VARIABLE to
STREAM-LF record format
(much more efficient with this server)

<ENDLIST> 

<HEAD>(Scripts\head_scripts)

<P> The WASD scripting mechanism is based on the WWW CGI Common Gateway 
Interface (CGI, modelled on the CERN and NCSA VMS implementations). 

<P> <EMPHASIS>(Scripts) are programs external to the main server that behave 
as <EMPHASIS>(gateways) to non-hypertext data formats, usually interpreting 
those formats into HTML before transport to and use by the browser.  The WASD 
environment provides a number of scripts for accessing VMS-specific,
DEC-specific and some other WASD-specific information. 

<HEAD1>(Auto-Scripting\head_autoscripting)

<P> A script can be automatically activated by the server through it detecting 
the content-type of the specified document (based on the file 
<EMPHASIS>(extension) (e.g. <QUOTE>(.TXT))).

<P> This <EMPHASIS>(auto-scripting) can occur whenever the document 
specification includes no file version number.  If a file version number is 
present the file is always returned directly to the browser.  The browser must 
then process the document in some fashion (often by activating a 
<EMPHASIS>(save as) dialog).  A simple way of suppressing the auto-scripting 
facility is to include a <EMPHASIS>(latest-version) number (i.e. 
<QUOTE>(;0)), as in this specification 
<QUOTE>(/sys$common/syshlp/helplib.hlb;0). 

<COMMENT>(--------------------------------------------------------------------)

<CHAPTER>(Document Access and Specification\chapter_document_access)

<P> <EMPHASIS>(Arbitrary documents may not be accessed.\BOLD)

<P> The server can only access files where the path is allowed according to a 
specified set of rules specified within the hypertext environment.

<P> <EMPHASIS>(Documents must be read-accessable.\BOLD)

<P> The server can only access files that are world readable, or that have an 
ACL specifically controlling access for <QUOTE>(HTTP$SERVER), the server 
account. 

<HEAD1>(Document Content Type\head_document_types)

<P> Document (file) retrieval is initiated by providing the server with the 
file specification as a URL path.  Server configuration determines the format 
in which the file is returned to the client.  It may contain text or images 
immediately diplayable by the browser, or by a viewer external to the browser 
may be spawned.  The server may automatically activate a script to provide a 
gateway to non-native information (see <REFERENCE>(head_autoscripting)).  The 
file type (extension) determines the content type by which the server returns 
(and/or interprets) the file. 

<P> The following table lists some of the current file types (as examples) and 
their associated MIME-style content type.  HTML documents are presented
layed-up according to the full HTML-capabilities of the browser.  Plain-text 
documents are presented in a fixed-font format.  Other types require an 
external viewer to be activated.  Here are a few examples.

<CODE_EXAMPLE>
  .BKB        Bookreader document (BNU)   text/html, gateway script activated
  .BKS        Bookreader shelf (BNU)      text/html, gateway script activated
  .C          C source                    text/plain
  .COM        DCL procedure               text/plain
  .CONF       configuration file          text/plain
  .CPP        C++ source                  text/plain
  .DECW$BOOK  Bookreader document         text/html, gateway script activated
  .FOR        Fortran source              text/plain
  .GIF        GIF image                   image/gif
  .H          C header                    text/plain
  .HLB        VMS Help library            text/html, gateway script activated
  .HTML       HyperText Markup Language   text/html
  .HTM        HyperText Markup Language   text/html
  .JPG        JPEG image                  image/jpeg
  .LIS        Listing                     text/plain
  .MAR        Macro source                text/plain
  .PAS        Pascal source               text/plain
  .PRO        IDL source                  text/plain
  .PS         PostScript                  application/PostScript
  .TEXT       Text                        text/plain
  .TLB        VMS text library            text/html, gateway script activated
  .TXT        Text                        text/plain
  .SHTML      HyperText Markup Language   pre-processed text/html
  .ZIP        zipped file                 application/binary
<ENDCODE_EXAMPLE>

<P> If other file types are required to be defined contact the Web
administrator.

<HEAD1>(Explicitly Specifying Content-Type\head_explicit_type)

<P> When accessing files it is possible to explicitly specify the identifying
content-type to be returned to the browser in the HTTP response header.  Of
course this does not change the actual content of the file, just the header
content-type!  This is primarily provided to allow access to plain-text
documents that have obscure, non-<QUOTE>(standard) or non-configured file
extensions.

<P> It could also be used for other purposes, <QUOTE>(forcing) the browser to
accept a particular file as a particular content-type.  This can be useful if
the extension is not configured (as mentioned above) or in the case where the
file contains data of a known content-type but with an extension conflicting
with an already configured extension specifying data of a different
content-type.

<P> Enter the file path into the browser's URL specification field ("Location:",
"Address:").  Then, for plain-text, append the following query string:

<CODE_EXAMPLE>
  ?httpd=content&type=text/plain
<ENDCODE_EXAMPLE>

<P> For another content-type substitute it appropriately. 
For example, to retrieve a text file in binary (why I can't imagine :^) use

<CODE_EXAMPLE>
  ?httpd=content&type=application/octet-stream
<ENDCODE_EXAMPLE>

<P> This is an example:

<COMMENT>(....................................................................)

<COMMENT>(HTML=
<PRE>
  <A HREF="file.unknown">file.unknown</A>

  <A HREF="file.unknown?httpd=content&type=text/plain">file.unknown?httpd=content&type=text/plain</A>
</PRE>
)

<COMMENT>(HTML/OFF)
<P><BOX>(online demonstration)
<COMMENT>(HTML/ON)

<COMMENT>(....................................................................)

<P> It is also posssible to "force" the content-type for all files in a
particular directory. See <REFERENCE>(head_dir_content_type).

<COMMENT>(....................................................................)

<HEAD1>(Document Specification\head_document_specification)

<P> For the <QUOTE>(http:) protocol, file and directory locations are specified
using URL path syntax where slash-separated (<QUOTE>(/)) elements delineate a
hierarchy leading to a data item.  Anyone familiar with the syntax of the Unix
file system, or the MS-DOS file system (where back-slashes are hierarchy
delimiters), will feel at home with URL syntax.  Specifications under VMS are
not case-sensitive. 

<P> A VMS directory specification 

<CODE_EXAMPLE>
  WEB:[TECHNICAL.HTML-PRIMER]
<ENDCODE_EXAMPLE>

<CP> would be represented in URL syntax as

<CODE_EXAMPLE>
  /web/technical/html-primer/
<ENDCODE_EXAMPLE>

<CP> and a VMS file specification 

<CODE_EXAMPLE>
  WEB:[TECHNICAL.HTML-PRIMER]HTML-PRIMER.HTML
<ENDCODE_EXAMPLE>

<CP> represented as

<CODE_EXAMPLE>
  /web/technical/html-primer/html-primer.html
<ENDCODE_EXAMPLE>

<NOTE>

It is not required (although not forbidden) to supply a VMS <EMPHASIS>(master 
file directory) component (<QUOTE>([000000]), <QUOTE>([000000.), etc.) in a 
URL specification.  Hence the file specification 

<CODE_EXAMPLE>
  WEB:[000000]HOME.HTML
<ENDCODE_EXAMPLE>

<CP> should be represented as

<CODE_EXAMPLE>
  /web/home.html
<ENDCODE_EXAMPLE>

<ENDNOTE> 

<HEAD2>(Absolute File Path\head_absolute_file_path)

<P> A file may be specified using an <EMPHASIS>(absolute), or full path.  This 
must specify the location of the file exactly.  Absolute paths 
<EMPHASIS>(always\BOLD) begin with a forward-slash (<QUOTE>(/)).  For example: 

<CODE_EXAMPLE>
  /web/committee/minutes/1994/1994-09-27.txt
  /web/committee/constitution.txt
  /web/committee/membership/fred-bloggs.txt
<ENDCODE_EXAMPLE>

<HEAD2>(Partial (or Relative) File Path\head_partial_file_path)

<P> <EMPHASIS>((Strictly speaking, it is a function of the client to 
construct a full URL from such a relative URL before sending the request to 
the server.))

<P> A file may be specified <EMPHASIS>(relative) to its current location.  
That is, a current document (or menu) may specify another document file 
relative to itself.  This may be at the current level, a subdirectory, or in 
another part of the directory tree related to the current.  Relative paths 
<EMPHASIS>(never\BOLD) begin with forward-slash (<QUOTE>(/)). 

<P> For example, documents at the same level as the current may be specified 
without any hierachy being indicated: 

<CODE_EXAMPLE>
  1994-07-22.txt
  1994-08-24.txt
  1994-09-27.txt
<ENDCODE_EXAMPLE>

<P> Documents at an inferior point in the hierarchy may be specified as in the 
following example: 

<CODE_EXAMPLE>
  1993/1993-02-17.txt
  1993/reports/membership.txt
  other/etc.txt
<ENDCODE_EXAMPLE>

<P> Documents in a related part of the hierarchy may be referenced using the 
<QUOTE>(<EMPHASIS>(../\BOLD)) construct.  As with MS-DOS and Unix this syntax 
indicates the immediately superior directory. 

<CODE_EXAMPLE>
  ../other_committee/1993/1993-02-17.txt
  ../other_committee/1993/reports/balance-sheet.txt
  ../../other_section/committee/constitution.txt
<ENDCODE_EXAMPLE>

<HEAD1>(Extended File Specifications (ODS-5)\head_mapping_extended)

<P> OpenVMS Alpha V7.2 introduced a new on-disk file system structure, ODS-5. 
This brings to VMS in general, and WASD and other Web servers in particular, a
number of issues regarding the handling of characters previously not
encountered during (ODS-2) file system activities.

<HEAD2>(Characters In Request Paths\head_mapping_extended_paths)

<P> There is a standard for characters used in HTTP requests paths and query
strings (URLs).  This includes conventions for the handling of reserved
characters, for example <QUOTE>(?), <QUOTE>(+), <QUOTE>(&), <QUOTE>(=)
that have specific meanings in a request,  characters that are completely
forbidden, for example white-space, control characters (0x00 to 0x1f), and
others that have usages by convention, for example the <QUOTE>(~), commonly
used to indicate a username mapping.  The request can otherwise contain these
characters provided they are URL-encoded (i.e. a percentage symbol followed by
two hexadecimal digits representing the hexadecimal-encoded character value).

<P> There is also an RMS standard for handling characters in extended file
specifications, some of which are forbidden in the ODS-2 file naming
conventions, and others which have a reserved meaning to either the command-line
interpreter (e.g. the space) or the file system structure (e.g. the <QUOTE>(:),
<QUOTE>([), <QUOTE>(]) and <QUOTE>(.)).  Generally the allowed but reserved
characters can be used in ODS-5 file names if escaped using the <QUOTE>(^)
character.  For example, the ODS-2 file name <QUOTE>(THIS_AND_THAT.TXT) could
be named <QUOTE>(This^_^&^_That.txt) on an ODS-5 volume.  More complex rules
control the use of character combinations with significance to RMS, for
instance multiple periods.  The following file name is allowed on an ODS-5
volume, <QUOTE>(A-GNU-zipped-TAR-archive^.tar.gz), where the non-significant
period has been escaped making it acceptable to RMS.

<P> The WASD server will accept request paths for file specifications in both
formats, URL-encoded and RMS-escaped.  Of course characters absolutely
forbidden in request paths must still be URL-encoded, the most obvious example
is the space.  RMS will accept the file name <QUOTE>(This^ and^ that.txt) (i.e.
containing escaped spaces) but the request path would need to be specified as
<QUOTE>(This%20and%20that.txt), or possibly <QUOTE>(This^%20and^%20that.txt)
although the RMS escape character is basically redundant.

<P> Unlike for ODS-2 volumes, ODS-5 volumes do not have <QUOTE>(invalid)
characters, so unlike with ODS-2 no processing is performed by the server to
ensure RMS compliance.

<HEAD2>(Characters In Server-Generated Paths\head_mapping_generated_paths)

<P> When the server generates a path to be returned to the browser, either in a
viewable page such as a directory listing or error message, or as a part of the 
HTTP transaction such as a redirection, the path will contain the URL-encoded
equivalent of the <EMPHASIS>(canonical form) of an extended file specification
escaped character.  For example, the file name <QUOTE>(This^_and^_that.txt)
will be represented by <QUOTE>(This%20and%20that.txt).

<P> When presenting a file name in a viewable page the general rule is to also
provide this URL-equivalent of the unescaped file name, with a small number of
exceptions.  The first is a directory listing where VMS format has been
requested by including a version component in the request file specification. 
The second is in similar fashion, but with the <EMPHASIS>(tree) facility,
displaying a directory tree.  The third is in the navigation page of the
<EMPHASIS>(UPDate) menu.  In all of the instances the canonical form of the
extended file specification is presented (although any actual reference to the
file is URL-encoded as described above). 

<HEAD2>(Document Cache\head_document_cache)

<P> The Web server is most commonly set up to cache static documents (files). 
A cache is higher speed storage, in-memory, in the server itself.  Cached
documents are checked periodically for changes when being requested.  Changes
to a file are determined by the comparing the modification date/time and file
length.  A common check period is one minute, though it can set longer or even
disabled.  If a document has changed the old one is discarded from cache
(called invalidation) and the new one loaded into cache while being transfered
to the client.

<P> After making changes to a document it is possible the server will continue
to serve the old one for a short period.  This can be overridden by using the
browser's <EMPHASIS>(Reload) facility.  This directs the server to go and check
the on-disk file regardless, invalidating it if necessary.

<COMMENT>(--------------------------------------------------------------------)

<CHAPTER>(Directory Listing\chapter_directory_listing)

<P> A directory listing is sometimes refered to as a document 
<EMPHASIS>(Index), and is generally titled <QUOTE>(Index of <HELLIPSIS>). 

<P> Unless disabled by the server's configuration, a directory listing is 
recognised by the server whenever a wildcard is present in a specification and 
there is no query string directing another activity (e.g. a document search).  
Compliant with other hypertext implementations, a directory listing is also 
generated if a URL specifies a directory only and that directory contains no 
home page. 

<P> <EMPHASIS>(All specifications must be made using URL-style paths.\BOLD)  
See <REFERENCE>(head_document_specification).

<P> The directory listing is designed to look very much like the basic layout 
of other servers, except that all directories are grouped at the top.  In the 
opinion of the author, this looks and functions better than when interspersed
with the files, as is otherwise common.  The default listing provides: 

<LIST>(UNNUMBERED)
<LE> iconic indication of the data type
<LE> file name
<LE> last revison date/time
<LE> size
<LE> description
<ENDLIST>

<P> The description can be either be just that, a description of the role of
that type of file under VMS, or  if presented within quotes, an HTML
document's own internal description taken from the
<QUOTE>(<LITERAL>(<TITLE></TITLE>)) element.

<P> Note that directory listings only processes the physical file system.  
This may or may not correspond to the hypertext environment's virtual
mappings. 

<P> The following link illustrates the directory listing format:

<COMMENT>(....................................................................)

<COMMENT>(HTML=<A HREF="*.*">*.*</A>)

<COMMENT>(HTML/OFF)
<CODE_EXAMPLE>
  <LITERAL>(<A HREF="*.*">*.*</A>)
<ENDCODE_EXAMPLE>
<P><BOX>(online demonstration)
<COMMENT>(HTML/ON)

<COMMENT>(....................................................................)

<COMMENT>(--------------------------------------------------------------------)

<HEAD>(VMS-ish Format\head_directory_vmsish)

<P> The default listing has a <EMPHASIS>(generic) WWW look about it, however
it can be made to look a little more like the format of the VMS
<QUOTE>(DIRECTORY) command. In this mode the directories are presented as VMS
subdirectories, the version number is shown, if a version wildcard was
included in the specification then all matching versions are shown, the size
is presented in used and allocated blocks, and automatic script activation is
disabled. The VMS-style format is enabled by providing an explicit or wildcard
version number with the specification, as in the following example:

<COMMENT>(....................................................................)

<COMMENT>(HTML=&nbsp;<A HREF="*.*;">*.*;</A>)

<COMMENT>(HTML/OFF)
<LITERAL>(<A HREF="*.*;">*.*;</A>)

<BOX>(online demonstration)
<COMMENT>(HTML/ON)

<COMMENT>(....................................................................)

<COMMENT>(--------------------------------------------------------------------)

<HEAD1>(Controlling Access To A Directory\head_www_hidden)

<P> The following files (empty, or not), when within a specific directory 
regulate access to that directory, and the listing of any parent directory or 
subdirectories. 

<LIST>(UNNUMBERED)

<LE> <QUOTE>(.WWW_HIDDEN) 
<LINE> Renders the directory completely invisible to the directory listing 
mechanism.  Files within the directory may still be accessed if specified 
explicitly but the directory content itself cannot be listed by any means. 

<LE> <QUOTE>(.WWW_NOWILD) 
<LINE> Renders the directory incapable of being listed using <QUOTE>(*.*)
characters at the end of the path, even if allowed by the server.  This is a
little different to <QUOTE>(.WWW_HIDDEN), which hides the
directory completely.  The <EMPHASIS>(no-wild) still allows a directory without
a home page to list as a directory, it does however <EMPHASIS>(prevent the
forced listing using the <QUOTE>(*.*) syntax\BOLD).

<LE> <QUOTE>(.WWW_NOP) 
<LINE> Any parent directory is not listed.

<LE> <QUOTE>(.WWW_NOS) 
<LINE> Any subdirectories are not listed.

<LE> <QUOTE>(.WWW_NOPS) 
<LINE> Any parent directory or subdirectories are not listed.

<ENDLIST>

<COMMENT>(--------------------------------------------------------------------)

<HEAD1>(<QUOTE>(Hidden) Files\head_hidden_files)

<P> Any file name beginning with a period is hidden from the directory listing 
mechanism (i.e. in VMS parlance it has only a type/suffix/extension).  If 
specifically accessed they will be retrieved however.  Hence the following 
files would not appear in a directory listing: 

<LIST>(UNNUMBERED)
<LE> <QUOTE>(.WWW_NOPS)
<LE> <QUOTE>(.CANT_BE_SEEN)
<LE> <QUOTE>(.HIDDEN_FROM_VIEW)
<LE> <QUOTE>(.;1)
<ENDLIST>

<COMMENT>(--------------------------------------------------------------------)

<HEAD1>(Server Directives\head_directory_directives)

<P> The WASD server behaviour can be modified using <EMPHASIS>(server 
directives).  For directory listings this involves the inclusion of a query 
string beginning with <QUOTE>(?httpd=index).  The server 
detects this query string and processes it internally, changing the default 
action of directory listings.

<P> Multiple directives can be combined by concatenating them with intervening 
ampersands, as per normal URL syntax.

<CODE_EXAMPLE>
  ?httpd=index&autoscript=no
  ?httpd=index&readme=no
  ?httpd=index&type=text/plain
  ?httpd=index&layout=<EMPHASIS>(format)
  ?httpd=index&script=<EMPHASIS>(script-name)
  ?httpd=index&script=<EMPHASIS>(script-name)&readme=no
  ?httpd=index&delimit=none&readme=no&nos=yes
<ENDCODE_EXAMPLE>

<COMMENT>(--------------------------------------------------------------------)

<HEAD2>(Layout\head_directory_layout)

<P> Allows specification of the directory listing layout from the URL,
overriding the server default. The layout directive is a short,
case-insensitive string that specifies the included fields, relative placement
and optionally the width of the fields in a directory listing. Each field is
controlled by a single letter (one with colon-separated parameter) and
optional leading decimal number specifying its width. When a width is not
specified an appropriate default applies. An underscore is used to indicate a
single space and is used to separate the fields (two consecutive works well). 

<COMMENT>(HTML=<P>)

<LIST>(UNNUMBERED)
<LE><EMPHASIS>(C\BOLD) - creation date
<LE><EMPHASIS>(D\BOLD) - description (often best specified last)
<LIST>(UNNUMBERED)
<LE><EMPHASIS>(D:L\BOLD) - for files, make a link out of the description text
<ENDLIST>
<LE><EMPHASIS>(I\BOLD) - icon (takes no field-width attribute)
<LIST>(UNNUMBERED)
<LE><EMPHASIS>(L\BOLD) - link (highlighted anchor using the name of the file)
<LE><EMPHASIS>(L:F\BOLD) - file-system name (for ODS-5 displays spaces, etc.) 
<LE><EMPHASIS>(L:N\BOLD) - name-only, do not display the extension
<LE><EMPHASIS>(L:U\BOLD) - force name to upper-case
<ENDLIST>
<LE><EMPHASIS>(N\BOLD) - name (no link, why bother? who knows!)
<LE><EMPHASIS>(O\BOLD) - owner (can be disabled)
<LE><EMPHASIS>(R\BOLD) - revision date
<LE><EMPHASIS>(S\BOLD) - size
<LIST>(UNNUMBERED)
<LE><EMPHASIS>(S:B\BOLD) - in bytes (comma-formatted)
<LE><EMPHASIS>(S:D\BOLD) - decimal kilos (see below)
<LE><EMPHASIS>(S:F\BOLD) - kilo and mega are displayed to one decimal place
<LE><EMPHASIS>(S:K\BOLD) - in kilo-bytes (and fractions thereof)
<LE><EMPHASIS>(S:M\BOLD) - in mega-bytes (and fractions thereof)
<ENDLIST>
<LE><EMPHASIS>(U\BOLD) - upper-case file and directory names (must be the
first character)
<ENDLIST>

<COMMENT>(HTML=<P>)

<P> The default layout is:

<CODE_EXAMPLE>
  I__L__R__S__D
<ENDCODE_EXAMPLE>

<P> The following provide other examples:

<CODE_EXAMPLE>
  ?httpd=index&layout=UI__L__R__S__D
  ?httpd=index&layout=I__L__R__S:b__D
  ?httpd=index&layout=I__L__R__S__D
  ?httpd=index&layout=I__15L__S__D
  ?httpd=index&layout=15L__9R__S
  ?httpd=index&layout=15N_9C_9R_S
<ENDCODE_EXAMPLE>

<P> The size of files is displayed by default as 1024 byte kilos.  When using
the <QUOTE>(S:k), <QUOTE>(S:m) and <QUOTE>(S:f) size modifiers the size is
displayed as 1000 byte kilos.  If it is prefered to have the default display
in 1000 byte kilos then set the directory listing layout using:

<CODE_EXAMPLE>
  ?httpd=index&layout=I__L__R__S:d__D
<ENDCODE_EXAMPLE>

<P> If unsure of the kilo value being used check the
<QUOTE>(<LITERAL>(<META>)) information in the directory listing.

<COMMENT>(....................................................................)

<COMMENT>(HTML=
<P> The following links illustrate this functionality by listing this 
document's directory in a default and then three other formats.

<P> <A HREF="*.*">Default</A>.

<BR> <A HREF="*.*?httpd=index&layout=I__L">Only an icon and link</A>.

<BR> <A HREF="*.*;?httpd=index&layout=I__L__S">Icon, link and 
size</A> (in VMS-style format). 

<BR> <A HREF="*.*?httpd=index&layout=N__9C__9R">Name, day created and
day revised</A>.

<BR> <A HREF="*.*?httpd=index&layout=UN__9C__9R">Name (in upper-case), day
created and day revised</A>.

<BR> <A HREF="*.*?httpd=index&layout=30D:l__S:b__R">Description (fixed width)
as a link, size in bytes, and day revised</A>.
)

<COMMENT>(HTML/OFF)
<P><BOX>(online demonstration)
<COMMENT>(HTML/ON)

<COMMENT>(....................................................................)

<COMMENT>(--------------------------------------------------------------------)

<HEAD2>(Readme Files\head_directory_readme)

<P> When a directory listing is generated any <QUOTE>(README.),
<QUOTE>(README.TXT) or <QUOTE>(README.HTML) file (or 
others as configured for the particular server) in the directory will have its 
contents displayed immediately below the title of the page.  This allows 
additional information on the directory's contents, function, etc., to be 
presented.  This can be suppressed by appending the following query-string to 
the directory specification, as in the accompanying example: 

<CODE_EXAMPLE>
  ?httpd=index&readme=no

  <LITERAL>(<A HREF="*.*?httpd=index&readme=no">*.* (no <I>readme</I>s)</A>)
<ENDCODE_EXAMPLE>

<P> Read-me files can be SSI documents if configured by the server
administrator. General SSI guidelines apply to these, see
<REFERENCE>(chapter_ssi)

<COMMENT>(--------------------------------------------------------------------)

<HEAD2>(Listing Delimiters\head_directory_delimit)

<P> A directory listing is normally delimited by a header, comprising an
<QUOTE>(Index of), column headings and horizontal line, and a footer,
comprising a horizintal line.  This default behaviour may be modified using the
<QUOTE>(delimit=) directive.

<LIST>(UNNUMBERED)

<LE> <EMPHASIS>(header - \BOLD) 
a header comprising a horizontal rule and column heading is generated

<LE> <EMPHASIS>(footer - \BOLD) 
a footer comprising a horizontal rule is generated

<LE> <EMPHASIS>(none - \BOLD) 
no header or footer is generated

<LE> <EMPHASIS>(both - \BOLD) 
both header and footer is generated (default)

<ENDLIST>

<CODE_EXAMPLE>
  ?httpd=index&delimit=none

  ?httpd=index&delimit=top
<ENDCODE_EXAMPLE>

<COMMENT>(--------------------------------------------------------------------)

<HEAD2>(Suppressing Directories\head_directory_suppress)

<P> Parent and subdirectories may be suppressed in a listing using the
<QUOTE>(nop), <QUOTE>(nops) and <QUOTE>(nos) directives.  These parallel the
purpose of the directory listing control files described in
<REFERENCE>(head_www_hidden), and if set to true suppress the listing of the
corresponding directories.

<LIST>(UNNUMBERED)

<LE> <EMPHASIS>(nop - \BOLD) 
any parent directory is not listed

<LE> <EMPHASIS>(nops - \BOLD) 
any subdirectories are not listed

<LE> <EMPHASIS>(nos - \BOLD) 
any parent directory or subdirectories are not listed

<ENDLIST>

<CODE_EXAMPLE>
  ?httpd=index&nop=yes

  ?httpd=index&nops=yes

  ?httpd=index&nos=yes
<ENDCODE_EXAMPLE>

<COMMENT>(--------------------------------------------------------------------)

<HEAD2>(Listing Refresh and Expiry\head_dir_refresh_expiry)

<P> Directory listings and trees may be <EMPHASIS>(pre-expired).  That is, the
listing is reloaded each time the page is referenced.  This is convenient in
some environments where directory contents change frequently, but adds
considerable over-head and so is often disabled by default.  Individual
directory listings may have either default behaviour over-ridden using syntax
similar to the following examples:

<CODE_EXAMPLE>
  /dir1/dir2/*.*?httpd=index?expired=yes
  /dir1/dir2/*.*?httpd=index?expired=no
  /tree/dir1/dir2/?httpd=index?expired=yes
  /tree/dir1/dir2/?httpd=index?expired=no
<ENDCODE_EXAMPLE>

<COMMENT>(--------------------------------------------------------------------)

<HEAD2>(Scripting From Directory Listings\head_directory_scripting)

<P> When a directory listing is requested a script name can be specified to be 
used as a prefix to all of the file links in the listing.  When the client 
selects a file link the script specified is implicitly activated. 

<CODE_EXAMPLE>
  ?httpd=index&script=script_name

  <LITERAL>(<A HREF="*.*?httpd=index&script=print">print *.*</A>)
<ENDCODE_EXAMPLE>

<COMMENT>(....................................................................)

<COMMENT>(HTML=
<P> The following link illustrates this facility by specifying the 
<EMPHASIS>(print) script.  When a link is selected the print script presents a 
form to allow the file to be printed: 

<P> <A HREF="*.*?httpd=index&script=print">print *.*</A>
)

<COMMENT>(HTML/OFF)
<P><BOX>(online demonstration)
<COMMENT>(HTML/ON)

<COMMENT>(....................................................................)

<COMMENT>(--------------------------------------------------------------------)

<HEAD2>(Auto-Scripting\head_directory_autoscripting)

<P> The server's <EMPHASIS>(auto-scripting) facility (see 
<REFERENCE>(head_autoscripting)) can be suppressed by appending the following 
query-string to the directory specification, as in the accompanying example: 

<CODE_EXAMPLE>
  ?httpd=index&autoscript=no

  <LITERAL>(<A HREF="*.*?httpd=index&autoscript=no">get me *.*</A>)
<ENDCODE_EXAMPLE>

<P> This implies that any file accessed from the listing will be transfered 
without any data conversion possible due to script activation (see 
<REFERENCE>(head_scripts)).  The browser must then process the document in 
some fashion (often by activating a <EMPHASIS>(save as) dialog).

<COMMENT>(....................................................................)

<COMMENT>(--------------------------------------------------------------------)

<HEAD2>(Specifying Content-Type\head_dir_content_type)

<P> When accessing files it is possible to explicitly specify the identifying
content-type to be returned to the browser in the HTTP response header.  Of
course this does not change the actual content of the file, just the header
content-type!  This is primarily provided to allow access to plain-text
documents that have obscure, non"-standard" or non-configured file extensions.
See <REFERENCE>(head_explicit_type).

<P> It could also be used for other purposes, "forcing" the browser to accept a
particular file as a particular content-type.  This can be useful if the
extension is not configured (as mentioned above) or in the case where the file
contains data of a known content-type but with an extension conflicting with an
already configured extension specifying data of a different content-type.

<P> It is posssible to "force" the content-type for all files in a particular
directory.  Enter the path to the directory and then add

<CODE_EXAMPLE>
  ?httpd=index&type=text/plain
<endCODE_EXAMPLE>

<P> (or what-ever type is desired).  Links to files in the listing will contain
the appropriate <QUOTE>(?httpd=content&type=...) appended as a query string.

<P> This is an example:

<COMMENT>(....................................................................)

<COMMENT>(HTML=
<PRE>
  <A HREF="*.*">*.*</A>

  <A HREF="*.*?httpd=index&type=text/plain">*.*?httpd=index&type=text/plain</A>
</PRE>
)

<COMMENT>(HTML/OFF)
<P><BOX>(online demonstration)
<COMMENT>(HTML/ON)

<COMMENT>(--------------------------------------------------------------------)

<HEAD1>(Directory Tree\head_dtree)

<P> The <QUOTE>(Tree) internal script allows a directory tree to
be  generated.  This script is supplied with a directory name from which it
displays all subdirectories in a hierarchical layout, showing subordinancies. 
Selecting any one of the subdirectories displayed generates a directory 
listing (see <REFERENCE>(chapter_directory_listing)). 

<P> Appending a file specification (with or without wildcards) to the 
directory name results in the any directory listing displaying only files 
matching the specification.  To display all files a <QUOTE>(*.*) 
should always be appended. 

<P> Note that this script only processes the physical file system.  This may 
or may not correspond to the hypertext environment's virtual mappings. 

<P> To enable the VMS-style directory listing format, or to use any of the 
directory server directives, append one, or a combination of, the following 
query strings to the directory specification: 

<CODE_EXAMPLE>
  ?httpd=index&autoscript=no
  ?httpd=index&readme=no
  ?httpd=index&script=<EMPHASIS>(script-name)
  ?httpd=index&script=<EMPHASIS>(script-name)&readme=no
<ENDCODE_EXAMPLE>

<COMMENT>(....................................................................)

<COMMENT>(HTML=
<P> The following links provide online demonstrations:

<P> <A HREF="/tree/ht_root/*.*">/ht_root/</A> tree

<BR> <A HREF="/tree/ht_root/*.*;*">/ht_root/ (VMS-ish)</A> tree
) 

<COMMENT>(HTML/OFF)
<CODE_EXAMPLE>
<LITERAL>(<A HREF="/tree/ht_root/*.*">/ht_root/</A> tree)

<LITERAL>(<A HREF="/tree/ht_root/*.*;*">/ht_root/ (VMS-ish)</A> tree)
<ENDCODE_EXAMPLE>

<P><BOX>(online demonstration)
<COMMENT>(HTML/ON) 

<COMMENT>(....................................................................)

<P> Note that this activity is I/O intensive, and can take a considerable 
period if the tree is extensive. 

<NOTE>
The <QUOTE>(tree) internal script supercededs the <QUOTE>(Dtree) external
script which has been retired.
<ENDNOTE>

<COMMENT>(--------------------------------------------------------------------)

<CHAPTER>(Server Side Includes (SSI)\chapter_ssi)

<P> 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 <EMPHASIS>(directives), which are replaced by dynamic 
information based upon the particular directive. 

<P> 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
<REFERENCE>(head_ssi_flow_control). These extensions allow quite versatile
documents to be created without resorting to script processing.

<P> Two documents are provided as examples of SSI processing.

<LIST>(UNNUMBERED)

<LE> <EMPHASIS>(A simple SSI document.\BOLD)

<P>
<COMMENT>(HTML=
<A HREF="ssi.txt">HT_ROOT:[DOC.ENV]SSI.SHTML</A>
&nbsp;&nbsp;(<A HREF="ssi.shtml">access as SSI</A>)
)

<COMMENT>(HTML/OFF)
HT_ROOT:[DOC.ENV]SSI.SHTML
<P><BOX>(online demonstration)
<COMMENT>(HTML/ON)

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(An SSI document using variable assignment and flow-control.\BOLD)

<P>
<COMMENT>(HTML=
<A HREF="xssi.txt">HT_ROOT:[DOC.ENV]XSSI.SHTML</A>
&nbsp;&nbsp;(<A HREF="xssi.shtml">access as SSI</A>)
)

<COMMENT>(HTML/OFF)
HT_ROOT:[DOC.ENV]SSI.SHTML
<P><BOX>(online demonstration)
<COMMENT>(HTML/ON)

<ENDLIST>

<P> By default the HTML pre-processor is invoked when the document file's
extension is <QUOTE>(.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.

<P> Essential compatibility with OSU Server Side Includes is provided.  This
may ease any transition between the two.  See <REFERENCE>(head_ssi_osu) for
further information.

<P> Also see <REFERENCE>(head_ssi_scrunched_doc).  It contains
valuable information on reducing the resources involved in processing
SSI documents, improving system impact and document response times.

<COMMENT>(....................................................................)

<HEAD1>(Virtual Documents\head_ssi_virtual_doc)

<P> 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
<REFERENCE>(head_ssi_last_modified)), loses the advantages of
"If-Modified-Since:" processing (see <REFERENCE>(chapter_httpd)).

<HEAD>(Example 1\head_ssi_virtual_example_1)

<P> 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).

<CODE_EXAMPLE><LITERAL>
  <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>
<ENDLITERAL><ENDCODE_EXAMPLE>

<P> 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 <EMPHASIS>(throw) a file at the network, than parse every character
in one ;^)

<CODE_EXAMPLE><LITERAL>
  <HTML>
  <HEAD>
  <TITLE>Just an example!</TITLE>
  </HEAD>
  <!--#include virtual="header.shtml" -->
  <!--#include virtual="example.html" -->
  <!--#include virtual="footer.shtml" -->
  </HTML>
<ENDLITERAL><ENDCODE_EXAMPLE>

<HEAD>(Example 2\head_ssi_virtual_example_2)

<P> 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.

<P> File 1; the document accessed via the browser URL, doesn't matter what
it's name is, this configuration is completely naming independent.

<CODE_EXAMPLE><LITERAL>
  <!--#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
  -->
<ENDLITERAL><ENDCODE_EXAMPLE>

<P> File 2; the TEMPLATE.SHTML refered to by the first include above.

<CODE_EXAMPLE><LITERAL>
  <!--#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"
  -->
<ENDLITERAL><ENDCODE_EXAMPLE>

<P> File 3; the DOCUMENT.HTML refered to by the second include in file 1.

<CODE_EXAMPLE><LITERAL>
  <P> This is just a <B>bunch of HTML</B>!
<ENDLITERAL><ENDCODE_EXAMPLE>

<P> <EMPHASIS>(This is an explanation of how it works <HELLIPSIS>\BOLD)

<LIST>(NUMBERED)

<LE> the browser accesses file 1 via a URL
<LE> processing begins with file 1
<LE> file 1 checks if it has a parent (is the first file processed),
<LINE> <EMPHASIS>(it doesn't and so <HELLIPSIS>\BOLD)
<LE> file 1 set a variable named TITLE
<LE> file 1 #includes file 2, a site-common template
<LE> file 2 substitutes the TITLE variable contents as the document title
<LE> file 2 #includes a site-common header
<LE> file 2 #includes an optional document-local header
<LE> <EMPHASIS>(here's the interesting bit <HELLIPSIS>\BOLD)
<LINE> file 2 now re-#includes the original document, file 1 (!!)
<LE> file 1 checks if it has a parent (is the first file processed),
<LINE> <EMPHASIS>(it does and so <HELLIPSIS>\BOLD)
<LE> file 1 #includes file 3 (the actual contents of the document)
<LE> file 3 is a plain HTML document, just added to the output
<LE> file 1 is now exhausted and processing returns to file 2
<LE> file 2 #includes an optional document-local footer
<LE> file 2 #includes a site-common footer
<LE> file 2 is exhausted and processing returns to file 1
<LE> file 1 is exhausted and processing stops

<ENDLIST>

<P> 

<COMMENT>(HTML=
<P> The following link provides an example of a
<A HREF="example_document.shtml">such a virtual document</A>.
)

<COMMENT>(HTML/OFF)
<P> The following link provides an example of such a virtual document.
<P><BOX>(online demonstration)
<COMMENT>(HTML/ON)

<COMMENT>(....................................................................)

<HEAD1>(Last-Modified Information\head_ssi_last_modified)

<P> 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
<QUOTE>(Last-Modified: <EMPHASIS>(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
(<QUOTE>(If-Modified-Since: <EMPHASIS>(timestamp))), are significant against
the CPU overheads of processing SSI documents.

<P> 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.

<P> The <EMPHASIS>(if-modified-since) tag compares the determined revision
date/time of the document file(s) with any <QUOTE>(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 <QUOTE>(Last-Modified:) header field is
added to the document and it continues to be processed.

<P> If a request has a "Pragma: no-cache" field (as with Navigator's
<EMPHASIS>(reload) function) the document is always generated (this is
consistent with general WASD behaviour).

The following example illustrates the essential features.

<CODE_EXAMPLE><LITERAL>
  <!--#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
  -->
<ENDLITERAL><ENDCODE_EXAMPLE>

<P> 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).

<COMMENT>(....................................................................)

<HEAD1>(Pre-Expiring Documents\head_ssi_pre_expire)

<P> SSI preprocessed documents are <EMPHASIS>(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 <EMPHASIS>(expire).  This will result
in the document being reloaded with each access.  This can be accomplished two
ways.

<LIST>(UNNUMBERED)

<COMMENT>(HTML=<P>)

<LE> Use the #modified directive to include an <QUOTE>(Expires:
<EMPHASIS>(timestamp)) response header field.  Place the following construct at
the beginning of the SSI document.

<CODE_EXAMPLE><LITERAL>
  <!--#modified expires="Fri, 13 Jan 1978 14:00:00 GMT" -->
<ENDLITERAL><ENDCODE_EXAMPLE>

<COMMENT>(HTML=<P>)

<LE> Ensure the document is structured similar to the following and include the
<LITERAL>(<META HTTP-EQUIV= ...>) tag with a legitimate date well in the past:

<CODE_EXAMPLE><LITERAL>
  <!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>
<ENDLITERAL><ENDCODE_EXAMPLE>

<ENDLIST>

<HEAD1>(Directive Syntax\head_preprocessing_syntax)

<P> 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: 

<CODE_EXAMPLE>
  <LITERAL>(<)!--#<EMPHASIS>(directive\BOLD) [[<EMPHASIS>(tag1\BOLD)="<EMPHASIS>(value)"] [<EMPHASIS>(tag2\BOLD)="<EMPHASIS>(value)"] ...] --<LITERAL>(>)
<ENDCODE_EXAMPLE>

<P> A <EMPHASIS>(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
<REFERENCE>(head_ssi_variables).  A value must be encolosed by quotation
marks if it contains white-space.

<P> A directive <EMPHASIS>(can be split over multiple lines\BOLD) provided the
new line begins naturally on white-space within the directive.  For example,
this is correctly split

<CODE_EXAMPLE>
  <LITERAL>(<!--#echo
  created[="<EMPHASIS>(time-format)"] -->)
<ENDCODE_EXAMPLE>

<CP> while the following is not (and would produce an error)

<CODE_EXAMPLE>
  <LITERAL>(<!--#echo creat
  ed[="<EMPHASIS>(time-format)"] -->)
<ENDCODE_EXAMPLE>

<P> 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.

<HEAD1>(Directives\head_preprocessing_directives)

<P>
<TABLE>
<TABLE_SETUP>(3\10\30)
<TABLE_HEADS>(Directive\Description\Section)
<COMMENT>(HTML=<TR></TR>)
<TABLE_ROW>(<EMPHASIS>(#accesses\BOLD)\document access count\
<REFERENCE>(head_ssi_accesses))
<TABLE_ROW>(<EMPHASIS>(#config\BOLD)\document processing options\
<REFERENCE>(head_ssi_config))
<TABLE_ROW>(<EMPHASIS>(#dir\BOLD)\directory listing\
<REFERENCE>(head_ssi_dir))
<TABLE_ROW>(<EMPHASIS>(#dcl\BOLD)\DCL command processing\
<REFERENCE>(head_ssi_dcl))
<TABLE_ROW>(<EMPHASIS>(#echo\BOLD)\output information\
<REFERENCE>(head_ssi_echo))
<TABLE_ROW>(<EMPHASIS>(#elif\BOLD)\flow control\
<REFERENCE>(head_ssi_elif))
<TABLE_ROW>(<EMPHASIS>(#else\BOLD)\flow control\
<REFERENCE>(head_ssi_else))
<TABLE_ROW>(<EMPHASIS>(#endif\BOLD)\flow control\
<REFERENCE>(head_ssi_endif))
<TABLE_ROW>(<EMPHASIS>(#exec\BOLD)\same as <QUOTE>(#dcl)\
<REFERENCE>(head_ssi_exec))
<TABLE_ROW>(<EMPHASIS>(#exit\BOLD)\flow control, stop current document processing\
<REFERENCE>(head_ssi_exit))
<TABLE_ROW>(<EMPHASIS>(#fcreated\BOLD)\output file creation date/time\
<REFERENCE>(head_ssi_fcreated))
<TABLE_ROW>(<EMPHASIS>(#flastmod\BOLD)\output file last modification date/time\
<REFERENCE>(head_ssi_flastmod))
<TABLE_ROW>(<EMPHASIS>(#fsize\BOLD)\output file size\
<REFERENCE>(head_ssi_fsize))
<TABLE_ROW>(<EMPHASIS>(#if\BOLD)\flow control\
<REFERENCE>(head_ssi_if))
<TABLE_ROW>(<EMPHASIS>(#include\BOLD)\include a text file or another SSI document\
<REFERENCE>(head_ssi_include))
<TABLE_ROW>(<EMPHASIS>(#modified\BOLD)\HTTP response control\
<REFERENCE>(head_ssi_modified))
<TABLE_ROW>(<EMPHASIS>(#orif\BOLD)\flow control\
<REFERENCE>(head_ssi_orif))
<TABLE_ROW>(<EMPHASIS>(#printenv\BOLD)\list document variables\
<REFERENCE>(head_ssi_printenv))
<TABLE_ROW>(<EMPHASIS>(#set\BOLD)\assign value to a document variable\
<REFERENCE>(head_ssi_set))
<TABLE_ROW>(<EMPHASIS>(#ssi\BOLD)\block of SSI statements\
<REFERENCE>(head_ssi_ssi))
<TABLE_ROW>(<EMPHASIS>(#stop\BOLD)\stop SSI processing completely\
<REFERENCE>(head_ssi_stop))
<ENDTABLE>

<COMMENT>(....................................................................)

<HEAD2>(#ACCESSES\head_ssi_accesses)

<P> The <EMPHASIS>(#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: 

<LIST>(UNNUMBERED)

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(ORDINAL\BOLD)

<CODE_EXAMPLE>
  <LITERAL>(<)!--#accesses ordinal --<LITERAL>(>)
<ENDCODE_EXAMPLE>

<P> Provides the count as 1st, 2nd, 3rd, 4th, 5th <HELLIPSIS> 10th, 11th, 12th
<HELLIPSIS> 120th, 121st, 122nd, etc.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(SINCE\BOLD)

<CODE_EXAMPLE>
  <LITERAL>(<)!--#accesses since="<EMPHASIS>(text)" --<LITERAL>(>)
<ENDCODE_EXAMPLE>

<P> This tag includes the specified text immediately after the access count is 
displayed, then adds the creation date of the counter file.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(TIMEFMT\BOLD)

<CODE_EXAMPLE>
  <LITERAL>(<)!--#accesses since="<EMPHASIS>(text)" timefmt="[<EMPHASIS>(time-format)]" --<LITERAL>(>)
<ENDCODE_EXAMPLE>

<CP> Allows the time format of the <EMPHASIS>(since) tag to be supplied, where 
<EMPHASIS>(time-format) is specified according to 
<REFERENCE>(head_ssi_time_format). 

<ENDLIST>

<COMMENT>(....................................................................)

<HEAD2>(#CONFIG\head_ssi_config)

<P> The <EMPHASIS>(#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 <EMPHASIS>(config) directive.  A 
<EMPHASIS>(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. 

<LIST>(UNNUMBERED)

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(ERRMSG\BOLD)

<CODE_EXAMPLE>
  <LITERAL>(<)!--#config errmsg="<EMPHASIS>(string)" --<LITERAL>(>)
<ENDCODE_EXAMPLE>

<P> 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. 

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(TIMEFMT\BOLD)

<CODE_EXAMPLE>
  <LITERAL>(<)!--#config timefmt="<EMPHASIS>(time-format)" --<LITERAL>(>)
<ENDCODE_EXAMPLE>

<CP> Where <EMPHASIS>(time-format) is specified according to
<REFERENCE>(head_ssi_time_format).

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(SIZEFMT\BOLD)

<CODE_EXAMPLE>
  <LITERAL>(<)!--#config sizefmt="<EMPHASIS>(size-format)" --<LITERAL>(>)
<ENDCODE_EXAMPLE>

<CP> Where <EMPHASIS>(size-format) is specified using the following keywords:

<LIST>(UNNUMBERED)
<LE> <QUOTE>(abbrev) (as bytes, kbytes, Mbytes)
<LE> <QUOTE>(blocks) (VMS blocks, used)
<LE> <QUOTE>(bytes) (e.g. <QUOTE>(1,256,731 bytes))
<ENDLIST>

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(TRACE\BOLD)

<CODE_EXAMPLE>
  <LITERAL>(<)!--#config trace="<EMPHASIS>(1)|<EMPHASIS>(0)"  --<LITERAL>(>)
<ENDCODE_EXAMPLE>

<P> Switches document processing trace on or off, intended for use when
debugging more complex or flow-controlled SSI documents.

<P> Output from a trace is colour-coded.

<LIST>(UNNUMBERED)

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(Blue - \BOLD)
As a line is read from the document is is displayed in blue.  The text is
preceded by a square-bracketed source file line number and flow-control level.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(Red - \BOLD)
As an SSI statement is actually processed it is displayed in red. Due to
document parsing this may occur at some point after the line is read from file.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(Magenta - \BOLD)
As variables are set or read the variable name and value is displayed.  A
variable set has the name separated from the value by an equate symbol
(<QUOTE>(=)), when being read the character is a full-colon (<QUOTE>(:)). 

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(Black - \BOLD)
Document (HTML and text) output is displayed as black plain text.

<ENDLIST>

<COMMENT>(HTML=
<P> The following link provides an example of a
<A HREF="xssi.shtml?httpd=ssi&trace=on">document trace</A>.
)

<COMMENT>(HTML/OFF)
<P> The following link provides an example of a document trace.
<P><BOX>(online demonstration)
<COMMENT>(HTML/ON)

<ENDLIST>

<COMMENT>(....................................................................)

<HEAD2>(#DIR\head_ssi_dir)

<P> The <EMPHASIS>(#dir) directive generates an <EMPHASIS>(Index of 
<HELLIPSIS>) 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 <REFERENCE>(chapter_directory_listing)), including
query string format control via the <QUOTE>(par=) parameter (note that from the
<QUOTE>(?httpd=index) introducer used with directory listings is not necessary
from SSI). It is an WASD HTTPd extension to pre-processed HTML.

<LIST>(UNNUMBERED)

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(FILE\BOLD)
<P> Listing specified using a VMS file path. 

<CODE_EXAMPLE>
  <LITERAL>(<)!--#dir file="<EMPHASIS>(file-name)" [par="<EMPHASIS>(server-directive(s))"] --<LITERAL>(>)
<ENDCODE_EXAMPLE>

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(VIRTUAL\BOLD)
<P> Listing specified using URL-style syntax. 

<CODE_EXAMPLE>
  <LITERAL>(<)!--#dir virtual="<EMPHASIS>(path)" [par="<EMPHASIS>(server-directive(s))"] --<LITERAL>(>)
<ENDCODE_EXAMPLE>

<ENDLIST>

<P> For example:

<CODE_EXAMPLE>
  <LITERAL>(<!--#dir /ht_root/src/httpd/" -->)

  <LITERAL>(<!--#dir /ht_root/src/httpd/*.c" par="layout=UL__S&nops=yes" -->)
<ENDCODE_EXAMPLE>

<COMMENT>(....................................................................)

<HEAD2>(#DCL\head_ssi_DCL)

<P> The <EMPHASIS>(#dcl) directive executes a DCL command and incorporates the 
output into the processed document.  It is an WASD HTTPd extension to the more 
common <EMPHASIS>(exec) directive, which is also included.

<P> By default, output from the DCL command has all HTML-forbidden characters
(e.g. <QUOTE>(<LITERAL>(<)), <QUOTE>(<LITERAL>(&))) 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:

<CODE_EXAMPLE>
  type="text/html"
<ENDCODE_EXAMPLE>

<P> Some <EMPHASIS>(#dcl) directives are for <EMPHASIS>(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 <EMPHASIS>(innocuous) commands are allowed in standard documents. 

<LIST>(UNNUMBERED)

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(SAY\BOLD)
<P> Execute the DCL <QUOTE>(WRITE SYS$OUTPUT) command, using the 
specified parameter. 

<CODE_EXAMPLE>
  <LITERAL>(<!--#dcl say="hello." -->)
<ENDCODE_EXAMPLE>

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(SHOW\BOLD)
<P> Execute the DCL <QUOTE>(SHOW) command, using the specified 
parameter. 

<CODE_EXAMPLE>
  <LITERAL>(<!--#dcl show="device/full tape1:" -->)
<ENDCODE_EXAMPLE>

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(DIR\BOLD)
<P> Execute the DCL <QUOTE>(DIRECTORY) command, using the 
supplied file specification.  Qualifiers may be included in the optional
<QUOTE>(par) tag to control the format of the listing.

<CODE_EXAMPLE>
  <LITERAL>(<!--#dcl dir="web:[000000]" -->)
  <LITERAL>(<!--#dcl dir="web:[000000]" par="/nohead/notrail" -->)
  <LITERAL>(<!--#dcl dir="web:[000000]" par="/size/date" -->)
<ENDCODE_EXAMPLE>

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(EXEC\BOLD) (privileged)
<P> Execute the specified DCL command.

<CODE_EXAMPLE>
  <LITERAL>(<!--#dcl exec="show device/full tape1:" -->)
<ENDCODE_EXAMPLE>

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(FILE\BOLD) (privileged)
<P> Execute the DCL command procedure specified as a VMS file path, with any 
specified parameters applied to the procedure. 

<CODE_EXAMPLE>
  <LITERAL>(<!--#dcl file="HT_ROOT:[SHTML]TEST.COM" par="PARAM1 PARAM2" -->)
<ENDCODE_EXAMPLE>

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(VIRTUAL\BOLD) (privileged)
<P> Execute the DCL command procedure specified in URL-style syntax, with any 
specified parameters applied to the procedure. 

<CODE_EXAMPLE>
  <LITERAL>(<!--#dcl virtual="../shtml/test.com" par="PARAM1 PARAM2" -->)
<ENDCODE_EXAMPLE>

<ENDLIST>

<COMMENT>(....................................................................)

<HEAD2>(#ECHO\head_ssi_echo)

<P> The <EMPHASIS>(#echo) directive incorporates the specified information into 
the processed document. Multiple tags may be used within the one directive.

<LIST>(UNNUMBERED)

<LE> <EMPHASIS>(VALUE=\BOLD)
<LINE><EMPHASIS>(VAR=\BOLD)

<P> Any SSI variable (e.g. CREATED), CGI variable (e.g. HTTP_USER_AGENT),
or document assigned variable (e.g. EXAMPLE1), see
<REFERENCE>(head_ssi_variables).

<CODE_EXAMPLE>
  <LITERAL>(<)!--#echo value={created} var={example1} --<LITERAL>(>)
<ENDCODE_EXAMPLE>

<COMMENT>(HTML=<P>)
<LE> <EMPHASIS>(CREATED\BOLD)
<P> The date/time of the current document's creation.

<CODE_EXAMPLE>
  <LITERAL>(<)!--#echo created[="<EMPHASIS>(time-format)"] --<LITERAL>(>)
<ENDCODE_EXAMPLE>

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(DATE_LOCAL\BOLD)
<P> Include the current date/time.

<CODE_EXAMPLE>
  <LITERAL>(<)!--#echo date_local[="<EMPHASIS>(time-format)"] --<LITERAL>(>)
<ENDCODE_EXAMPLE>

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(DATE_GMT\BOLD)
<P> Include the current Greenwich Mean Time (UTC) date/time.

<CODE_EXAMPLE>
  <LITERAL>(<)!--#echo date_gmt[="<EMPHASIS>(time-format)"] --<LITERAL>(>)
<ENDCODE_EXAMPLE>

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(DOCUMENT_NAME\BOLD)
<P> The current document's URL-style path.

<CODE_EXAMPLE>
  <LITERAL>(<)!--#echo document_name --<LITERAL>(>)
<ENDCODE_EXAMPLE>

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(FILE_NAME\BOLD)
<P> The current document's VMS file path.

<CODE_EXAMPLE>
  <LITERAL>(<)!--#echo file_name --<LITERAL>(>)
<ENDCODE_EXAMPLE>

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(LAST_MODIFIED\BOLD)
<P> The date/time of the current document's last modification.

<CODE_EXAMPLE>
  <LITERAL>(<)!--#echo last_modified[="<EMPHASIS>(time-format)"] --<LITERAL>(>)
<ENDCODE_EXAMPLE>

<ENDLIST>

<COMMENT>(....................................................................) 

<HEAD2>(#ELIF\head_ssi_elif)

<P> The <EMPHASIS>(#elif) directive (else-if) allows blocks of HTML markup and
SSI directives to be conditionally processed, see
<REFERENCE>(head_ssi_flow_control) and <REFERENCE>(head_ssi_if).  This
directive effectively allows a <EMPHASIS>(case) statement to be constructed.


<CODE_EXAMPLE>
  <LITERAL>(<)!--#elif var="[<EMPHASIS>({variable})|<EMPHASIS>(literal)" --<LITERAL>(>)
<ENDCODE_EXAMPLE>

<COMMENT>(....................................................................) 

<HEAD2>(#ELSE\head_ssi_else)

<P> The <EMPHASIS>(else) directive allows blocks of HTML markup and
SSI directives to be conditionally processed, see
<REFERENCE>(head_ssi_flow_control).  It is the default block after an
<QUOTE>(#if), <QUOTE>(#orif) or <QUOTE>(#elif).

<CODE_EXAMPLE>
  <LITERAL>(<)!--#else --<LITERAL>(>)
<ENDCODE_EXAMPLE>

<COMMENT>(....................................................................) 

<HEAD2>(#ENDIF\head_ssi_endif)

<P> The <EMPHASIS>(#endif) directive marks the end of a block of document text
being conditionally processed, see <REFERENCE>(head_ssi_flow_control).

<CODE_EXAMPLE>
  <LITERAL>(<)!--#endif --<LITERAL>(>)
<ENDCODE_EXAMPLE>

<COMMENT>(....................................................................)

<HEAD2>(#EXEC\head_ssi_exec)

<P> The <EMPHASIS>(#exec) directive executes a DCL command and incorporates the 
output into the processed document.  It is the VMS equivalent of the 
<EMPHASIS>(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 <EMPHASIS>(cmd) tag, the 
<EMPHASIS>(cgi) tag, allowing execution of CGI scripts, is not supported. 

<CODE_EXAMPLE>
  <LITERAL>(<!--#exec cmd="show device/full tape1:" -->)
<ENDCODE_EXAMPLE>

<P> The <EMPHASIS>(exec) directive is for <EMPHASIS>(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. 

<COMMENT>(....................................................................) 

<HEAD2>(#EXIT\head_ssi_exit)

<P> The <EMPHASIS>(#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 <EMPHASIS>(#stop) directive
also is available, it stops processing of the entire virtual document.

<CODE_EXAMPLE>
  <LITERAL>(<)!--#exit --<LITERAL>(>)
<ENDCODE_EXAMPLE>

<COMMENT>(....................................................................) 

<HEAD2>(#FCREATED\head_ssi_fcreated)

<P> The <EMPHASIS>(#fcreated) directive incorporates the creation date/time of 
a specified file/document into the processed document. 

<LIST>(UNNUMBERED)

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(FILE\BOLD)
<P> Document specified using a VMS file path. 

<CODE_EXAMPLE>
  <LITERAL>(<)!--#fcreated file="<EMPHASIS>(file-name)" [fmt="<EMPHASIS>(time-format)"] --<LITERAL>(>)
<ENDCODE_EXAMPLE>

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(VIRTUAL\BOLD)
<P> Document specified using URL-style syntax. 

<CODE_EXAMPLE>
  <LITERAL>(<)!--#fcreated virtual="<EMPHASIS>(path)" [fmt="<EMPHASIS>(time-format)"] --<LITERAL>(>)
<ENDCODE_EXAMPLE>

<ENDLIST>

<COMMENT>(....................................................................) 

<HEAD2>(#FLASTMOD\head_ssi_flastmod)

<P> The <EMPHASIS>(#flastmod) directive incorporates the last modification 
date/time of a specified file/document into the processed document. 

<LIST>(UNNUMBERED)

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(FILE\BOLD)
<P> Document specified using a VMS file path. 

<CODE_EXAMPLE>
  <LITERAL>(<)!--#flastmod file="<EMPHASIS>(file-name)" [fmt="<EMPHASIS>(time-format)"] --<LITERAL>(>)
<ENDCODE_EXAMPLE>

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(VIRTUAL\BOLD)
<P> Document specified using URL-style syntax. 

<CODE_EXAMPLE>
  <LITERAL>(<)!--#flastmod virtual="<EMPHASIS>(path)" [fmt="<EMPHASIS>(time-format)"] --<LITERAL>(>)
<ENDCODE_EXAMPLE>

<ENDLIST>

<COMMENT>(....................................................................) 

<HEAD2>(#FSIZE\head_ssi_fsize)

<P> The <EMPHASIS>(#fsize) directive incorporates the size, in bytes, kbytes or 
Mbytes, of a specified file/document into the processed document. 

<LIST>(UNNUMBERED)

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(FILE\BOLD)
<P> Document specified using a VMS file path.

<CODE_EXAMPLE>
  <LITERAL>(<)!--#fsize file="<EMPHASIS>(file-name)" [fmt="<EMPHASIS>(size-format)"] --<LITERAL>(>)
<ENDCODE_EXAMPLE>

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(VIRTUAL\BOLD)
<P> Document specified using URL-style syntax.

<CODE_EXAMPLE>
  <LITERAL>(<)!--#fsize virtual="<EMPHASIS>(path)" [fmt="<EMPHASIS>(size-format)"] --<LITERAL>(>)
<ENDCODE_EXAMPLE>

<ENDLIST>

<COMMENT>(....................................................................) 

<HEAD2>(#IF\head_ssi_if)

<P> The <EMPHASIS>(#if) directive allows blocks of HTML markup and SSI
directives to be conditionally processed, see
<REFERENCE>(head_ssi_flow_control).

<LIST>(UNNUMBERED)

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(VAR=\BOLD)
<P> Variable the decision will be based upon.

<CODE_EXAMPLE>
  <LITERAL>(<)!--#if var="[<EMPHASIS>({variable})|<EMPHASIS>(literal)]" --<LITERAL>(>)
<ENDCODE_EXAMPLE>

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(EQS=\BOLD)
<P> Is the string the same as in the variable?

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(EQ=\BOLD)
<P> If the variable is a number is it the same as this?

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(GT=\BOLD)
<P> If the variable is a number is it greater than this?

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(LT=\BOLD)
<P> If the variable is a number is it less than this?

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(SRCH=\BOLD)
<P> Search the variable for this string.  May contain the <QUOTE>(*) wildcard,
matching one or more characters, and the <QUOTE>(%), matching any single
character.

<ENDLIST>

<P> As in the following examples:

<CODE_EXAMPLE>
  <LITERAL>(<)!--#if value={DOCUMENT_URI} eqs="/ht_root/doc/env/xssi.shtml" --<LITERAL>(>)
  <LITERAL>(<)!--#if value={COUNT} lt=10 --<LITERAL>(>)
  <LITERAL>(<)!--#if value="This is a test!" eqs={STRING} --<LITERAL>(>)
  <LITERAL>(<)!--#if value={PATH_INFO} srch="*/env/*" --<LITERAL>(>)
<ENDCODE_EXAMPLE>

<COMMENT>(....................................................................) 

<HEAD2>(#INCLUDE\head_ssi_include)

<P> The <EMPHASIS>(#include) directive incorporates the contents of a specified 
file/document into the processed document.

<LIST>(UNNUMBERED)

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(FILE\BOLD)
<P> Include the contents of the document specified using a VMS file
specification.

<CODE_EXAMPLE>
  <LITERAL>(<)!--#include file="<EMPHASIS>(file-name)" --<LITERAL>(>)
<ENDCODE_EXAMPLE>

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(VIRTUAL\BOLD)
<P> Include the contents of the document specified using URL-style syntax.

<CODE_EXAMPLE>
  <LITERAL>(<)!--#include virtual="<EMPHASIS>(path)" --<LITERAL>(>)
<ENDCODE_EXAMPLE>

<ENDLIST>

<P> The contents of the specified file are included differently depending on
the MIME content-type of the file.  Files of <EMPHASIS>(text/html) content-type
(HTML documents) are included directly, and any HTML tags within them
contribute to the markup of the document.  Files of <EMPHASIS>(text/plain)
content-type (plain-text documents) are encapsulated in
<QUOTE>(<LITERAL>(<PRE></PRE>)) tags and have all HTML-forbidden
characters (e.g. <QUOTE>(<LITERAL>(<)), <QUOTE>(<LITERAL>(&))) escaped before
inclusion in the processed document.  An HTML file can be forced to be included
as plain-text by using the following syntax:

<CODE_EXAMPLE>
  <LITERAL>(<)!--#include virtual="example.html" type="text/plain" --<LITERAL>(>)
<ENDCODE_EXAMPLE>

<P> To <QUOTE>(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.

<CODE_EXAMPLE>
  <LITERAL>(<)!--#include virtual="example.html" content="text/plain" --<LITERAL>(>)
  <LITERAL>(<)!--#include virtual="example.html" content="text/html" --<LITERAL>(>)
<ENDCODE_EXAMPLE>

<P> 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.

<COMMENT>(....................................................................) 

<HEAD2>(#MODIFIED\head_ssi_modified)

<P> The <EMPHASIS>(#modified) directive allows a document author to control the
<QUOTE>(Last-Modified:)/<QUOTE>(If-Modified-Since:)/<QUOTE>(304 Not modified)
behaviour of an SSI document.  See <REFERENCE>(head_ssi_virtual_doc).

<LIST>(UNNUMBERED)

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(<EMPHASIS>(no tag)\BOLD)
<P> Get the last-modified date/time of the current document.

<CODE_EXAMPLE>
  <LITERAL>(<)!--#modified --<LITERAL>(>)
<ENDCODE_EXAMPLE>

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(FILE\BOLD)
<P> Get the last-modified date/time of the document specified using VMS file
specification.

<CODE_EXAMPLE>
  <LITERAL>(<)!--#modified file="<EMPHASIS>(file-name)" --<LITERAL>(>)
<ENDCODE_EXAMPLE>

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(VIRTUAL\BOLD)
<P> Get the last-modified date/time of the document specified using URL-style
syntax.

<CODE_EXAMPLE>
  <LITERAL>(<)!--#modified virtual="<EMPHASIS>(path)" --<LITERAL>(>)
<ENDCODE_EXAMPLE>

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(IF-MODIFIED-SINCE\BOLD)
<P> Compares any <QUOTE>(If-Modified-Since:) request header timestamp to the
revision date time obtained using <EMPHASIS>(file) or <EMPHASIS>(virtual) (most
recent if multiple).  If the document timestamp is more recent (has been
modified) an appropriate <QUOTE>(Last-Modified) response header field is
generated and added to the response, and document processing continues.  If it
has not been modified a <QUOTE>(304) response header is return (document not
modified) and document processing stops.

<CODE_EXAMPLE>
  <LITERAL>(<)!--#modified if-modified-since --<LITERAL>(>)
<ENDCODE_EXAMPLE>

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(LAST-MODIFIED\BOLD)
<P> Adds a <QUOTE>(Last-Modified:) response header field using a timestamp
retrieved using <EMPHASIS>(file) or <EMPHASIS>(virtual) (note: unnecessary if
the <EMPHASIS>(if-modified-since) tag is used). 

<CODE_EXAMPLE>
  <LITERAL>(<)!--#modified last-modified --<LITERAL>(>)
<ENDCODE_EXAMPLE>

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(EXPIRES\BOLD)
<P> Adds a <QUOTE>(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.

<CODE_EXAMPLE>
  <LITERAL>(<)!--#modified expires="Fri, 13 Jan 1978 14:00:00 GMT" --<LITERAL>(>)
<ENDCODE_EXAMPLE>

<ENDLIST>

<COMMENT>(....................................................................) 

<HEAD2>(#ORIF\head_ssi_orif)

<P> The <EMPHASIS>(#orif) directive (or-if) allows blocks of HTML markup and
SSI directives to be conditionally processed, see
<REFERENCE>(head_ssi_flow_control) and <REFERENCE>(head_ssi_if).  In the
absence of any real expression parser this directive allows a block to be
processed if one of multiple conditions are met.

<CODE_EXAMPLE>
  <LITERAL>(<)!--#orif var="[<EMPHASIS>({variable})|<EMPHASIS>(literal)" --<LITERAL>(>)
<ENDCODE_EXAMPLE>

<COMMENT>(....................................................................) 

<HEAD2>(#PRINTENV\head_ssi_printenv)

<P> The <EMPHASIS>(#printenv) directive prints a plain-text list of all
SSI-specific, then CGI, then document-assigned variables (see
<REFERENCE>(head_ssi_variables)). This directive is intended for use when
debugging flow-controlled SSI documents.

<CODE_EXAMPLE>
  <LITERAL>(<)!--#printenv --<LITERAL>(>)
<ENDCODE_EXAMPLE>

<COMMENT>(HTML=
<P> The following link uses the example SSI document
<A HREF="xssi.shtml?httpd=ssi&text=plain">HT_ROOT:[DOC.ENV]XSSI.SHTML</A>
to demonstrate this.

<PRE>
  <A HREF="xssi.shtml?httpd=ssi&printenv=yes&test1=one&test2=two&test3=three">xssi.shtml?httpd=ssi&printenv=yes&test1=one&test2=two&test3=three</A>
</PRE>
)

<COMMENT>(HTML/OFF)
<P> The following link uses the example SSI document,
HT_ROOT:[DOC.ENV]XSSI.SHTML, to demonstrate this.

<P><BOX>(online demonstration)
<COMMENT>(HTML/ON)

<COMMENT>(....................................................................) 

<HEAD2>(#SET\head_ssi_set)

<P> The <EMPHASIS>(#set) directive allows a user variable to be assigned or
modified, see <REFERENCE>(head_ssi_variables).

<CODE_EXAMPLE>
  <LITERAL>(<)!--#set var="<EMPHASIS>(variable-name)" value="<EMPHASIS>(whatever)" --<LITERAL>(>)
<ENDCODE_EXAMPLE>

<P> 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.

<COMMENT>(....................................................................) 

<HEAD2>(#SSI\head_ssi_ssi)

<P> The <EMPHASIS>(#ssi) directive allows multiple SSI directives to be used
without the requirement to enclose them in the normal HTML comment tags (i.e.
<LITERAL>(<!-- -->)). 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 <QUOTE>(#ssi) tag, although of course document output can be
generated using the <QUOTE>(#echo) tag.

<CODE_EXAMPLE>
  <LITERAL>(<!--#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
  <LITERAL>(-->)
<ENDCODE_EXAMPLE>

<COMMENT>(HTML=
<P> The example SSI document
<A HREF="xssi.shtml?httpd=ssi&text=plain">HT_ROOT:[DOC.ENV]XSSI.SHTML</A>
illustrates this concept.
)

<COMMENT>(HTML/OFF)
<P> The example SSI document, HT_ROOT:[DOC.ENV]XSSI.SHTML, illustrates this
concept.
<COMMENT>(HTML/ON)

<COMMENT>(....................................................................) 

<HEAD2>(#STOP\head_ssi_stop)

<P> The <EMPHASIS>(#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 <EMPHASIS>(#exit)
directive also is available, it stops processing of the current file (for
nested #includes, etc.). 

<CODE_EXAMPLE>
  <LITERAL>(<)!--#stop --<LITERAL>(>)
<ENDCODE_EXAMPLE>

<COMMENT>(....................................................................) 

<HEAD1>(Variables\head_ssi_variables)

<P> The SSI processor maintains information about the server, date and time,
request path, request parameters, etc., accessable via <EMPHASIS>(variable
name). Although these <EMPHASIS>(server variables) cannot be modified by the
document the processor also allows the author to create and assign new
<EMPHASIS>(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
<EMPHASIS>(#included), and any included by those, etc.

<P> Local variables:

<LIST>(UNNUMBERED)
<LE>DOCUMENT_DEPTH, the current nesting level for #included SSI files
<LE>PARENT_FILE_NAME, if an #included SSI file the name of the including file
<LE>THIS_FILE_NAME, the name of the SSI file currently being processed
<ENDLIST>

<P> One other special-purpose variable, THE_FILE_NAME, see
<REFERENCE>(head_ssi_var_ht_file_name).

<P> Server assigned variables comprise some SSI-specific as well as the same
CGI variables available to CGI scripts.

<COMMENT>(HTML=
These may be found listed in the &quot;CGI Scripting&quot; chapter of the
<A HREF="../htd/">Technical Overview</A>.

<P> The following link provides a list of the
<A HREF="xssi.shtml?httpd=ssi&printenv=yes">SSI and CGI variables</A>
available to SSI documents.
)

<COMMENT>(HTML/OFF)
<P> These may be found listed in the <EMPHASIS>(CGI Scripting) chapter of the
<EMPHASIS>(Technical Overview).

<P><BOX>(online demonstration)
<COMMENT>(HTML/ON)

<P> Whenever a directive uses information from a tag (see
<REFERENCE>(head_preprocessing_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

<CODE_EXAMPLE>
  <LITERAL>(<)!--#include virtual={FILENAME} --<LITERAL>(>)
<ENDCODE_EXAMPLE>

would include the file named by the contents of a variable named
<QUOTE>(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

<CODE_EXAMPLE>
  <LITERAL>(<)!--#echo var="Hello {REMOTE_HOST}, time here is {LOCAL_TIME}" --<LITERAL>(>)
<ENDCODE_EXAMPLE>

<P> Variables are considered numeric when they begin with a digit.  Those
beginning with an alphabetic are considered to have a numeric value of zero.

<P> Variables are considered to be boolean <EMPHASIS>(false) if empty and
<EMPHASIS>(true) when not empty.

<HEAD>(Substrings\head_ssi_var_substrings)

<P> It is also possible to extract substrings from variables using the
following syntax,

<CODE_EXAMPLE>
  {<EMPHASIS>(variable-name),<EMPHASIS>(start-index),<EMPHASIS>(count)}
<ENDCODE_EXAMPLE>

<P> 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.

<P> To illustrate,

<CODE_EXAMPLE><LITERAL>
  <!--#set var=EXAMPLE value="This is an example!" -->
  <!--#echo "{EXAMPLE,2}at was {EXAMPLE,8,999}" -->
<ENDLITERAL><ENDCODE_EXAMPLE>

<P> would output

<CODE_EXAMPLE>
  That was an example!
<ENDCODE_EXAMPLE>

<HEAD>(Other <QUOTE>(Functions)\head_ssi_var_functions)

<LIST>(UNNUMBERED)

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(LENGTH - \BOLD) This <QUOTE>(function) returns the length of
the parameter string (or substring).

<CODE_EXAMPLE>
  {<EMPHASIS>(variable-name)[,<EMPHASIS>(start-index)],<EMPHASIS>(count)]],length}
<ENDCODE_EXAMPLE>

<P> For example

<CODE_EXAMPLE><LITERAL>
  <!--#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!" -->
<ENDLITERAL><ENDCODE_EXAMPLE>

<P> would output

<CODE_EXAMPLE>
  "This is an example!" is 19 characters long.
  "is" is 2 characters long!
<ENDCODE_EXAMPLE>

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(EXISTS - \BOLD) This <QUOTE>(function) returns <EMPHASIS>(true)
if the variable exists and <EMPHASIS>(false) if it does not.  This is useful
as accessing a non-existant variable will result in an SSI error message with
document processing ceasing!

<CODE_EXAMPLE>
  {<EMPHASIS>(variable-name),exists}
<ENDCODE_EXAMPLE>

<P> For example

<CODE_EXAMPLE><LITERAL>
  <!--##set var=BOGUS_VARIABLE value="irrelevant" -->
  <!--#if {BOGUS_VARIABLE,exists} -->
  &quot;BOGUS_VARIABLE&quot; exists!
  <!--#else -->
  &quot;BOGUS_VARIABLE&quot; does NOT exist!
  <!--#endif -->
<ENDLITERAL><ENDCODE_EXAMPLE>

<ENDLIST>

<HEAD>(Example\head_ssi_var_example)

<COMMENT>(HTML=
<P> The example SSI document
<A HREF="xssi.shtml?httpd=ssi&text=plain">HT_ROOT:[DOC.ENV]XSSI.SHTML</A>
illustrates these concepts.
)
<COMMENT>(HTML/OFF)
<P> The example SSI document, HT_ROOT:[DOC.ENV]XSSI.SHTML, illustrates these
concepts.
<COMMENT>(HTML/ON)

<COMMENT>(....................................................................) 

<HEAD1>(Flow Control\head_ssi_flow_control)

<P> 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.

<P> 
<LIST>(UNNUMBERED)

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(#if - \BOLD)
Marks the start of a conditionally processed block.  If evaluated true the
block is processed.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(#orif - \BOLD)
Allows a document block to be
processed if one of multiple conditions are met. Must be used immediately
following a <QUOTE>(#if) or <QUOTE>(elif). (This is the only really
WASD-idiosyncratic element)

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(#elif - \BOLD)
Allows a series of conditionals to be tested each with it's own document block
available for processing.  Allows a type of case statement to be constructed.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(#else - \BOLD)
Provides a default document block following unsuccessful <QUOTE>(#if),
<QUOTE>(orif) and <QUOTE>(elif) testing and consequent non-processed blocks.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(#endif - \BOLD)
Terminates a conditional block.

<ENDLIST>

<P> The <QUOTE>(#if), <QUOTE>(#orif) and <QUOTE>(#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.

<P> 
<LIST>(UNNUMBERED)

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(eqs - \BOLD)
If the supplied string is the same as the variable string.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(srch - \BOLD)
If the variable string matches the supplied search string. The search string
may contain the <QUOTE>(*), matching any zero or more characters, and
<QUOTE>(%), matching any one character.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(eq - \BOLD)
If the numeric value of the variable is the same as that of the supplied
number.  For a numeric value test to be legitimate both values must begin with
a digit.  Those beginning with an alphabetic are considered zero.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(lt - \BOLD)
If the numeric value of the variable is less than that of the supplied number.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(gt - \BOLD)
If the numeric value of the variable is greater than that of the supplied
number.

<ENDLIST>

<P> 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
<EMPHASIS>(false) result, the second <EMPHASIS>(true).

<CODE_EXAMPLE><LITERAL>
  <!--#if value="test" !eqs="test" -->
  <!--#if value=20 !lt=10 -->
<ENDLITERAL><ENDCODE_EXAMPLE>

<P> The following is a simple example illustration of variable setting, use
of variable substrings, and conditional processing of document blocks.

<CODE_EXAMPLE><LITERAL>
  <!--##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>
<ENDLITERAL><ENDCODE_EXAMPLE>

<COMMENT>(HTML=
<P> The example SSI document
<A HREF="xssi.shtml?httpd=ssi&text=plain">HT_ROOT:[DOC.ENV]XSSI.SHTML</A>
further illustrates these concepts.
)

<COMMENT>(HTML/OFF)
<P> The example SSI document, HT_ROOT:[DOC.ENV]XSSI.SHTML, further illustrates
these concepts.
<COMMENT>(HTML/ON)

<COMMENT>(....................................................................) 

<HEAD1>(Query Strings\head_ssi_query_strings)

<P> 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 <QUOTE>(?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:

<CODE_EXAMPLE>
  ?httpd=ssi&printenv=no
  ?httpd=ssi&printenv=yes
  ?httpd=ssi&trace=yes&test2=one&test2=two&test3=three
<ENDCODE_EXAMPLE>

<COMMENT>(HTML=
<P> The following link uses the example SSI document
<A HREF="xssi.shtml?httpd=ssi&text=plain">HT_ROOT:[DOC.ENV]XSSI.SHTML</A>
to demonstrate this. Look for the <QUOTE>(FORM_TEST1=one), etc.

<PRE>
  <A HREF="xssi.shtml?httpd=ssi&printenv=yes&test1=one&test2=two&test3=three">xssi.shtml?httpd=ssi&printenv=yes&test1=one&test2=two&test3=three</A>
</PRE>
)

<COMMENT>(HTML/OFF)
<P> The following link uses the example SSI document,
HT_ROOT:[DOC.ENV]XSSI.SHTML, to demonstrate this. Look for the
<QUOTE>(FORM_TEST1=one), etc.

<P><BOX>(online demonstration)
<COMMENT>(HTML/ON)

<COMMENT>(--------------------------------------------------------------------)

<HEAD1>(File and Virtual Specifications\head_ssi_file_virtual)

<P> Documents may be specified using either the <QUOTE>(FILE) or
<QUOTE>(VIRTUAL) tags.

<P> The <QUOTE>(FILE) tag expects an absolute VMS file
specification.

<P> The <QUOTE>(VIRTUAL) tag expects an URL-style path to a
document.  This can be an absolute or relative path.  See
<REFERENCE>(head_document_specification) for further details.

<HEAD2>(THE_FILE_NAME\head_ssi_var_ht_file_name)

<P> 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 <QUOTE>(?) 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.

<P> 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.

<LIST>(UNNUMBERED)

<COMMENT>(HTML=<P>)

<LE> For #included files, the 'fmt="?"' just suppresses an error report, if the
file exists then it is included.

<COMMENT>(HTML=<P>)

<LE> For #modified file specifications use 'fmt="?"' to suppress error
reporting on evaluation of files that may exist but are not mandatory.

<COMMENT>(HTML=<P>)

<LE> For file statistic directives (e.g. #flastmod, #fcreated, #fsize) the
'fmt="?"' tag completely suppresses all output as well as error reporting. 
This can be used to check for the existance of a file.  For example if the file
TEST.TXT exists in the following example the variable THE_FILE_NAME would
contain the full file name, if it does not exist it would be empty, and the
code example would behave accordingly.

<CODE_EXAMPLE><LITERAL>
  <!--#fcreated virtual="TEST.TXT" fmt="?" -->
  <!--#if var={THE_FILE_NAME} eqs="" -->
  File does not exist!
  <!--#else -->
  File exists!
  <!--#endif -->
<ENDLITERAL><ENDCODE_EXAMPLE>

<ENDLIST>

<COMMENT>(--------------------------------------------------------------------)

<HEAD1>(Time Format\head_ssi_time_format)

<P> <EMPHASIS>(Note: \BOLD) Time formatting only applies if the HTTPd server 
has been compiled using DEC C. 

<P> 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 <EMPHASIS>(strftime()).

<P> The format specifier follows a similar syntax to the C standard library
<EMPHASIS>(printf()) family of functions, where conversion specifiers are
introduced by percentage symbols.  Here are some example uses:

<CODE_EXAMPLE>
  The date is <LITERAL>(<)!--#echo date_local fmt="%d/%m/%y" --<LITERAL>(>).
  The time is <LITERAL>(<)!--#echo date_local fmt="%r" --<LITERAL>(>).
  The day-of-the-week is <LITERAL>(<)!--#echo date_local fmt="%A" --<LITERAL>(>).
<ENDCODE_EXAMPLE>

<P> A problem with any supplied time formatting specification will be reported.

<P> The following table provides the general conversion specifiers.  For
futher information on the formatting process refer to a C programming library
document on the <EMPHASIS>(strftime()) function.

<P>
<TABLE>
<TABLE_SETUP>(2\8)
<TABLE_HEADS>(Specifier\Replaced by)
<COMMENT>(HTML=<TR></TR>)
<TABLE_ROW>(a\The locale's abbreviated weekday name)
<TABLE_ROW>(A\The locale's full weekday name)
<TABLE_ROW>(b\The locale's abbreviated month name)
<TABLE_ROW>(B\The locale's full month name)
<TABLE_ROW>(c\The locale's appropriate date and time representation)
<TABLE_ROW>(C\The century number (the year divided by 100 and truncated
to an integer) as a decimal number (00 - 99))
<TABLE_ROW>(d\The day of the month as a decimal number (01 - 31))
<TABLE_ROW>(D\Same as %m/%d/%y)
<TABLE_ROW>(e\The day of the month as a decimal number (1 - 31) in a
2 digit field with the leading space character fill)
<TABLE_ROW>(Ec\The locale's alternative date and time representation)
<TABLE_ROW>(EC\The name of the base year (period) in the locale's
alternative representation)
<TABLE_ROW>(Ex\The locale's alternative date representation)
<TABLE_ROW>(EX\The locale's alternative time representation)
<TABLE_ROW>(Ey\The offset from the base year (%EC) in the locale's
alternative representation)
<TABLE_ROW>(EY\The locale's full alternative year representation)
<TABLE_ROW>(h\Same as %b)
<TABLE_ROW>(H\The hour (24-hour clock) as a decimal number (00 - 23))
<TABLE_ROW>(I\The hour (12-hour clock) as a decimal number (01 - 12))
<TABLE_ROW>(j\The day of the year as a decimal number (001 - 366))
<TABLE_ROW>(m\The month as a decimal number (01 - 12))
<TABLE_ROW>(M\The minute as a decimal number (00 - 59))
<TABLE_ROW>(n\The newline character)
<TABLE_ROW>(Od\The day of the month using the locale's alternative
numeric symbols)
<TABLE_ROW>(Oe\The date of the month using the locale's alternative
numeric symbols)
<TABLE_ROW>(OH\The hour (24-hour clock) using the locale's alternative
numeric symbols)
<TABLE_ROW>(OI\The hour (12-hour clock) using the locale's alternative
numeric symbols)
<TABLE_ROW>(Om\The month using the locale's alternative numeric symbols)
<TABLE_ROW>(OM\The minutes using the locale's alternative numeric symbols)
<TABLE_ROW>(OS\The seconds using the locale's alternative numeric symbols)
<TABLE_ROW>(Ou\The weekday as a number in the locale's alternative
representation (Monday=1))
<TABLE_ROW>(OU\The week number of the year (Sunday as the first day of the
week) using the locale's alternative numeric symbols)
<TABLE_ROW>(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.)
<TABLE_ROW>(Ow\The weekday as a number (Sunday=0) using the locale's
alternative numeric symbols)
<TABLE_ROW>(OW\The week number of the year (Monday as the first day of
the week) using the locale's alternative numeric symbols)
<TABLE_ROW>(Oy\The year without the century using the locale's alternative
numeric symbols)
<TABLE_ROW>(p\The locale's equivalent of the AM/PM designations associated
with a 12-hour clock)
<TABLE_ROW>(r\The time in AM/PM notation)
<TABLE_ROW>(R\The time in 24-hour notation (%H:%M))
<TABLE_ROW>(S\The second as a decimal number (00 - 61))
<TABLE_ROW>(t\The tab character)
<TABLE_ROW>(T\The time (%H:%M:%S))
<TABLE_ROW>(u\The weekday as a decimal number between 1 and 7 (Monday=1))
<TABLE_ROW>(U\The week number of the year (the first Sunday as the first
day of week 1) as a decimal number (00 - 53))
<TABLE_ROW>(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.)
<TABLE_ROW>(w\The weekday as a decimal number (0 [Sunday] - 6))
<TABLE_ROW>(W\The week number of the year (the first Monday as the first
day of week 1) as a decimal number (00 - 53))
<TABLE_ROW>(x\The locale's appropriate date representation)
<TABLE_ROW>(X\The locale's appropriate time representation)
<TABLE_ROW>(y\The year without century as a decimal number (00 - 99))
<TABLE_ROW>(Y\The year with century as a decimal number)
<TABLE_ROW>(Z\Timezone name or abbreviation. If timezone information is
not available, no character is output.)
<TABLE_ROW>(%\%)
<ENDTABLE>

<HEAD1>(Scrunched Documents\head_ssi_scrunched_doc)

<P> Now that I have your attention!

<P> A <EMPHASIS>(scrunched) SSI file is a variable length record file, where
each record either comprises a single SSI directive, with the
<QUOTE>(<LITERAL>(<)!--#) beginning on the record boundary, or a record of
other text to be output (i.e. not beginning with <QUOTE>(<LITERAL>(<)!--#)).

<P> Why do this?  Well, if all SSI directives begin on a record boundary you
only have to check the first five characters to establish
whether it should be interpreted or directly output!  This <EMPHASIS>(saves
checking every character of every record\BOLD) for the opening
<QUOTE>(<LITERAL>(<)) and the following <QUOTE>(!--#). This can be a
not inconsiderable saving in processing overhead if a largish file only
contains a few SSI directives (like many).  This will not only reduce latency
but significantly reduce processing on more heavily loaded systems.  Tests
indicate anything from 25% to 50% reduction in request duration, with CPU time
consumed showing a similar reduction (depending on the proportion of plain-text
and SSI directives in the file, the less SSI the greater the improvement).

<P> The HTTPd SSI module detects a <QUOTE>(<LITERAL>(<!--#SCRUNCH ... -->))
directive (which should be at the start of the first record of the file.  If
this exists it assumes the file has been legitimately scrunched by the utility
and processes the records in an appropriate manner.  The utility also checks
for this string to ascertain whether it's dealing with a previously scrunched
file or not.  The HTTPd processes both formats in the same basic manner and so
files may scrunched and unscrunched at anytime without affecting availability
(except perhaps for a brief period of locking).

<P> <EMPHASIS>(What needs to be done?\BOLD)  When an SSI file has been composed
ready to be put into production the SCRUNCH utility is applied to it.  This is
done at the command line.  Ensure the utility exists as a foreign command (as
an <EMPHASIS>(unscruncher) as well!)

<CODE_EXAMPLE>
  $ SCRUNCH == "$HT_EXE:SCRUNCH"
  $ UNSCRUNCH == "$HT_EXE:SCRUNCH/UNSCRUNCH"
<ENDCODE_EXAMPLE>

<P> The first example shows a single file being processed.  SCRUNCH will also
accept full RMS wildcarding to process multiple files.

<CODE_EXAMPLE>
  $ SCRUNCH WEB:[000000]HOME.SHTML
  $ SCRUNCH WEB:[SUPPORT]*.SHTML
<ENDCODE_EXAMPLE>

<P> <EMPHASIS>(Files that have been scrunched are basically unsuitable for
editing\bold) (only due to the often inappropriately sized records). 
Previously scrunched files may be returned to something (often exactly)
resembling their original condition using the /UNSCRUNCH qualifier.

<CODE_EXAMPLE>
  $ UNSCRUNCH WEB:[000000]HOME.SHTML
  $ UNSCRUNCH WEB:[SUPPORT]*.SHTML
<ENDCODE_EXAMPLE>

<HEAD1>(OSU Compatibility\head_ssi_osu)

<P> 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 <QUOTE>(.HTMLX) files
ensure the following WASD configuration is in place.

<P> In HTTPD$CONFIG file:

<CODE_EXAMPLE>
  [AddType]
  .HTMLX  text/x-shtml  -  OSU SSI HTML
<ENDCODE_EXAMPLE>

<P> Note that the content description must contain the string "OSU" to activate
some compliancy behaviours.  

<P> In HTTPD$MAP file:

<CODE_EXAMPLE>
  redirect /*.*.htmlx /*.htmlx?httpd=ssi&__part=*
<ENDCODE_EXAMPLE>

<P> This provides a mechanism for the OSU part-document facility.
(Yes, the <quote>(__part) has two leading underscores!)

<HEAD>(OSU Directives\head_ssi_osu_directives)

<P> 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.

<P>
<TABLE>
<TABLE_SETUP>(2\30)
<TABLE_HEADS>(Directive\Description)
<COMMENT>(HTML=<TR></TR>)
<TABLE_ROW>(<EMPHASIS>(#begin <EMPHASIS>(label) [<EMPHASIS>(label)]\BOLD)\
delimit a part-document (see <REFERENCE>(head_ssi_osu_part)))
<TABLE_ROW>(<EMPHASIS>(#config verify=1 \BOLD)\
enable commented-tag trace output)
<TABLE_ROW>(<EMPHASIS>(#echo accesses\BOLD)\document access count)
<TABLE_ROW>(<EMPHASIS>(#echo accesses_ordinal\BOLD)\document access count)
<TABLE_ROW>(<EMPHASIS>(#echo getenv=""\BOLD)\output logical or symbol)
<TABLE_ROW>(<EMPHASIS>(#echo hw_name\BOLD)\system hardware name)
<TABLE_ROW>(<EMPHASIS>(#echo server_name\BOLD)\HTTPd server host name)
<TABLE_ROW>(<EMPHASIS>(#echo server_version\BOLD)\HTTPd software version)
<TABLE_ROW>(<EMPHASIS>(#echo vms_version\BOLD)\HTTPd system version of VMS)
<TABLE_ROW>(<EMPHASIS>(#end <EMPHASIS>(label) [<EMPHASIS>(label)]\BOLD)\
delimit a part-document (see <REFERENCE>(head_ssi_osu_part)))
<TABLE_ROW>(<EMPHASIS>(#include <LITERAL>([file|virtual])="" part="<EMPHASIS>(label)"\BOLD)\
include only part of a virtual document)
<ENDTABLE>

<P> 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).

<COMMENT>(....................................................................)

<COMMENT>(HTML=
<BLOCKQUOTE>
<A HREF="/ht_root/src/osu/preproc.htmlx">/ht_root/src/osu/preproc.htmlx</A>
</BLOCKQUOTE>
)

<COMMENT>(HTML/OFF)
<P><BOX>(online demonstration)
<COMMENT>(HTML/ON) 

<COMMENT>(....................................................................)

<P> How do we know WASD is processing it?  Look for the
<EMPHASIS>(#echo var=<QUOTE>(GETENV=SYS$REM_ID)) towards the end of the
document.  It should indicate <QUOTE>([VARIABLE_DOES_NOT_EXIST!]) because it's
attempting to output a DECnet-related logical name!

<HEAD>(OSU <QUOTE>(Part)s\head_ssi_osu_part)

<P> The OSU processor allows for delimited subsections of an
<EMPHASIS>(#include)d 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 <QUOTE>(.HTMLX) documents and if otherwise used may
interact unexpectedly with WASD SSI flow-control.

<COMMENT>(--------------------------------------------------------------------)

<CHAPTER>(Clickable Image Support\chapter_ismap)

<P> Clickable image support is provided as an integral part of HTTPd 
functionality (i.e. it is does not require script execution), and so can be 
quite efficient.  It will process both NCSA and CERN configuration formats (in 
the same file if necessary, although for clarity that should be avoided). 

<HEAD>(<EMPHASIS>(Digression) <HELLIPSIS> How It Works\head_ismap_how_it_works)

<P> When the image specified in the anchor is clicked upon the browser sends a 
mapping configuration file URL, specified in the HTML anchor, along with the 
pixel coordinate of the click, as a query string, to the HTTPd server.  The 
server interprets region specifications in the configuration file to determine 
which region corresponds to the coordinates in the query string.  A matching 
specification's URL, or a default if none match, is then accessed by the 
server (if local), or sent back to, and then transparently reaccessed by the 
browser (redirected, if a different protocol or host). 

<HEAD>(Steps For Using a Clickable Image\head_image_steps)

<LIST>(NUMBERED)

<LE> create an <EMPHASIS>(image configuration file) (see 
<REFERENCE>(head_image_config_file)), mapping pixel coordinates of regions 
within the image to URLs 

<LE> specify an HTML anchor using an inline 
<QUOTE>(<LITERAL>(<IMG...>)) tag, the <QUOTE>(HREF=) 
specifies the path to the image configuration file

<LE> specify <QUOTE>(ISMAP) in the 
<QUOTE>(<LITERAL>(<IMG...>)) 
tag 

<P> For example:
<CODE_EXAMPLE>
  <LITERAL>(<A HREF="ismap_demo.ismap">
  <IMG SRC="ismap_demo.gif" ISMAP></A>)
<ENDCODE_EXAMPLE>

<ENDLIST>

<HEAD1>(Image Configuration File\head_image_config_file)

<P> Image configuration is done using a plain-text file containing region 
keywords specifying image pixel coordinates and associated URLs.  Clicking 
within these coordinates results in the corresponding URL being returned.  
Four keywords defining geometrically shaped series of coordinates are 
provided, along with a default keyword.  These can be supplied in either of 
two formats.  The NCSA format may be more commonly used. 

<LIST>(NUMBERED)

<LE> <EMPHASIS>(NCSA\BOLD)

<COMMENT>(HTML=<P>)

<LIST>(UNNUMBERED)

<LE> <EMPHASIS>(circle URL x1,y1 x2,y2\BOLD)
<LINE>
URL to be returned when the click is within a circle of centre-point
<EMPHASIS>(x1,y1) and a circumference specified by the edge-point 
<EMPHASIS>(x2,y2). 

<LE> <EMPHASIS>(rectangle URL x1,y1 x2,y2\BOLD)
<LINE>
URL to be returned when the click is within a rectangle having opposite 
corners <EMPHASIS>(x1,y1) and <EMPHASIS>(x2,y2). 

<LE> <EMPHASIS>(point URL x,y\BOLD)
<LINE>
With multiple points specified, the URL of the point closest to the click.

<LE> <EMPHASIS>(polygon URL x1,y1 x2,y2 x3,y3 [... xn,yn]\BOLD)
<LINE>
URL to be returned when the click is within an arbitrary polygon having 
adjacent verticies specified by the series of coordinates <EMPHASIS>((x1,y1)) 
through to <EMPHASIS>((xn,yn)).  If the polygon is not explcitly closed it is 
treated as if the first and last coordinates were connected.

<LE> <EMPHASIS>(default URL\BOLD)
<LINE>
URL to be returned when the click is not within any of the specified 
coordinates, and there has been no <EMPHASIS>(point) specified. 

<ENDLIST>

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(CERN\BOLD)

<COMMENT>(HTML=<P>)

<LIST>(UNNUMBERED)

<LE> <EMPHASIS>(circle (x,y) r URL\BOLD)
<LINE>
URL to be returned when the click is within a circle of radius <EMPHASIS>(r) 
at centre-point <EMPHASIS>((x,y)). 

<LE> <EMPHASIS>(rectangle (x1,y1)(x2,y2) URL\BOLD)
<LINE>
URL to be returned when the click is within a rectangle having opposite 
corners <EMPHASIS>((x1,y1)) and <EMPHASIS>((x2,y2)). 

<LE> <EMPHASIS>(point (x1,y1) URL\BOLD)
<LINE>
With multiple points specified, the URL of the point closest to the click 
(strictly speaking, this is NCSA only). 

<LE> <EMPHASIS>(polygon (x1,y1)(x2,y2)...(xn,yn) URL\BOLD)
<LINE>
URL to be returned when the click is within an arbitrary polygon having 
adjacent verticies specified by the series of coordinates <EMPHASIS>((x1,y1)) 
through to <EMPHASIS>((xn,yn)).  If the polygon is not explcitly closed it is 
treated as if the first and last coordinates were connected.

<LE> <EMPHASIS>(default URL\BOLD)
<LINE>
URL to be returned when the click is not within any of the specified 
coordinates, and there has been no <EMPHASIS>(point) specified. 

<ENDLIST>

<ENDLIST>

<P> For online examples of rule usage within configuration files see 
<REFERENCE>(head_ismap_examples) below.  Note that:

<LIST>(UNNUMBERED)

<LE> There must be only one region keyword on each line.

<LE> The region keywords are scanned from first towards last, the first one 
with coordinates encompassing the click having its URL returned.  Region 
coordinates within other regions should be defined first.

<LE> Either full URLs (<EMPHASIS>(protocol://host/path)) or partial URLs 
(<EMPHASIS>(/path)) may be specified against the keywords.  As an extension to 
NCSA and CERN capability, this image mapper will also accept relative URLs 
(<EMPHASIS>(path), <EMPHASIS>(../path), etc.). 

<LE> The image mapping utility may return textual error messages if the 
configuration keywords or parameters are incorrect. 

<LE> The keywords may be abbreviated to <EMPHASIS>(circ), <EMPHASIS>(rect), 
<EMPHASIS>(poly), <EMPHASIS>(poin) and <EMPHASIS>(def). 

<LE> Blank lines are ignored.

<LE> Commentary must be preceded by a <QUOTE>(#) or <QUOTE>(!) character.

<ENDLIST>

<NOTE>(hint <HELLIPSIS>)
To establish the region keywords and coordinates required for the 
configuration file it may be necessary to use a program such as 
<QUOTE>(XV) to display the image, then by using the mouse locate 
the required parts of the image, reading off and noting the coordinate pairs, 
and finally using these to compose the configuration file.
<ENDNOTE> 

<HEAD1>(Examples\head_ismap_examples)

<P> See example in the 

<COMMENT>(....................................................................)

<COMMENT>(HTML=
<A HREF="/ht_root/exercise/">HT_ROOT:[EXERCISE]</A> directory.
)

<COMMENT>(HTML/OFF)
HT_ROOT:[EXERCISE] directory.
<COMMENT>(HTML/ON)

<COMMENT>(....................................................................)

<COMMENT>(--------------------------------------------------------------------)

<CHAPTER>(Document Searching\chapter_searching)

<P> The <EMPHASIS>(query) and <EMPHASIS>(extract) scripts provide real-time 
searching of plain-text and HTML documents, and document retrieval.  The 
search is a simple-string search, not a GREP-style search.  It is designed to 
provide a useful mechanism for locating documents containing a keyword, not 
for document analysis.  It has the useful feature for plain-text documents of 
allowing the selective extraction of only the portion near the 
<EMPHASIS>(hit). 

<P> Only files with a plain-text or HTML MIME data type (see 
<REFERENCE>(chapter_document_access)) will be searched.  Others may be 
specified, or be selected from wildcard file specification, but they will not 
actually have their contents searched. 

<P> Directory specifications may include a wildcard elipsis (allowing a
directory tree to be traversed) and/or file name wildcards.  In other words,
anything acceptable as VMS file system syntax (except in URL-format of course).
See examples in <REFERENCE>(head_standard_search_form).

<HEAD1>(Plain-Text Search\head_plain_text_search)

<P> A search of a plain-text file is straight-forward.  Each line in the file 
is searched for the required string.  The first time it is encountered is 
considered a <EMPHASIS>(hit).  The line is not searched for any further 
occurances. 

<P> Searches of plain text files allow the subsequent selection of partial 
documents (i.e. the retrieval of only a number of lines around any actual 
hit).  This allows the user to selectively extract a portion of a document, 
avoiding the need to explcitly scan through to the section of interest. 

<HEAD1>(HTML Search\head_html_search)

<P> A search of an HTML file is a little more complex.  As might be expected, 
only text presented in the document text is searched, markup text is ignored.  
That is, all text not part of an HTML <EMPHASIS>(tag) construct is extracted 
and searched.  For example, out of the following HTML fragment 

<CODE_EXAMPLE><LITERAL>
  <!-- an example HTML document -->
  <P>
  The document entitled <A HREF="example.html">"Example Document"</A>
  provides only an <I>overview</I> of the full capabilities of HTML.
<ENDLITERAL>
<ENDCODE_EXAMPLE>

<CP>
only the following text would actually be searched

<CODE_EXAMPLE>
  The document entitled "Example Document" provides only an overview
  of the full capabilities of HTML.
<ENDCODE_EXAMPLE>

<P> The mechanism for partial document retrieval available with plain-text 
files is <EMPHASIS>(not\BOLD) present with HTML documents.  HTML files 
generally must be treated as a whole, with the formatting of current sections 
often very dependent on the formatting of previous sections.  This makes 
extracting a subsection perilous without extensive syntactical analyis.  On 
the positive side, HTML documents tend to be already divided into meaningful 
subdocuments (files), making retrieval of a hit naturally more-or-less within 
context.

<P> Instead of partial document retrieval, the document is processed to place
anchors for each hit, making it possible to jump directly to a particular
section of interest.  Generally this works well but may occasionally distort
the presentation of a document.

<COMMENT>(--------------------------------------------------------------------)

<HEAD1>(Search Syntax\head_search_syntax)

<P> A search may be initiated in basic three ways:

<LIST>(NUMBERED)

<LE> Appending a question-mark and search string to a file specification (the 
simple syntax of <QUOTE>(ISINDEX)-style searching).  This is 
standard HTTP, and of course must conform to HTTP syntax.

<COMMENT>(HTML=<P>)

<LE> Providing the name of the query script followed by the directory path to
be searched.  The script then returns a standard search form.

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(Forms)-based search, which allows the format and mechanism of 
the search to be controlled.

<ENDLIST>

<HEAD2>(<QUOTE>(ISINDEX) Search\head_isindex_search)

<P> Placing the HTML tag <QUOTE>(<LITERAL>(<ISINDEX>)) within a 
document's text is sufficient to inform the browser that searching is 
available for that document.  The browser will inform the user of this and 
allow a search of that document to be initiated at any time.  Note that it is 
limited to the one document. 

<P> Using the keyword search syntax explicitly is another method of initiating 
a search, and additionally can use a wildcard in the document specification.  
For example:

<CODE_EXAMPLE>
  /ht_root/doc/env/*.*?formatted
<ENDCODE_EXAMPLE>

<COMMENT>(....................................................................)

<COMMENT>(HTML=
<P> The following link provides an online demonstration search using the above
syntax.  Note the difference in the way plain-text file hits are presented
compared with those of HTML files. 

<BLOCKQUOTE>
<A HREF="/ht_root/doc/env/*.*?formatted">/ht_root/doc/env/*.*?formatted</A>
</BLOCKQUOTE>
) 

<COMMENT>(HTML/OFF)
<P><BOX>(online demonstration)
<COMMENT>(HTML/ON) 

<COMMENT>(....................................................................)

<HEAD2>(Standard Search Form\head_standard_search_form)

<P> Using the <QUOTE>(QUERY) script name followed by a URL-format path
specifying the directory to be searched returns a standard, script-generated
search form.

<COMMENT>(....................................................................)

<COMMENT>(HTML=
<P> The following link provides an online demonstration of the standard search
form.

<BLOCKQUOTE>
<A HREF="/cgi-bin/query/ht_root/doc/env/">/cgi-bin/query/ht_root/doc/env/</A>
</BLOCKQUOTE>
) 

<COMMENT>(HTML/OFF)
<P><BOX>(online demonstration)
<COMMENT>(HTML/ON) 

<COMMENT>(....................................................................)

<P> As with all search specifications, the directory specification may include
wildcard a elipsis (allowing a directory tree to be traversed) and/or file
name wildcards.  In other words, anything acceptable as VMS file system syntax
(except in URL-format of course).  See the following examples.

<COMMENT>(....................................................................)

<COMMENT>(HTML=
<BLOCKQUOTE>
<A HREF="/cgi-bin/query/ht_root/doc/env/*.html">/cgi-bin/query/ht_root/doc/env/*.html</A>
<BR><A HREF="/cgi-bin/query/ht_root/doc/.../">/cgi-bin/query/ht_root/doc/.../</A>
<BR><A HREF="/cgi-bin/query/ht_root/doc/.../*.html">/cgi-bin/query/ht_root/doc/.../*.html</A>
</BLOCKQUOTE>
) 

<COMMENT>(HTML/OFF)
<P><BOX>(online demonstration)
<COMMENT>(HTML/ON) 

<COMMENT>(....................................................................)

<HEAD2>(Forms-Based Search\head_forms_based_search)

<P> A <QUOTE>(forms-based) search is initiated by the server receiving a file 
specification, which of course may contain wildcards, followed by a 
<EMPHASIS>(search) parameter.  This is a typical HTML <EMPHASIS>(forms) format 
URL.  For example: 

<CODE_EXAMPLE>
   *.txt?search=SIMPLE
   /web/.../*.*?search=THIS
   sub_directory/*.*?search=THAT
   ../sibling_directory/*.HTML?search=OTHER
<ENDCODE_EXAMPLE>

<COMMENT>(....................................................................)

<COMMENT>(HTML=
<P> The following link provides an online demonstration search using the
form-based syntax. 

<BLOCKQUOTE>
<A HREF="/ht_root/doc/env/*.*?search=formatted">/ht_root/doc/env/*.*?search=formatted</A>
</BLOCKQUOTE>
) 

<COMMENT>(HTML/OFF)
<P><BOX>(online demonstration)
<COMMENT>(HTML/ON) 

<COMMENT>(....................................................................)

<HEAD2>(Search Options\head_search_options)

<P> Additional URI components may be appended after the initial 
<QUOTE>(search=) parameter.  These are appended with intervening
<QUOTE>(<LITERAL>(&))) characters. 

<LIST>(UNNUMBERED)

<LE> <EMPHASIS>(Case-Sensitivity.  \BOLD) An optional URI component of 
<QUOTE>(case=yes) or <QUOTE>(case=no) makes the search case-sensistive or 
case-insensistive (the default).  The following example illustrates the use of 
this syntax: 

<CODE_EXAMPLE>
  /web/html/.../*.html?search=Protocol&case=yes
  /web/html/.../*.html?search=PrOtOcOl&case=no
<ENDCODE_EXAMPLE>

<COMMENT>(....................................................................)

<COMMENT>(HTML=
<P> The following provides an online demonstration using the two links shown 
above: 

<UL>
<LI> <A HREF="*.html?search=Protocol&case=yes">
Case-sensistive search for "Protocol"</A>
<LI> <A HREF="*.html?search=PrOtOcOl&case=no">
Case-<B>in</B>sensistive search for "PrOtOcOl"</A>
</UL>
)

<COMMENT>(HTML/OFF)
<P><BOX>(online demonstration)
<COMMENT>(HTML/ON)

<COMMENT>(....................................................................)

<P>
<LE> <EMPHASIS>(Hits.  \BOLD) An optional URI component of 
<QUOTE>(hits=document) or <QUOTE>(hits=line) makes the search results be 
presented by-document (file) or by line-by-line (the default).  The following 
example illustrates the use of this syntax: 

<CODE_EXAMPLE>
  /web/html/.../*.html?search=protocol&hits=document
  /web/html/.../*.html?search=protocol&hits=line
<ENDCODE_EXAMPLE>

<COMMENT>(....................................................................)

<COMMENT>(HTML=
<P> The following provides an online demonstration using the two links shown 
above: 

<UL>
<LI> <A HREF="*.html?search=protocol&hits=document">
Search result granularity by document.</A>
<LI> <A HREF="*.html?search=protocol&hits=line">
Search result granularity by line (the default).</A>
</UL>
)

<COMMENT>(HTML/OFF)
<P><BOX>(online demonstration)
<COMMENT>(HTML/ON)

<ENDLIST>

<COMMENT>(--------------------------------------------------------------------)

<HEAD2>(Example Search Form\head_example_search_form)

<P> To allow the client to enter a search string and submit a search to the 
server a HTML level 2 <EMPHASIS>(form) construct can be used.  Here is an 
example: 

<CODE_EXAMPLE><LITERAL>
  <FORM ACTION="/web/html/.../*.html">
  Search HTML documents for: 
  <INPUT TYPE=text NAME="search">
  <INPUT TYPE=submit VALUE="[execute]">
  </FORM>
<ENDLITERAL>
<ENDCODE_EXAMPLE>

<COMMENT>(....................................................................)

<COMMENT>(HTML=
<P> The following provides an online demonstration of the form used above:

<FORM ACTION="*.html">
Search HTML documents for: 
<INPUT TYPE=text NAME="search">
<INPUT TYPE=submit VALUE="[execute]">
</FORM>
)

<COMMENT>(HTML/OFF)
<P><BOX>(online demonstration)
<COMMENT>(HTML/ON)

<COMMENT>(....................................................................)

<HEAD>(Bells and Whistles\head_bells_and_whistles)

<P> A form providing all the options refered to in 
<REFERENCE>(head_search_options) is shown below (some additional white-space 
introduced for clarity): 

<CODE_EXAMPLE><LITERAL>
  <FORM ACTION="/web/html/.../*.html">

  Search HTML documents for: 
  <INPUT TYPE=text NAME="search">
  <INPUT TYPE=submit VALUE="[execute]">

  <BR><TT><A HREF="/query/-/aboutquery.html">About</A> this search.</TT>

  <BR><TT>Output By:
  line <INPUT TYPE=radio NAME="hits" VALUE="line" CHECKED>
  document <INPUT TYPE=radio NAME="hits" VALUE="document"></TT>

  <BR><TT>Case Sensitive:
  no <INPUT TYPE=radio NAME="case" VALUE="no" CHECKED>
  yes <INPUT TYPE=radio NAME="case" VALUE="yes"></TT>

  </FORM>
<ENDLITERAL>
<ENDCODE_EXAMPLE>

<COMMENT>(....................................................................)

<COMMENT>(HTML=
<P> The following provides an online demonstration of the form used above:

<FORM ACTION="*.html">
Search HTML documents for: 
<INPUT TYPE=text NAME="search">
<INPUT TYPE=submit VALUE="[execute]">
<BR><TT><A HREF="/query/-/aboutquery.html">About</A> this search.</TT>
<BR><TT>Output By:
line <INPUT TYPE=radio NAME="hits" VALUE="line" CHECKED>
document <INPUT TYPE=radio NAME="hits" VALUE="document"></TT>
<BR><TT>Case Sensitive:
no <INPUT TYPE=radio NAME="case" VALUE="no" CHECKED>
yes <INPUT TYPE=radio NAME="case" VALUE="yes"></TT>
</FORM>
)

<COMMENT>(HTML/OFF)
<P><BOX>(online demonstration)
<COMMENT>(HTML/ON)

<COMMENT>(....................................................................)

<COMMENT>(--------------------------------------------------------------------)

<CHAPTER>(VMS Help and Text Libraries\chapter_conan)

<P> Affectionately known as <EMPHASIS>(Conan the Librarian), and with all due 
acknowlegement to Wierd Al.Yankovic <QUOTE>(:^<CPAREN>), this
script makes VMS <EMPHASIS>(Help) and <EMPHASIS>(Text) libraries accessable in
the hypertext environment. 

<P> The librarian script will be automatically activated if the file specified 
has an extension of <QUOTE>(.HLB) or <QUOTE>(.TLB).  
Alternatively it may be explicitly activated by specifying <EMPHASIS>(/conan) 
as a prefix to the file specification (but the ability to provide a relative 
specification is lost).  The following examples illustrate the syntax: 

<CODE_EXAMPLE>
  <LITERAL>(<A HREF="/sys$common/syshlp/helplib.hlb">VMS help</A>)
  <LITERAL>(<A HREF="/conan/sys$common/syshlp/helplib.hlb">VMS help via /Conan</A>)
<ENDCODE_EXAMPLE>

<COMMENT>(....................................................................)

<COMMENT>(HTML=
<P> The following links provide an online demonstration:

<UL>
<LI> <A HREF="/sys$common/syshlp/helplib.hlb">VMS Help</A>
<LI> <A HREF="/conan/sys$common/syshlp/helplib.hlb">VMS Help via /CONAN</A>
</UL>
) 

<COMMENT>(HTML/OFF)
<P><BOX>(online demonstration)
<COMMENT>(HTML/ON) 

<COMMENT>(....................................................................)

<HEAD>(Other Librarian Functionality\head_conan_other)

<P> To obtain an index of matching libraries explicitly activate the 
<EMPHASIS>(Conan) script providing a wildcard file specification.

<CODE_EXAMPLE>
  <LITERAL>(<A HREF="/conan/sys$common/syshlp/*.hlb">All Help libraries in SYS$HELP</A>)
<ENDCODE_EXAMPLE>

<COMMENT>(....................................................................)

<COMMENT>(HTML=
<P> The following link provides an online demonstration:

<UL>
<LI> <A HREF="/conan/sys$common/syshlp/*.hlb">All Help libraries in SYS$HELP</A>
</UL>
) 

<COMMENT>(HTML/OFF)
<P><BOX>(online demonstration)
<COMMENT>(HTML/ON) 

<COMMENT>(....................................................................)

<P> To obtain the library header information add a query string to the library 
file specification, as shown in the following example: 

<CODE_EXAMPLE>
  <LITERAL>(<A HREF="/conan/sys$common/syshlp/helplib.hlb?do=header">VMS help library header</A>)
<ENDCODE_EXAMPLE>

<COMMENT>(....................................................................)

<COMMENT>(HTML=
<P> The following link provides an online demonstration:

<UL>
<LI> <A HREF="/conan/sys$common/syshlp/helplib.hlb?do=header">VMS help library header</A>
</UL>
) 

<COMMENT>(HTML/OFF)
<P><BOX>(online demonstration)
<COMMENT>(HTML/ON) 

<COMMENT>(....................................................................)

<COMMENT>(--------------------------------------------------------------------)

<CHAPTER>(Bookreader Books and Libraries\chapter_hyperreader)

<P> Access to DEC's Bookreader format documentation (and any generated 
internally) is provided in the WASD hypertext environment via two integrated 
scripts, <EMPHASIS>(HyperReader), which reads the books, and 
<EMPHASIS>(HyperShelf), which reads the Library and Shelf structures. 

<P> The HyperReader and HyperShelf scripts are automatically activated when 
the document file's extension is <QUOTE>(.DECW$BOOK) and 
<QUOTE>(.DECW$BOOKSHELF) respectively.  Alternatively, the 
respective scripts may be explicitly specified (but the ability to provide a 
relative specification is lost).

<COMMENT>(....................................................................)

<P> If the server system supports Bookreader documentation collection the
following link will provide an online demonstration:

<COMMENT>(HTML=
<BLOCKQUOTE>
<A HREF="/HyperShelf/">/HyperShelf/</A>
</BLOCKQUOTE>
)

<COMMENT>(HTML/OFF)
<P><BOX>(online demonstration)
<COMMENT>(HTML/ON) 

<COMMENT>(--------------------------------------------------------------------)

<CHAPTER>(Web Document <EMPHASIS>(Upd\BOLD)ate\chapter_web_update)

<P> The <EMPHASIS>(Upd\bold)ate facility allows Web documents and file
environments to be administered from a standard browser.  This facility is
available to Web administrator and user alike.  Availability and capability
depends on the authorization environment within the server.

<P> It <EMPHASIS>(should be stressed\BOLD) that this is not designed as a full
hypertext administration or authoring tool, and for document preparation relies
on the editing capabilities of the <QUOTE>(<LITERAL>(<TEXTAREA>))
widget of the user's  browser.  It does however, allow <EMPHASIS>(ad-hoc
changes\BOLD) to be made to documents fairly easily, as well as allowing
documents to be deleted, and directories to be created and deleted.

<COMMENT>(HTML=
<P> Consult the 
<A HREF="/httpd/-/updhelp.html">current <B>Upd</B>ate
documentation</A> for usage detail.

<P> Here is <A HREF="/upd/ht_root/">an example of the interface</A>.
)

<COMMENT>(HTML/OFF)
<P> Consult the current <EMPHASIS>(Upd\BOLD)ate documentation for usage detail.
<P><BOX>(online hypertext link)
<COMMENT>(HTML/ON)

<HEAD>(Update Access Permission\head_web_update_permission)

<P> Of course, the user must have write (POST/PUT) access to the document or
area on the server (i.e. the <EMPHASIS>(path)) and the server account have file
system permission to write into the <UNDERLINE>(parent directory).

<P> Contact the Web Administrator for further information on the availablility
of authentication and authorization permissions to do on-line updates of Web
paths.

<P> The server will report <QUOTE>(Insufficient privilege or object protection
violation ... /path/) if it does not have file system permission to write into
a directory.

<P> Write access by the server into VMS directories (using the POST or PUT
HTTP methods) is controlled using VMS ACLs. <EMPHASIS>(This is in addition to
the path authorization of the server itself of course!\BOLD) The requirement
to have an ACL on the directory prevents inadvertant mapping/authorization of
a path resulting in the ability to write somewhere not intended.

<P> Two different ACLs implement two grades of access.

<LIST>(NUMBERED)

<LE> If the ACL grants <EMPHASIS>(CONTROL\BOLD) access to the server account
then only VMS-authenticated usernames with security profiles can potentially
write to the directory. Only potentially, because a further check is made to
assess whether that VMS account in particular has write access.

<P> This example shows a suitable ACL that applies only to the original
directory:

<CODE_EXAMPLE>
  $ SET SECURITY directory.DIR -
    /ACL=(IDENT=HTTP$SERVER,ACCESS=READ+CONTROL)
<ENDCODE_EXAMPLE>

<CP> This example shows setting an ACL that will propagate to created files
and importantly, subdirectories:

<CODE_EXAMPLE>
  $ SET SECURITY directory.DIR -
    /ACL=((IDENT=HTTP$SERVER,OPTIONS=DEFAULT,ACCESS=READ+WRITE+DELETE+CONTROL), -
          (IDENT=HTTP$SERVER,ACCESS=READ+WRITE+DELETE+CONTROL))
<ENDCODE_EXAMPLE>

<LE> If the ACL grants <EMPHASIS>(WRITE\BOLD) access then the directory can be
written into by any authenticated username for the authorized path.

<P> This example shows a suitable ACL that applies only to the original
directory:

<CODE_EXAMPLE>
  $ SET SECURITY directory.DIR -
    /ACL=(IDENT=HTTP$SERVER,ACCESS=READ+WRITE)
<ENDCODE_EXAMPLE>

<CP> This example shows setting an ACL that will propagate to created files
and importantly, subdirectories:

<CODE_EXAMPLE>
  $ SET SECURITY directory.DIR -
    /ACL=((IDENT=HTTP$SERVER,OPTIONS=DEFAULT,ACCESS=READ+WRITE+DELETE), -
          (IDENT=HTTP$SERVER,ACCESS=READ+WRITE+DELETE))
<ENDCODE_EXAMPLE>

<ENDLIST>

<COMMENT>(--------------------------------------------------------------------)

<CHAPTER>(Document Printing\chapter_hprints)

<P> The <EMPHASIS>(print) script allows the printing of PostScript, text and 
other files on WASD printers.  It is restricted to browsers from WASD hosts 
<EMPHASIS>(for obvious reasons!), or if configured for your local site! 

<P> The print script may be accessed by specifying <EMPHASIS>(/print) as a 
prefix to the document specification to be printed, as in the following 
example: 

<CODE_EXAMPLE>
  <LITERAL>(<A HREF="/print/ht_root/doc/htd/htd.ps">This Document</A>)
<ENDCODE_EXAMPLE>

<P> When this link is selected an online <EMPHASIS>(form) is presented to the 
user allowing the selection of the print queue required.  An optional 
<EMPHASIS>(check-box) allows the selection of <EMPHASIS>(two document pages 
per printed sheet) on supporting print queues, allowing the ready conservation 
of paper.  The form can then be <EMPHASIS>(submitted) to print the file. 

<COMMENT>(....................................................................)

<COMMENT>(HTML=
<P> The following is an online demonstration.  Selecting this link presents 
the print queue selection form.  Do not select the <EMPHASIS>(print) button 
unless you wish a copy of this document, use your browser to navigate 
backwards from the page: 

<P> <A HREF="/print/ht_root/doc/env/env.ps">Print this document.</A>
)

<COMMENT>(HTML/OFF)
<P><BOX>(online demonstration)
<COMMENT>(HTML/ON)

<COMMENT>(....................................................................)

<COMMENT>(--------------------------------------------------------------------)

