(online demonstration) (HTML/ON) (....................................................................)

((Browser (HTML) Supported Targets\BOLD)) (2\15) (Target\Description) (HTML=) ((_blank\BOLD)\opens the file in a new window or tab) ((_self\BOLD)\in the same frame) ((_parent\BOLD)\in the parent frame) ((_top\BOLD)\in the full body of the window) (((framename)\BOLD)\in a named frame) There is a per-path mapping (SET dir=target=) equivalent. (--------------------------------------------------------------------) (Specifying Content-Type\sect_dir_content_type)

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 (sect_explicit_type).

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.

It is posssible to "force" the content-type for all files in a particular directory. Enter the path to the directory and then add ?httpd=index&type=text/plain

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

This is an example: (....................................................................) (HTML=

*.*
*.*?httpd=index&type=text/plain

) (HTML/OFF)

(online demonstration) (HTML/ON) (YMMV) Some browsers and operating systems insist they know better than the server and ignore the response-specified content-type, inferring presentation of the content from (magic bytes) in that content or the trailing dot-separated (file name extension). (--------------------------------------------------------------------) (Icon Plain Text Link\sect_dir_icon_link)

Directory listing icons are generally links to the content of the file displayed as plain-text ((sect_directory_icons)). This can be disabled using the (ilink) directive. ?httpd=index&ilink=no (get me *.*) There is a per-path mapping (SET dir=noilink) equivalent. (--------------------------------------------------------------------) (Query String\sect_dir_query_string)

The (query=()) directive can be used to propagate an explicit query string to subsequent directory requests. This is intended to be applied from a .WWW_WASD control file because actual URI query strings are propagated by default. # an example .WWW_WASD file query=httpd=index&style=sort2&sort=s- (--------------------------------------------------------------------) (Allowing Override\sect_dir_override)

When a .WWW_WASD file is present in a directory it takes precedence over any SSI or URI (query string) directives also available, unless it includes an (override=yes) directive. When this is present any SSI and/or URI directive string is also applied to the request. # an example .WWW_WASD file override=yes (--------------------------------------------------------------------) (Directory Tree\sect_dtree)

The (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 (chapter_directory_listing)).

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 (*.*) should always be appended.

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

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: ?httpd=index&autoscript=no ?httpd=index&readme=no ?httpd=index&script=(script-name) ?httpd=index&script=(script-name)&readme=no (....................................................................) (HTML=

The following links provide online demonstrations:

/wasd_root/ tree
/wasd_root/ (VMS-ish) tree

) (HTML/OFF) (/wasd_root/ tree) (/wasd_root/ (VMS-ish) tree)

(online demonstration) (HTML/ON) (....................................................................)

Note that this activity is I/O intensive, and can take a considerable period if the tree is extensive. (--------------------------------------------------------------------) (Server Side Includes (SSI)\chapter_ssi)

The HTML pre-processor is used to provide dynamic information inside of an otherwise static, HTML (HyperText Markup Language) document. The HTTPd server provides this as internal functionality, scanning the input document for special pre-processor (directives), which are replaced by dynamic information based upon the particular directive.

As of version 5.1 WASD SSI has been enhanced to provide flow-control statements, allowing blocks of the document to be conditionally processed, see (sect_ssi_flow_control). These extensions allow quite versatile documents to be created without resorting to script processing.

Two documents are provided as examples of SSI processing. (UNNUMBERED) (A simple SSI document.\BOLD)

(HTML= WASD_ROOT:[DOC.ENV]SSI.SHTML   (access as SSI) ) (HTML/OFF) WASD_ROOT:[DOC.ENV]SSI.SHTML

(online demonstration) (HTML/ON) (An SSI document using variable assignment and flow-control.\BOLD)

(HTML= WASD_ROOT:[DOC.ENV]XSSI.SHTML   (access as SSI) ) (HTML/OFF) WASD_ROOT:[DOC.ENV]SSI.SHTML

(online demonstration) (HTML/ON)

By default the HTML pre-processor is invoked when the document file's extension is (.SHTML). As there is a significant overhead with pre-processed HTML compared to normal HTML, it should only be used when it serves a useful documentary purpose, and not just for the novelty.

Essential compatibility with OSU Server Side Includes is provided. This may ease any transition between the two. See (sect_ssi_osu) for further information. (....................................................................) (Virtual Documents\sect_ssi_virtual_doc)

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 (sect_ssi_last_modified)). (Example 1\sect_ssi_virtual_example_1)

This provides an example of the efficient use of SSI processing to create virtual documents. Each page will comprise a header (containing the body tag and page header, etc), the document proper and a footer (containg the end-of-page information, modification date, and end-body tag, etc).

This is the document information.

Blah, blah, blah.

A more efficient variant places the document proper in its own, plain HTML file which is then #included (it is much, much, much more efficient for the server to (throw) a file at the network, than parse every character in one ;^) (Example 2\sect_ssi_virtual_example_2)

This example provides a seemingly more convoluted, but very much more powerful configuration, that uses recursion to greatly simplify maintenance of common-layout documents for the end-user.

File 1; the document accessed via the browser URL, doesn't matter what its name is, this configuration is completely naming independent.

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

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

This is just a bunch of HTML!

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

(HTML=

The following link provides an example of a such a virtual document. ) (HTML/OFF)

The following link provides an example of such a virtual document.

(online demonstration) (HTML/ON) (....................................................................) (Last-Modified Information\sect_ssi_last_modified)

SSI documents generally contain dynamic elements, that is those that may change with each access to the document (e.g. current date/time). This makes evaluation of any document modification date difficult and so by default no (Last-Modified: (timestamp)) information is supplied against an SSI document. The potential efficiencies of having document timestamps, so that requests can be made for a document to be returned only if modified after a certain date/time ((If-Modified-Since: (timestamp))), are significant against the CPU overheads of processing SSI documents.

WASD allows the document author to determine whether or not a last-modified header field should be generated for a particular document and which contributing file(s) should be used to determine it. This is done using the #modified directive. If a virtual document is made up of multiple source documents (files) each can be assessed using multiple virtual= or file= tags, the most recently modified will be used to determine if the virtual document has been modified, and also to generate the last-modified timestamp.

The (if-modified-since) tag compares the determined revision date/time of the document file(s) with any (If-Modified-Since:) timestamp supplied with the request. If the virtual document's revision date/time is the same or older than the request's then a not-modified (304 status) header is generated and sent to the client and document processing ceases. If more recent an appropriate (Last-Modified:) header field is added to the document and it continues to be processed.

If a request has a "Pragma: no-cache" field (as with Navigator's (reload) function) the document is always generated (this is consistent with general WASD behaviour). The following example illustrates the essential features.

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). (....................................................................) (Pre-Expiring Documents\sect_ssi_pre_expire)

SSI preprocessed documents are (dynamic) in the sense that the information presented can be different every time the document is generated (e.g. if time directives are included). If it is important that each time the document is accessed it is regenerated then an HTML META tag can be included in the HTML header to cause the document to (expire). This will result in the document being reloaded with each access. This can be accomplished two ways. (UNNUMBERED) Use the #modified directive to include an (Expires: (timestamp)) response header field. Place the following construct at the beginning of the SSI document. An alternative, if the objective to to pre-expire the document, is to specify an expiry of zero. The is specially handled by the SSI engine. It adds an expiry response header field, plus cache-control header fields to suppress document caching (on compliant browsers). (Directive Syntax\sect_preprocessing_syntax)

The syntax follows closely that used by the other implementations, but some directives are tailored to the WASD and VMS environment. The directive is enclosed within an HTML comment and takes the form: (<)!--#(directive\BOLD) [[(tag1\BOLD)="(value)"] [(tag2\BOLD)="(value)"] ...] --(>)

A (tag) provides parameter information to the directive. A directive may have zero, one or more parameters. Values supplied with any tag may be literal or via variable substitution (see (sect_ssi_variables). A value must be encolosed by quotation marks if it contains white-space.

A directive (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 () while the following is not (and would produce an error) ()

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. (Directives\sect_preprocessing_directives)

((SSI Directives\BOLD))

(3\10\30) (Directive\Description\Section) (HTML=) ((#accesses\BOLD)\document access count\ (sect_ssi_accesses)) ((#config\BOLD)\document processing options\ (sect_ssi_config)) ((#dir\BOLD)\directory listing\ (sect_ssi_dir)) ((#dcl\BOLD)\DCL command processing\ (sect_ssi_dcl)) ((#echo\BOLD)\output information\ (sect_ssi_echo)) ((#elif\BOLD)\flow control\ (sect_ssi_elif)) ((#else\BOLD)\flow control\ (sect_ssi_else)) ((#endif\BOLD)\flow control\ (sect_ssi_endif)) ((#exec\BOLD)\same as (#dcl)\ (sect_ssi_exec)) ((#exit\BOLD)\flow control, stop current document processing\ (sect_ssi_exit)) ((#fcreated\BOLD)\output file creation date/time\ (sect_ssi_fcreated)) ((#flastmod\BOLD)\output file last modification date/time\ (sect_ssi_flastmod)) ((#fsize\BOLD)\output file size\ (sect_ssi_fsize)) ((#if\BOLD)\flow control\ (sect_ssi_if)) ((#include\BOLD)\include a text file or another SSI document\ (sect_ssi_include)) ((#modified\BOLD)\HTTP response control\ (sect_ssi_modified)) ((#orif\BOLD)\flow control\ (sect_ssi_orif)) ((#printenv\BOLD)\list document variables\ (sect_ssi_printenv)) ((#set\BOLD)\assign value to a document variable\ (sect_ssi_set)) ((#ssi\BOLD)\block of SSI statements\ (sect_ssi_ssi)) ((#stop\BOLD)\stop SSI processing completely\ (sect_ssi_stop)) (....................................................................) (#ACCESSES\sect_ssi_accesses)

The (#accesses) directive allows the number of times the document has been accessed to be included. It does this by creating a counter file in the same location and using the same name with a dollar symbol appended to the type (extension). The count may be reset by deleting the file. This is an expensive function (in terms of file system activity) and so should be used appropriately. It can be disabled by server configuration. Three tags provide additional functionality: (UNNUMBERED) (ORDINAL\BOLD) (<)!--#accesses ordinal --(>)

Provides the count as 1st, 2nd, 3rd, 4th, 5th 10th, 11th, 12th 120th, 121st, 122nd, etc. (SINCE\BOLD) (<)!--#accesses since="(text)" --(>)

This tag includes the specified text immediately after the access count is displayed, then adds the creation date of the counter file. (TIMEFMT\BOLD) (<)!--#accesses since="(text)" timefmt="[(time-format)]" --(>) Allows the time format of the (since) tag to be supplied, where (time-format) is specified according to (sect_ssi_time_format). (....................................................................) (#CONFIG\sect_ssi_config)

The (#config) directive allows time and file size formats to be specified for all subsequent directives providing these values. Optional specifications for individual directives may still be made, and override, do not supercede, any specification made using a (config) directive. A (config) directive may be made once, or any number of times in a document, and applies until another is made, or until the end of the document. (UNNUMBERED) (ERRMSG\BOLD) (<)!--#config errmsg="(string)" --(>)

This directive allows the error message generated if a problem problem processing the SSI document occurs (e.g. miss-spelled directive) to be specified in the document. (TIMEFMT\BOLD) (<)!--#config timefmt="(time-format)" --(>) Where (time-format) is specified according to (sect_ssi_time_format). (SIZEFMT\BOLD) (<)!--#config sizefmt="(size-format)" --(>) Where (size-format) is specified using the following keywords: (UNNUMBERED) (abbrev) (as bytes, kbytes, Mbytes) (blocks) (VMS blocks, used) (bytes) (e.g. (1,256,731 bytes)) (TRACE\BOLD) (<)!--#config trace="(1)|(0)" --(>)

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

Output from a trace is colour-coded. (UNNUMBERED) (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. (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. (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 ((=)), when being read the character is a full-colon ((:)). (Black - \BOLD) Document (HTML and text) output is displayed as black plain text. (HTML=

The following link provides an example of a document trace. ) (HTML/OFF)

The following link provides an example of a document trace.

(online demonstration) (HTML/ON) (....................................................................) (#DIR\sect_ssi_dir)

The (#dir) directive generates an (Index of ) directory listing inside an HTML document. Apart from not generating a title (it is up to the pre-processed document to title, or otherwise caption, the listing) it provides all the functionality of the WASD HTTPd directory listing (see (chapter_directory_listing)), including query string format control via the (par=) parameter (note that from the (?httpd=index) introducer used with directory listings is not necessary from SSI). It is an WASD HTTPd extension to pre-processed HTML. (UNNUMBERED) (FILE\BOLD)

Listing specified using a VMS file path. (<)!--#dir file="(file-name)" [par="(server-directive(s))"] --(>) (VIRTUAL\BOLD)

Listing specified using URL-style syntax. (<)!--#dir virtual="(path)" [par="(server-directive(s))"] --(>)

For example: () () (....................................................................) (#DCL\sect_ssi_DCL)

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

By default, output from the DCL command has all HTML-forbidden characters (e.g. ((<)), ((&))) escaped before inclusion in the processed document. Thus command output cannot interfere with document markup, but nor can the DCL command provide HTML markup. This behaviour may be changed by appending the following tag to the directive: type="text/html"

Some (#dcl) directives are for (privileged) documents only, documents defined as those being owned by the SYSTEM account, and not being world-writeable. The reason for this should be obvious. There are implicit security concerns about any document being able to execute any DCL command(s), even if it is being executed in a completely unprivileged process. Hence only (innocuous) commands are allowed in standard documents. (UNNUMBERED) (SAY\BOLD)

Execute the DCL (WRITE SYS$OUTPUT) command, using the specified parameter. () (SHOW\BOLD)

Execute the DCL (SHOW) command, using the specified parameter. () (DIR\BOLD)

Execute the DCL (DIRECTORY) command, using the supplied file specification. Qualifiers may be included in the optional (par) tag to control the format of the listing. () () () (EXEC\BOLD) (privileged)

Execute the specified DCL command. () (FILE\BOLD) (privileged)

Execute the DCL command procedure specified as a VMS file path, with any specified parameters applied to the procedure. () (VIRTUAL\BOLD) (privileged)

Execute the DCL command procedure specified in URL-style syntax, with any specified parameters applied to the procedure. () (CGI\BOLD)

Execute the specified CGI script. The CGI response header is suppressed and only the response body is included in the document. () (....................................................................) (#ECHO\sect_ssi_echo)

The (#echo) directive incorporates the specified information into the processed document. Multiple tags may be used within the one directive. (UNNUMBERED) (VALUE=\BOLD) (VAR=\BOLD)

Any SSI variable (e.g. CREATED), CGI variable (e.g. HTTP_USER_AGENT), or document assigned variable (e.g. EXAMPLE1), see (sect_ssi_variables). (<)!--#echo value={created} var={example1} --(>) (CREATED\BOLD)

The date/time of the current document's creation. (<)!--#echo created[="(time-format)"] --(>) (DATE_LOCAL\BOLD)

Include the current date/time. (<)!--#echo date_local[="(time-format)"] --(>) (DATE_GMT\BOLD)

Include the current Greenwich Mean Time (UTC) date/time. (<)!--#echo date_gmt[="(time-format)"] --(>) (DOCUMENT_NAME\BOLD)

The current document's URL-style path. (<)!--#echo document_name --(>) (FILE_NAME\BOLD)

The current document's VMS file path. (<)!--#echo file_name --(>) (HEADER\BOLD)

Append the specified string to the response header (with correct carriage control). Should be used as early as possible in the SSI document. (<)!--#echo header="Pragma: no-cache" --(>) (<)!--#echo header="X-Extension-Header: just an example!" --(>) (LAST_MODIFIED\BOLD)

The date/time of the current document's last modification. (<)!--#echo last_modified[="(time-format)"] --(>) (....................................................................) (#ELIF\sect_ssi_elif)

The (#elif) directive (else-if) allows blocks of HTML markup and SSI directives to be conditionally processed, see (sect_ssi_flow_control) and (sect_ssi_if). This directive effectively allows a (case) statement to be constructed. (<)!--#elif var="[({variable})|(literal)" --(>) (....................................................................) (#ELSE\sect_ssi_else)

The (else) directive allows blocks of HTML markup and SSI directives to be conditionally processed, see (sect_ssi_flow_control). It is the default block after an (#if), (#orif) or (#elif). (<)!--#else --(>) (....................................................................) (#ENDIF\sect_ssi_endif)

The (#endif) directive marks the end of a block of document text being conditionally processed, see (sect_ssi_flow_control). (<)!--#endif --(>) (....................................................................) (#EXEC\sect_ssi_exec)

The (#exec) directive executes a DCL command and incorporates the output into the processed document. It is the VMS equivalent of the (exec) shell directive of some Unix implementations. It is implemented in the same way as the #DCL directive, and so the general detail of that directive applies. It supports both the (cmd) tag and the (cgi) tag, allowing execution of CGI scripts (the response header is absorbed). () ()

The (exec) directive is for (privileged) documents only, documents defined as those being owned by the SYSTEM account, and not being world-writeable. The reason for this should be obvious. There are implicit security concerns about any document being able to execute any DCL command(s), even if it is being executed in a completely unprivileged process. (....................................................................) (#EXIT\sect_ssi_exit)

The (#exit) directive causes the server to stop processing the current SSI file. If the current file was an #included SSI file, processing continues back with the parent file. Note that the (#stop) directive also is available, it stops processing of the entire virtual document. (<)!--#exit --(>) (....................................................................) (#FCREATED\sect_ssi_fcreated)

The (#fcreated) directive incorporates the creation date/time of a specified file/document into the processed document. (UNNUMBERED) (FILE\BOLD)

Document specified using a VMS file path. (<)!--#fcreated file="(file-name)" [fmt="(time-format)"] --(>) (VIRTUAL\BOLD)

Document specified using URL-style syntax. (<)!--#fcreated virtual="(path)" [fmt="(time-format)"] --(>) (....................................................................) (#FLASTMOD\sect_ssi_flastmod)

The (#flastmod) directive incorporates the last modification date/time of a specified file/document into the processed document. (UNNUMBERED) (FILE\BOLD)

Document specified using a VMS file path. (<)!--#flastmod file="(file-name)" [fmt="(time-format)"] --(>) (VIRTUAL\BOLD)

Document specified using URL-style syntax. (<)!--#flastmod virtual="(path)" [fmt="(time-format)"] --(>) (....................................................................) (#FSIZE\sect_ssi_fsize)

The (#fsize) directive incorporates the size, in bytes, kbytes or Mbytes, of a specified file/document into the processed document. (UNNUMBERED) (FILE\BOLD)

Document specified using a VMS file path. (<)!--#fsize file="(file-name)" [fmt="(size-format)"] --(>) (VIRTUAL\BOLD)

Document specified using URL-style syntax. (<)!--#fsize virtual="(path)" [fmt="(size-format)"] --(>) (....................................................................) (#IF\sect_ssi_if)

The (#if) directive allows blocks of HTML markup and SSI directives to be conditionally processed, see (sect_ssi_flow_control). (UNNUMBERED) (VAR=\BOLD)

Variable the decision will be based upon. (<)!--#if var="[({variable})|(literal)]" --(>) (EQS=\BOLD)

Is the string the same as in the variable? (EQ=\BOLD)

If the variable is a number is it the same as this? (GT=\BOLD)

If the variable is a number is it greater than this? (LT=\BOLD)

If the variable is a number is it less than this? (SRCH=\BOLD)

Search the variable for this string. May contain the (*) wildcard, matching one or more characters, and the (%), matching any single character.

As in the following examples: (<)!--#if value={DOCUMENT_URI} eqs="/wasd_root/doc/env/xssi.shtml" --(>) (<)!--#if value={COUNT} lt=10 --(>) (<)!--#if value="This is a test!" eqs={STRING} --(>) (<)!--#if value={PATH_INFO} srch="*/env/*" --(>) (....................................................................) (#INCLUDE\sect_ssi_include)

The (#include) directive incorporates the contents of a specified file/document into the processed document. (UNNUMBERED) (FILE\BOLD)

Include the contents of the document specified using a VMS file specification. (<)!--#include file="(file-name)" --(>) (VIRTUAL\BOLD)

Include the contents of the document specified using URL-style syntax. (<)!--#include virtual="(path)" --(>)

The contents of the specified file are included differently depending on the MIME content-type of the file. Files of (text/html) content-type (HTML documents) are included directly, and any HTML tags within them contribute to the markup of the document. Files of (text/plain) content-type (plain-text documents) are encapsulated in ((

)) tags and have all HTML-forbidden characters (e.g. ((<)), ((&))) escaped before inclusion in the processed document. An HTML file can be forced to be included as plain-text by using the following syntax: (<)!--#include virtual="example.html" type="text/plain" --(>)

To (force) a file to be considered as text regardless of the actual content (as determined by the server from the file type), use on of the following depending on whether it should be rendered as plain or HTML text. (<)!--#include virtual="example.html" content="text/plain" --(>) (<)!--#include virtual="example.html" content="text/html" --(>)

Other SSI files may be included and their content dynamically included in the resulting document. To prevent a recursive inclusion of documents the nesting level of SSI documents is limited to five. (....................................................................) (#MODIFIED\sect_ssi_modified)

The (#modified) directive allows a document author to control the (Last-Modified:)/(If-Modified-Since:)/(304 Not modified) behaviour of an SSI document. See (sect_ssi_virtual_doc). (UNNUMBERED) ((no tag)\BOLD)

Get the last-modified date/time of the current document. (<)!--#modified --(>) (FILE\BOLD)

Get the last-modified date/time of the document specified using VMS file specification. (<)!--#modified file="(file-name)" --(>) (VIRTUAL\BOLD)

Get the last-modified date/time of the document specified using URL-style syntax. (<)!--#modified virtual="(path)" --(>) (IF-MODIFIED-SINCE\BOLD)

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

Adds a (Last-Modified:) response header field using a timestamp retrieved using (file) or (virtual) (note: unnecessary if the (if-modified-since) tag is used). (<)!--#modified last-modified --(>) (EXPIRES\BOLD)

Adds a (Expires:) response header field. The string literal should be a legitimate RFC-1123 date string. This can be used for pre-expiring documents (so they are always reloaded), set it to a date in the not-too-distant past (as in the example below). Of course it could also be used for setting the legitimate future expiry of documents. (<)!--#modified expires="Fri, 13 Jan 1978 14:00:00 GMT" --(>) (....................................................................) (#ORIF\sect_ssi_orif)

The (#orif) directive (or-if) allows blocks of HTML markup and SSI directives to be conditionally processed, see (sect_ssi_flow_control) and (sect_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. (<)!--#orif var="[({variable})|(literal)" --(>) (....................................................................) (#PRINTENV\sect_ssi_printenv)

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

The following link uses the example SSI document WASD_ROOT:[DOC.ENV]XSSI.SHTML to demonstrate this.

  xssi.shtml?httpd=ssi&printenv=yes&test1=one&test2=two&test3=three

) (HTML/OFF)

The following link uses the example SSI document, WASD_ROOT:[DOC.ENV]XSSI.SHTML, to demonstrate this.

(online demonstration) (HTML/ON) (....................................................................) (#SET\sect_ssi_set)

The (#set) directive allows a user variable to be assigned or modified, see (sect_ssi_variables). (<)!--#set var="(variable-name)" value="(whatever)" --(>)

Variables are always stored as strings and have a finite but generally usable length. Some comparison tags provided in the flow-control directives treat the contents of variables as numbers. A numeric conversion is done at evaluation time. (....................................................................) (#SSI\sect_ssi_ssi)

The (#ssi) directive allows multiple SSI directives to be used without the requirement to enclose them in the normal HTML comment tags (i.e. ()). This helps reduce the clutter in an SSI document that uses the extended capabilities of variable assignment and flow control. Document HTML cannot be included between the opening and closing comment elements of the (#ssi) tag, although of course document output can be generated using the (#echo) tag. () (HTML=

The example SSI document WASD_ROOT:[DOC.ENV]XSSI.SHTML illustrates this concept. ) (HTML/OFF)

The example SSI document, WASD_ROOT:[DOC.ENV]XSSI.SHTML, illustrates this concept. (HTML/ON) (....................................................................) (#STOP\sect_ssi_stop)

The (#stop) directive causes the server to stop processing the virtual document. It can be used with flow control structures to conditionally process only part of a virtual document. Note that the (#exit) directive also is available, it stops processing of the current file (for nested #includes, etc.). (<)!--#stop --(>) (....................................................................) (Variables\sect_ssi_variables)

The SSI processor maintains information about the server, date and time, request path, request parameters, etc., accessible via (variable name). Although these (server variables) cannot be modified by the document the processor also allows the author to create and assign new (document variables) by name. SSI variables have global scope, with a small number of exceptions listed below. That is, the same set of variables are shared with the parent document by any other SSI documents (#included), and any included by those, etc.

Local variables: (UNNUMBERED) DOCUMENT_DEPTH, the current nesting level for #included SSI files PARENT_FILE_NAME, if an #included SSI file the name of the including file THIS_FILE_NAME, the name of the SSI file currently being processed

One other special-purpose variable, THE_FILE_NAME, see (sect_ssi_var_ht_file_name).

Server assigned variables comprise some SSI-specific as well as the same CGI variables available to CGI scripts. (HTML= These may be found listed in the "CGI Scripting" chapter of the Technical Overview.

The following link provides a list of the SSI and CGI variables available to SSI documents. ) (HTML/OFF)

These may be found listed in the (CGI Scripting) chapter of the (Technical Overview).

(online demonstration) (HTML/ON)

Whenever a directive uses information from a tag (see (sect_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 (<)!--#include virtual={FILENAME} --(>) would include the file named by the contents of a variable named (FILENAME). When using a variable in a tag it is not necessary to enclose the tag parameter in quotation marks unless there is additional literal text. Variables may also be used within literal strings, producing a compound, resultant string, as in the following example (<)!--#echo var="Hello {REMOTE_HOST}, time here is {LOCAL_TIME}" --(>)

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

Variables are considered to be boolean (false) if empty and (true) when not empty. (Substrings\sect_ssi_var_substrings)

It is also possible to extract substrings from variables using the following syntax, {(variable-name),(start-index),(count)}

where the start-index begins with the zeroth character and numbers up to the last character in the string, and count may be zero or any positive number. If only one number is supplied it is regarded as a count and the string is extracted from the zeroth character.

To illustrate,

would output That was an example! (Other (Functions)\sect_ssi_var_functions) (UNNUMBERED) (LENGTH - \BOLD) This (function) returns the length of the parameter string (or substring). {(variable-name)[,(start-index)],(count)]],length}

For example

would output "This is an example!" is 19 characters long. "is" is 2 characters long! (EXISTS - \BOLD) This (function) returns (true) if the variable exists and (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! var={(variable-name),exists}

For example "BOGUS_VARIABLE" exists! "BOGUS_VARIABLE" does NOT exist! (Example\sect_ssi_var_example) (HTML=

The example SSI document WASD_ROOT:[DOC.ENV]XSSI.SHTML illustrates these concepts. ) (HTML/OFF)

The example SSI document, WASD_ROOT:[DOC.ENV]XSSI.SHTML, illustrates these concepts. (HTML/ON) (....................................................................) (Flow Control\sect_ssi_flow_control)

WASD SSI allows blocks of document to be conditionally processed. This uses constructs in a similar way to any programming language. The emphasis has been on simplicity and speed of processing. No complex expression parser is provided. Despite this, complex document constructs can be implemented. Flow control structures may be nested up to eight levels.

(UNNUMBERED) (#if - \BOLD) Marks the start of a conditionally processed block. If evaluated true the block is processed. (#orif - \BOLD) Allows a document block to be processed if one of multiple conditions are met. Must be used immediately following a (#if) or (elif). (This is the only really WASD-idiosyncratic element) (#elif - \BOLD) Allows a series of conditionals to be tested each with its own document block available for processing. Allows a type of case statement to be constructed. (#else - \BOLD) Provides a default document block following unsuccessful (#if), (orif) and (elif) testing and consequent non-processed blocks. (#endif - \BOLD) Terminates a conditional block.

The (#if), (#orif) and (#elif) directives must provide an evaluation. This can be single variable, which if numeric and non-zero is considered true, if zero if false, or can be a string, which if empty is false, and if not empty is true. Tests can be made against the variable which when evaluated return a true or false. Multiple tests may be made against the one variable, or against more than one variable. Multiple tests act as a logical AND of the results and terminate when the first fails.

(UNNUMBERED) (eqs - \BOLD) If the supplied string is the same as the variable string. (srch - \BOLD) If the variable string matches the supplied search string. The search string may contain the (*), matching any zero or more characters, and (%), matching any one character. (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. (lt - \BOLD) If the numeric value of the variable is less than that of the supplied number. (gt - \BOLD) If the numeric value of the variable is greater than that of the supplied number.

Any evaluation can have the result negated by prefixing it with an exclamation point. For instance, the first of these examples would produce a (false) result, the second (true).

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

Simple XSSI Demonstration

, the time here is . (Sorry, I do not know your name, DNS lookup must be disabled!) (HTML=

The example SSI document WASD_ROOT:[DOC.ENV]XSSI.SHTML further illustrates these concepts. ) (HTML/OFF)

The example SSI document, WASD_ROOT:[DOC.ENV]XSSI.SHTML, further illustrates these concepts. (HTML/ON) (....................................................................) (Query Strings\sect_ssi_query_strings)

A query string may be passed to an SSI document in much the same way as to a CGI script. In this way the behaviour of the document can be varied in accordance to information explicitly passed to it when accessed. To prevent the server's default query engine being given the request precede any query string with (?httpd=ssi). The server detects this and passes the request instead to the SSI processor. Just append the desired query string components to this as if they were form elements. For example: ?httpd=ssi&printenv=no ?httpd=ssi&printenv=yes ?httpd=ssi&trace=yes&test2=one&test2=two&test3=three (HTML=

The following link uses the example SSI document WASD_ROOT:[DOC.ENV]XSSI.SHTML to demonstrate this. Look for the (FORM_TEST1=one), etc.

  xssi.shtml?httpd=ssi&printenv=yes&test1=one&test2=two&test3=three

) (HTML/OFF)

The following link uses the example SSI document, WASD_ROOT:[DOC.ENV]XSSI.SHTML, to demonstrate this. Look for the (FORM_TEST1=one), etc.

(online demonstration) (HTML/ON) (--------------------------------------------------------------------) (File and Virtual Specifications\sect_ssi_file_virtual)

Documents may be specified using either the (FILE) or (VIRTUAL) tags.

The (FILE) tag expects an absolute VMS file specification.

The (VIRTUAL) tag expects an URL-style path to a document. This can be an absolute or relative path. See (sect_document_specification) for further details. (THE_FILE_NAME\sect_ssi_var_ht_file_name)

Generally, when an error are encountered document processing halts and and an error report is generated. For some common circumstances, in particular the existance or not of a particular file, may require an alternative action. For file activities (e.g. #include, #flastmod, #created, #fsize) the optional fmt="" tag provides some measure of control on error behaviour. If the format string begins with a (?) files not found are not reported as errors and processing continues. Other file systems errors, such as directory not found, syntax errors, etc., are always reported.

Every time a file is accessed (e.g. #include, #flastmod) the server variable THE_FILE_NAME gets set to that name if successful, or reset to empty if unsuccessful. This variable can be checked to determine success or otherwise. (UNNUMBERED) For #included files, the 'fmt="?"' just suppresses an error report, if the file exists then it is included. For #modified file specifications use 'fmt="?"' to suppress error reporting on evaluation of files that may exist but are not mandatory. 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. File does not exist! File exists! (--------------------------------------------------------------------) (Time Format\sect_ssi_time_format)

Whenever a time directive is used an optional tag can be included to specify the format of the output. The default looks a little VMS-ish. If a format specification is made it must confirm to the C programming language function (strftime()).

The format specifier follows a similar syntax to the C standard library (printf()) family of functions, where conversion specifiers are introduced by percentage symbols. Here are some example uses: The date is (<)!--#echo date_local fmt="%d/%m/%y" --(>). The time is (<)!--#echo date_local fmt="%r" --(>). The day-of-the-week is (<)!--#echo date_local fmt="%A" --(>).

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

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

((strftime() Format Directives\BOLD))

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

Essential compatibility with OSU Server Side Includes directives is provided. This is intended to ease any transition to WASD, as existing SSI documents will not need to be changed unless any of the WASD capabilities are required. To provide transparent processing of OSU (.HTMLX) files ensure the following WASD configuration is in place.

In HTTPD$CONFIG file: [AddType] .HTMLX text/x-shtml - OSU SSI HTML

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

In HTTPD$MAP file: redirect /*.*.htmlx /*.htmlx?httpd=ssi&__part=*

This provides a mechanism for the OSU part-document facility. (Yes, the (__part) has two leading underscores!) (OSU Directives\sect_ssi_osu_directives)

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.

((OSU Compatible Directives\BOLD))

(2\30) (Directive\Description) (HTML=) ((#begin (label) [(label)]\BOLD)\ delimit a part-document (see (sect_ssi_osu_part))) ((#config verify=1 \BOLD)\ enable commented-tag trace output) ((#echo accesses\BOLD)\document access count) ((#echo accesses_ordinal\BOLD)\document access count) ((#echo getenv=""\BOLD)\output logical or symbol) ((#echo hw_name\BOLD)\system hardware name) ((#echo server_name\BOLD)\HTTPd server host name) ((#echo server_version\BOLD)\HTTPd software version) ((#echo vms_version\BOLD)\HTTPd system version of VMS) ((#end (label) [(label)]\BOLD)\ delimit a part-document (see (sect_ssi_osu_part))) ((#include ([file|virtual])="" part="(label)"\BOLD)\ include only part of a virtual document)

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). (....................................................................) (HTML=

/wasd_root/src/osu/preproc.htmlx

) (HTML/OFF)

(online demonstration) (HTML/ON) (....................................................................)

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

The OSU processor allows for delimited subsections of an (#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 (.HTMLX) documents and if otherwise used may interact unexpectedly with WASD SSI flow-control. (Script-Generated SSI Documents\sect_ssi_script_gen)

It is possible to have script output passed back through the SSI engine for markup. This approach might allow script output to automatically be wrapped in standard site headers and footers for example. Essentially the script must output an SSI-markup response body and include in the otherwise standard CGI response header a field containing "Script-Control: X-content-handler=SSI". The following example in DCL show the essential elements of such a script. $ say = "write sys$output" $ say "Status: 200" $ say "Script-Control: X-content-handler=SSI"" $ say "" $ say "" $ say "" $ say "" $ say "" $ say "" $ say "" $ say "

Example of X-content-handler:SSI

" $ say "Hi there " $ say "" $ say "" $ say "" (--------------------------------------------------------------------) (Document Searching\chapter_searching)

The (query) and (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 (hit).

Only files with a plain-text or HTML MIME data type (see (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.

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 (sect_standard_search_form). (Plain-Text Search\sect_plain_text_search)

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 (hit). The line is not searched for any further occurances.

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. (HTML Search\sect_html_search)

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 (tag) construct is extracted and searched. For example, out of the following HTML fragment

The document entitled "Example Document" provides only an overview of the full capabilities of HTML. only the following text would actually be searched The document entitled "Example Document" provides only an overview of the full capabilities of HTML.

The mechanism for partial document retrieval available with plain-text files is (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.

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. (--------------------------------------------------------------------) (Search Syntax\sect_search_syntax)

A search may be initiated in basic three ways: (NUMBERED) Appending a question-mark and search string to a file specification (the simple syntax of (ISINDEX)-style searching). This is standard HTTP, and of course must conform to HTTP syntax. Providing the name of the query script followed by the directory path to be searched. The script then returns a standard search form. (Forms)-based search, which allows the format and mechanism of the search to be controlled. ((ISINDEX) Search\sect_isindex_search)

Placing the HTML tag (()) 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.

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: /wasd_root/doc/env/*.*?formatted (....................................................................) (HTML=

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.

/wasd_root/doc/env/*.*?formatted

) (HTML/OFF)

(online demonstration) (HTML/ON) (....................................................................) (Standard Search Form\sect_standard_search_form)

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

The following link provides an online demonstration of the standard search form.

/cgi-bin/query/wasd_root/doc/env/

) (HTML/OFF)

(online demonstration) (HTML/ON) (....................................................................)

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. (....................................................................) (HTML=

/cgi-bin/query/wasd_root/doc/env/*.html
/cgi-bin/query/wasd_root/doc/.../
/cgi-bin/query/wasd_root/doc/.../*.html

) (HTML/OFF)

(online demonstration) (HTML/ON) (....................................................................) (Forms-Based Search\sect_forms_based_search)

A (forms-based) search is initiated by the server receiving a file specification, which of course may contain wildcards, followed by a (search) parameter. This is a typical HTML (forms) format URL. For example: *.txt?search=SIMPLE /web/.../*.*?search=THIS sub_directory/*.*?search=THAT ../sibling_directory/*.HTML?search=OTHER (....................................................................) (HTML=

The following link provides an online demonstration search using the form-based syntax.

/wasd_root/doc/env/*.*?search=formatted

) (HTML/OFF)

(online demonstration) (HTML/ON) (....................................................................) (Search Options\sect_search_options)

Additional URI components may be appended after the initial (search=) parameter. These are appended with intervening ((&))) characters. (UNNUMBERED) (Case-Sensitivity. \BOLD) An optional URI component of (case=yes) or (case=no) makes the search case-sensistive or case-insensistive (the default). The following example illustrates the use of this syntax: /web/html/.../*.html?search=Protocol&case=yes /web/html/.../*.html?search=PrOtOcOl&case=no (....................................................................) (HTML=

The following provides an online demonstration using the two links shown above:

• Case-sensistive search for "Protocol"
• Case-insensistive search for "PrOtOcOl"

) (HTML/OFF)

(online demonstration) (HTML/ON) (....................................................................)

(Hits. \BOLD) An optional URI component of (hits=document) or (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: /web/html/.../*.html?search=protocol&hits=document /web/html/.../*.html?search=protocol&hits=line (....................................................................) (HTML=

The following provides an online demonstration using the two links shown above:

• Search result granularity by document.
• Search result granularity by line (the default).

) (HTML/OFF)

(online demonstration) (HTML/ON) (--------------------------------------------------------------------) (Example Search Form\sect_example_search_form)

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

Search HTML documents for: (....................................................................) (HTML=

The following provides an online demonstration of the form used above:

Search HTML documents for: ) (HTML/OFF)

(online demonstration) (HTML/ON) (....................................................................) (Bells and Whistles\sect_bells_and_whistles)

A form providing all the options refered to in (sect_search_options) is shown below (some additional white-space introduced for clarity):

Search HTML documents for:
About this search.
Output By: line document
Case Sensitive: no yes (....................................................................) (HTML=

The following provides an online demonstration of the form used above:

Search HTML documents for:
About this search.
Output By: line document
Case Sensitive: no yes ) (HTML/OFF)

(online demonstration) (HTML/ON) (....................................................................) (--------------------------------------------------------------------) (VMS Help and Text Libraries\chapter_conan)

Affectionately known as (Conan the Librarian), and with all due acknowlegement to Wierd Al.Yankovic (:^), this script makes VMS (Help) and (Text) libraries accessible in the web environment.

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

The following links provide an online demonstration:

• VMS Help
• VMS Help via /CONAN

) (HTML/OFF)

(online demonstration) (HTML/ON) (....................................................................) (Other Librarian Functionality\sect_conan_other)

To obtain an index of matching libraries explicitly activate the (Conan) script providing a wildcard file specification. (All Help libraries in SYS$HELP) (....................................................................) (HTML=

The following link provides an online demonstration:

• All Help libraries in SYS$HELP

) (HTML/OFF)

(online demonstration) (HTML/ON) (....................................................................)

To obtain the library header information add a query string to the library file specification, as shown in the following example: (VMS help library header) (....................................................................) (HTML=

The following link provides an online demonstration:

• VMS help library header

) (HTML/OFF)

(online demonstration) (HTML/ON) (....................................................................) (--------------------------------------------------------------------) (Bookreader Books and Libraries\chapter_hyperreader)

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

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

If the server system supports Bookreader documentation collection the following link will provide an online demonstration: (HTML=

/HyperShelf/

) (HTML/OFF)

(online demonstration) (HTML/ON) (--------------------------------------------------------------------) (Web Document (Upd\BOLD)ate\chapter_web_update)

The (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.

It (should be stressed\BOLD) that this is not designed as a full web administration or authoring tool, and for document preparation relies on the editing capabilities of the (()) 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 TARGET="_blank" HREF="/httpd/-/updhelp.html">current <B>Upd</B>ate documentation</A> for usage detail. <P> Here is <A TARGET="_blank" HREF="/upd/wasd_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 link) <COMMENT>(HTML/ON) <HEAD>(Update Access Permission\sect_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 online 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>(--------------------------------------------------------------------)