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

<FRONT_MATTER>
<TITLE_PAGE>

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

<LINE>

<HEAD>(1st December 1995\head_date)

<P><EMPHASIS>((with minor revisions for freeware release))

<P> Supercedes 19th July 1995, 1st May 1995

<HEAD>(Abstract\head_abstract)

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

<P> It covers the environment supported by the version 3 release of the HFRD 
VMS Hypertext Services (December 1995).

<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> Senior Information Technologist

<P> Mark.Daniel@dsto.defence.gov.au

<P> +61 (8) 2596031 (bus) 
<LINE> +61 (8) 2596673 (fax)

<P> Mark G. Daniel
<LINE> High Frequency Radar Division
<LINE> Defence Science and Technology Organisation
<LINE> PO Box 1500
<LINE> Salisbury
<LINE> South Australia 5108

<HEAD>(Printed Copy\head_printed_copy)

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

<COMMENT>(HTML=
<P> For hypertext browsers a PostScript version of this document is available
 <A HREF="/ht_root/docs/hfrdhyp/hfrdhyp.ps">viewing</A> 
 and for
 <A HREF="/print/ht_root/docs/hfrdhyp/hfrdhyp.ps">printing</A>.
)

<COMMENT>(HTML/OFF)
<P> This book is available for printing to a PostScript printer.  Use a 
hypertext browser to access a print menu in this same location.
<COMMENT>(HTML/ON) 

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

<ENDTITLE_PAGE>

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

<COPYRIGHT_PAGE>

<P> <EMPHASIS>(HFRD VMS Hypertext Services, Copyright (C) 1996 Mark G. 
Daniel.\BOLD) 

<P> This package is free software; you can redistribute it and/or modify it 
under the terms of the GNU General Public License as published by the Free 
Software Foundation; version 2 of the License, or any later version. 

<P> This package is distributed in the hope that it will be useful, but 
WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 
FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more 
details. 

<P> You should have received a copy of the GNU General Public License along 
with this package; if not, write to the Free Software Foundation, Inc., 675 
Mass Ave, Cambridge, MA 02139, USA. 

<ENDCOPYRIGHT_PAGE>

<CONTENTS_FILE>

<ENDFRONT_MATTER>

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

<CHAPTER>(Introduction\chapter_introduction)

<P> This document primarily written for use internal to HFRD and assumes that 
perpsective without apology.  Any additional usage is subordinate to its role 
within HFRD.  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 HFRD. 

<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="/hyperdata/technical/">on-line within HFRD</A>,
)

<COMMENT>(HTML/OFF)
on-line within HFRD,
<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> HFRD 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 HFRD VMS hypertext environment that can be used from within HFRD HTML 
documents.  The HFRD 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 HFRD where it was 
originally written. 

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

<CHAPTER>(HyperText Transport Protocol Daemon\chapter_httpd)

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

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

<LIST>(UNNUMBERED)
<LE> concurrent client support
<LE> file access
<LE> directory listing <EMPHASIS>((generic and VMS-style))
<LE> CGI-compliant scripting
<EMPHASIS>((with configurable, automatic, MIME content-type initiated 
activation))
<LE> HTML pre-processing <EMPHASIS>((server-side includes))
<LE> clickable-image support <EMPHASIS>((NCSA and CERN formats))
<LE> "If-Modified-Since:"/"304 Not Modified" functionality 
<EMPHASIS>((document is only sent if modified since time specified by client)) 
<ENDLIST> 

<HEAD>(Scripts\head_scripts)

<P> The HFRD 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 HFRD 
environment provides a number of scripts for accessing VMS-specific,
DEC-specific and some other HFRD-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. <EMPHASIS>(.TXT\SMALLCAPS))).

<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. 
<EMPHASIS>(;0\SMALLCAPS)), as in this specification 
<EMPHASIS>(/sys$common/syshlp/helplib.hlb;0\SMALLCAPS). 

<P> The current scripts supported by the HFRD hypertext environment include: 

<LIST>(UNNUMBERED)

<LE> Search and Extract (retrieves sections of plain-text documents in 
conjunction with Search) 

<LE> <EMPHASIS>(Conan The Librarian), providing VMS help and text library 
access

<LE> <EMPHASIS>(HyperReader), providing access to Bookreader libraries and 
books

<LE> A <EMPHASIS>(dBASEIV) database query interface

<LE> A crude <EMPHASIS>(WordPerfect) interface

<LE> Print (local printing of documents)

<LE> Teledex (HFRD and DSTOS telephone number lists)

<LE> MX (MadGoat application) mailing-list interface

<ENDLIST>

<P> A specific script can also be explicitly requested in the request URL.  
See subsequent sections describing individual scripts. 

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

<HEAD>(Document Types\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.

<CODE_EXAMPLE>
  .C          C source                    text/plain
  .COM        DCL procedure               text/plain
  .CONF       configuration file          text/plain
  .CPP        C++ source                  text/plain
  .DBF        dBaseIV database            text/html, gateway script activated
  .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
  .MENU       Menu                        text/x-menu
  .MNU        Menu                        text/x-menu
  .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
  .SHT        HyperText Markup Language   pre-processed text/html
  .XBM        X bitmap                    image/x-xbitmap
  .ZIP        zipped file                 application/binary
<ENDCODE_EXAMPLE>

<P> If other file types are required to be defined contact VMS systems 
management. 

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

<HEAD1>(Document Specification\head_document_specification)

<P> 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>
  HYPERDATA:[TECHNICAL.HTML-PRIMER]
<ENDCODE_EXAMPLE>

<CP> would be represented in URL syntax as

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

<CP> and a VMS file specification 

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

<CP> represented as

<CODE_EXAMPLE>
  /hyperdata/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>
  HYPERDATA:[000000]HOME.HTML
<ENDCODE_EXAMPLE>

<CP> should be represented as

<CODE_EXAMPLE>
  /hyperdata/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>
  /hyperdata/committee/minutes/1994/1994-09-27.txt
  /hyperdata/committee/constitution.txt
  /hyperdata/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>

<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
<EMPHASIS>(<LITERAL>(<TITLE>)<LITERAL>(</TITLE>)\SMALLCAPS) 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 hypertext demonstration)
<COMMENT>(HTML/ON)

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

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

<HEAD>(VMS-ish Format\head_directory_vmsish)

<P> The default listing has a <QUOTE>(generic) WWW look about it, however it
can be made to look a little more like the format of the VMS 
<EMPHASIS>(DIRECTORY\SMALLCAPS) 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=<A HREF="*.*;">*.*;</A>)

<COMMENT>(HTML/OFF)
<BOX>(online hypertext 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> <EMPHASIS>(.WWW_HIDDEN\SMALLCAPS) 
<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> <EMPHASIS>(.WWW_NOP\SMALLCAPS) 
<LINE> Any parent directory is not listed.

<LE> <EMPHASIS>(.WWW_NOS\SMALLCAPS) 
<LINE> Any subdirectories are not listed.

<LE> <EMPHASIS>(.WWW_NOPS\SMALLCAPS) 
<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> <EMPHASIS>(.WWW_NOPS\SMALLCAPS)
<LE> <EMPHASIS>(.CANT_BE_SEEN\SMALLCAPS)
<LE> <EMPHASIS>(.HIDDEN_FROM_VIEW\SMALLCAPS)
<LE> <EMPHASIS>(.;1\SMALLCAPS)
<ENDLIST>

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

<HEAD1>(Server Directives\head_directory_directives)

<P> The HFRD server behaviour can be modified using <EMPHASIS>(server 
directives).  For directory listings this involves the inclusion of a query 
string beginning with <EMPHASIS>(?httpd=index\SMALLCAPS).  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&layout=<EMPHASIS>(format)
  ?httpd=index&script=<EMPHASIS>(script-name)
  ?httpd=index&script=<EMPHASIS>(script-name)&readme=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 hypertext demonstration)
<COMMENT>(HTML/ON)

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

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

<HEAD2>(README Files\head_directory_readme)

<P> When a directory listing is generated any <EMPHASIS>(README.\SMALLCAPS),
<EMPHASIS>(README.TXT\SMALLCAPS) or <EMPHASIS>(README.HTML\SMALLCAPS) file (or 
others as configured for the particualr 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>

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

<LIST>(UNNUMBERED)
<LE><EMPHASIS>(C\BOLD) - creation date
<LE><EMPHASIS>(D\BOLD) - description (having no field-width attribute this is 
always best specified last)
<LE><EMPHASIS>(I\BOLD) - icon (takes no field-width attribute)
<LE><EMPHASIS>(L\BOLD) - link (highlighted anchor using the name of the file)
<LE><EMPHASIS>(N\BOLD) - name (no link, why bother? who knows!)
<LE><EMPHASIS>(O\BOLD) - owner (this may be disabled by the server)
<LE><EMPHASIS>(R\BOLD) - revision date
<LE><EMPHASIS>(S\BOLD) - size
<ENDLIST>

<CP> As illustrated in the following examples:

<CODE_EXAMPLE>
  ?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>

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

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

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

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

<HEAD1>(Directory Tree\head_dtree)

<P> The <EMPHASIS>(Dtree\SMALLCAPS) 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 <EMPHASIS>(*.*\SMALLCAPS) 
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="/dtree/ht_root/*.*">/ht_root/</A> tree

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

<COMMENT>(HTML/OFF)
<P><BOX>(online hypertext 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. 

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

<CHAPTER>(HTML Pre-Processing\chapter_shtml)

<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> This concept is also known as <EMPHASIS>(Server Side Includes\BOLD) (SSI). 

<P> The HTML pre-processor is invoked when the document file's extension is 
<EMPHASIS>(.SHTML\SMALLCAPS) (the <QUOTE>(<EMPHASIS>(s\SMALLCAPS)) may have
originated from the SSI nomenclature).  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> 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, but because it is a 
dynamic document loses the advantages of "If-Modified-Since:" processing (see 
<REFERENCE>(chapter_httpd)).

<HEAD>(Directive Syntax\head_preprocessing_syntax)

<P> The syntax follows closely that used by the other implementations, but some 
directives are tailored to the VMS environment.  The directive is enclosed 
within an HTML comment and takes the form: 

<CODE_EXAMPLE>
  <LITERAL>(<)!--#<EMPHASIS>(command\BOLD) [[<EMPHASIS>(tag\BOLD)="<EMPHASIS>(value)"] ...]--<LITERAL>(>)
<ENDCODE_EXAMPLE>

<P> A directive <EMPHASIS>(cannot be split over multiple lines\BOLD).  It must 
all be contained within the one line.  This restriction may be lifted in later 
versions.

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

<HEAD1>(Directive Commands\head_preprocessing_directives)

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

<HEAD2>(ACCESSES\head_shtml_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.  Two tags provide 
additional functionality: 

<LIST>(UNNUMBERED)

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

<ENDLIST>

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

<HEAD2>(CONFIG\head_shtml_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)

<P> This directive, provided in other implementations, <EMPHASIS>(is 
ignored\BOLD) for the HFRD HTTPd.  It controls whether an error message is 
generated upon encountering a pre-processor error.  For the HFRD 
implementation an error is always reported and aborts the processing of 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_shtml_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> <EMPHASIS>(abbrev\SMALLCAPS) (as bytes, kbytes, Mbytes)
<LE> <EMPHASIS>(blocks\SMALLCAPS) (VMS blocks, used)
<LE> <EMPHASIS>(bytes\SMALLCAPS) (e.g. <QUOTE>(1,256,731 bytes))
<ENDLIST>

<ENDLIST>

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

<HEAD2>(DIR\head_shtml_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 HFRD 
HTTPd directory listing (see <REFERENCE>(chapter_directory_listing)).  It is 
an HFRD 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>

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

<HEAD2>(DCL\head_shtml_DCL)

<P> The <EMPHASIS>(dcl) directive executes a DCL command and incorporates the 
output into the processed document.  It is an HFRD 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 <EMPHASIS>(WRITE SYS$OUTPUT\SMALLCAPS) command, using the 
specified parameter. 

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

<COMMENT>(HTML=<P>)

<LE> <EMPHASIS>(SHOW\BOLD)
<P> Execute the DCL <EMPHASIS>(SHOW\SMALLCAPS) 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 <EMPHASIS>(DIRECTORY\SMALLCAPS) command, using the 
supplied file specification.  Qualifiers may be included in the optional
<EMPHASIS>(par\SMALLCAPS) tag to control the format of the listing.

<CODE_EXAMPLE>
  <LITERAL>(<!--#dcl dir="hyperdata:[000000]" -->)
  <LITERAL>(<!--#dcl dir="hyperdata:[000000]" par="/nohead/notrail" -->)
  <LITERAL>(<!--#dcl dir="hyperdata:[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_shtml_echo)

<P> The <EMPHASIS>(echo) directive incorporates the specified information into 
the processed document. 

<LIST>(UNNUMBERED)

<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>(EXEC\head_shtml_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>(FCREATED\head_shtml_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_shtml_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_shtml_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>(INCLUDE\head_shtml_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)
<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
<EMPHASIS>(<LITERAL>(<PRE></PRE>)\SMALLCAPS) 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>

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

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

<HEAD1>(File and Virtual Specifications\head_shtml_file_virtual)

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

<P> The <EMPHASIS>(FILE\SMALLCAPS) tag expects an absolute VMS file
specification.

<P> The <EMPHASIS>(VIRTUAL\SMALLCAPS) 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.

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

<HEAD1>(Time Format\head_shtml_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>(<)!--#date_local fmt="%d/%m/%y" --<LITERAL>(>).
  The time is <LITERAL>(<)!--#date_local fmt="%r" --<LITERAL>(>).
  The day-of-the-week is <LITERAL>(<)!--#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.

<CODE_EXAMPLE>
  Specifier      Replaced by
  ---------      -------------------------------------------------------------

  a              The locale's abbreviated weekday name
 
  A              The locale's full weekday name
 
  b              The locale's abbreviated month name
 
  B              The locale's full month name
 
  c              The locale's appropriate date and time representation
 
  C              The century number (the year divided by 100 and truncated
                 to an integer) as a decimal number (00 - 99)
 
  d              The day of the month as a decimal number (01 - 31)
 
  D              Same as %m/%d/%y
 
  e              The day of the month as a decimal number (1 - 31) in a
                 2 digit field with the leading space character fill
 
  Ec             The locale's alternative date and time representation
 
  EC             The name of the base year (period) in the locale's
                 alternative representation
 
  Ex             The locale's alternative date representation
 
  EX             The locale's alternative time representation
 
  Ey             The offset from the base year (%EC) in the locale's
                 alternative representation
 
  EY             The locale's full alternative year representation
 
  h              Same as %b
 
  H              The hour (24-hour clock) as a decimal number (00 - 23)
 
  I              The hour (12-hour clock) as a decimal number (01 - 12)
 
  j              The day of the year as a decimal number (001 - 366)
 
  m              The month as a decimal number (01 - 12)
 
  M              The minute as a decimal number (00 - 59)
 
  n              The newline character
 
  Od             The day of the month using the locale's alternative
                  numeric symbols
 
  Oe             The date of the month using the locale's alternative
                 numeric symbols
 
  OH             The hour (24-hour clock) using the locale's alternative
                 numeric symbols
 
  OI             The hour (12-hour clock) using the locale's alternative
                 numeric symbols
 
  Om             The month using the locale's alternative numeric symbols
 
  OM             The minutes using the locale's alternative numeric symbols
 
  OS             The seconds using the locale's alternative numeric symbols
 
  Ou             The weekday as a number in the locale's alternative
                 representation (Monday=1)
 
  OU             The week number of the year (Sunday as the first day of the
                 week) using the locale's alternative numeric symbols
 
  OV             The week number of the year (Monday as the first day of the
                 week) as a decimal number (01 -53) using the locale's
                 alterntative 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.
 
  %              %
<ENDCODE_EXAMPLE>

<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 
<EMPHASIS>(<LITERAL>(<IMG...>)\SMALLCAPS) tag, the <EMPHASIS>(HREF=\SMALLCAPS) 
specifies the path to the image configuration file

<LE> specify <EMPHASIS>(ISMAP\SMALLCAPS) in the 
<EMPHASIS>(<LITERAL>(<IMG...>)\SMALLCAPS) 
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 
<EMPHASIS>(XV\SMALLCAPS) 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> Here are two examples, essentially just removed fom their original 
CERN environment and placed within HFRD's, with links allowing the respective 
configuration files to be viewed. 

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

<COMMENT>(HTML=
<UL>
<LI> <A HREF="demo.html">demo.html</A>
<P> <A HREF="demo*.ismap;0">index of configuration files</A>
)

<COMMENT>(HTML/OFF)
<P><BOX>(online hypertext demonstration)
<P><BOX>(online hypertext link)
<P><BOX>(online hypertext demonstration)
<P><BOX>(online hypertext link)
<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). 

<NOTE>
Searching is a notoriously CPU and I/O intensive activity.  Longer searches 
progressively decrease scheduling priority by one every 10 seconds, from 
normal to zero, helping to reduce impact on any interactive users of the 
server system.  The search algorithm itself is efficient, but searching will 
take longer on a more heavily loaded system because of this mechanism. 
<ENDNOTE> 

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

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

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

<HEAD1>(Search Syntax\head_search_syntax)

<P> A search may be initiated in one of two ways:

<LIST>(NUMBERED)

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

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

<ENDLIST>

<HEAD2>(<EMPHASIS>(ISINDEX\SMALLCAPS) Search\head_isindex_search)

<P> Placing the HTML tag <EMPHASIS>(<LITERAL>(<ISINDEX>)\SMALLCAPS) 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>
  /hyperdata/html/html-primer/*.html?problem
<ENDCODE_EXAMPLE>

<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
   /hyperdata/.../*.*?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.  It searches 
all files (plain-text and HTML) in the current directory for the keyword 
"formatted".  Note the difference in the way plain-text file hits are 
presented compared with those of HTML files. 

<P>
<A HREF="*.*?search=formatted">Search for "formatted"</A>
) 

<COMMENT>(HTML/OFF)
<P><BOX>(online hypertext 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>(&) 
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>
  /hyperdata/html/.../*.html?search=Protocol&case=yes
  /hyperdata/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 hypertext 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>
  /hyperdata/html/.../*.html?search=protocol&hits=document
  /hyperdata/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 hypertext demonstration)
<COMMENT>(HTML/ON)

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

<P>
<LE> <EMPHASIS>(About.  \BOLD) An optional URI component of 
<QUOTE>(about=search) provide the user with information about the search 
itself, how it works what the options mean. 

<CODE_EXAMPLE>
  /hyperdata/?about=search
<ENDCODE_EXAMPLE>

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

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

<P> <A HREF="?about=search">About this search.</A>
)

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

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

<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="/hyperdata/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 hypertext 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="/hyperdata/html/.../*.html">

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

  <BR><TT><A HREF="/hyperdata/?about=search">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="?about=search">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 hypertext 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 <EMPHASIS>(:^<CPAREN>\SMALLCAPS), 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 <EMPHASIS>(.HLB\SMALLCAPS) or <EMPHASIS>(.TLB\SMALLCAPS).  
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 hypertext 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 hypertext 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 hypertext 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 HFRD 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 <EMPHASIS>(.DECW$BOOK\SMALLCAPS) and 
<EMPHASIS>(.DECW$BOOKSHELF\SMALLCAPS) respectively.  Alternatively, the 
respective scripts may be explicitly specified (but the ability to provide a 
relative specification is lost).  The following examples illustrate the 
syntax: 

<CODE_EXAMPLE>
  <LITERAL>(<A HREF="hfrdhyp.decw$book">This document from Bookreader</A>)
  <LITERAL>(<A HREF="hfrdhyp.decw$bookshelf">The shelf DEC Document creates for this</A>)

  <LITERAL>(<A HREF="/HyperReader/ht_root/docs/hfrdhyp/hfrdhyp.decw$book">
    This document from Bookreader</A>)
  <LITERAL>(<A HREF="/HyperShelf/ht_root/docs/hfrdhyp/hfrdhyp.decw$bookshelf">
    The shelf DEC Document creates for this document</A>)
<ENDCODE_EXAMPLE>

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

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

<UL>
<LI> <A HREF="hfrdhyp.decw$book">This document from Bookreader</A>
<LI> <A HREF="hfrdhyp.decw$bookshelf">The shelf DEC Document creates for this document</A>
<LI> <A HREF="/HyperReader/ht_root/docs/hfrdhyp/hfrdhyp.decw$book">This document from Bookreader</A>
<LI> <A HREF="/HyperShelf/ht_root/docs/hfrdhyp/hfrdhyp.decw$bookshelf">The shelf DEC Document creates for this document</A>
</UL>
) 

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

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

<CHAPTER>(dBASEIV Query Interface\chapter_dbaseiv)

<P> The <EMPHASIS>(dBASEIV\SMALLCAPS) script provides query access to VMS-based
dBASEIV databases.

<P> The user can, by <EMPHASIS>(radio button), select to generate a report in a 
fixed-font format (the default), or using native HTML tables (supported by
<EMPHASIS>(Netscape v1.n), but not supported by <EMPHASIS>(Mosaic v2.4), the
current VMS browser). 

<P> Another set of <EMPHASIS>(radio buttons) allow selection of the report
layout as a <EMPHASIS>(table) (the default), where fields are columnated, or as
a <EMPHASIS>(listing), where fields are presented sequentially. 

<P> Parameters for the query are presented using a combination of
<EMPHASIS>(checkboxes) and/or <EMPHASIS>(text entry boxes) against one, more,
or all of the fields in a database.  The <EMPHASIS>(checkboxes) allow the
inclusion of that field in a report.  The <EMPHASIS>(text entry boxes) allow
the specification of <EMPHASIS>(query strings), and provide the ability to
selectively report on records of a database depending on the contents of the
fields. 

<P> A <EMPHASIS>(Submit Query) button allows the completed query form to be
sent to the server, and the report generated and returned to the user.

<HEAD>(Query Strings\head_dbaseiv_query)

<P> A query string allows a field to be selected based on a wildcard match. 
Wildcards supported are the <QUOTE>(*) and <QUOTE>(%).  For fields containing
numeric values selection can be based on arithmetic comparisions.

<HEAD>(Query Form Builder\head_dbaseiv_builder)

<P> To assist in building query interfaces for specific databases the
<EMPHASIS>(dBASEIV\SMALLCAPS) script will provide a form allowing the
specification of the fields to be queried and/or displayed, and then build and
return a custom hypertext form to do just that.  This form can then be saved
for use from, or inclusion in, another document.

<HEAD>(Online Demonstrations\head_dbaseiv_example)

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

<COMMENT>(HTML=
<P> This link provides access to the 
<A HREF="/dbiv?do=help">online help</A>.

<P> This link provides access to a basic
<A HREF="/dbiv">online demonstration</A>.
) 

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

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

<CHAPTER>(Document Printing\chapter_hprints)

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

<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/docs/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/docs/hfrdhyp/hfrdhyp.ps">Print this document.</A>
)

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

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

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

<CHAPTER>(PostMail Script\chapter_postmail)

<P> The <EMPHASIS>(Postmail\SMALLCAPS) script allows an HTML forms-based mail
message to be generated and sent.  It relies on authentication of a user with
an HFRD account.  The message originates from the authenticated username.

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

<COMMENT>(HTML=
<P> The script can provide its own <A HREF="/PostMail?help=please">help</A>.
)

<COMMENT>(HTML/OFF)
<P> The script can provide its own help.
<P><BOX>(online hypertext link)
<COMMENT>(HTML/ON)

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

<P> The HTTP GET method is used to request a message generation form.  The 
following URL form field names may be used to control the format of, and/or 
provide default values for, the message generation form.  The URL must of 
course conform to URL specification rules and have escaped characters where 
necessary.

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

<COMMENT>(HTML=
<P> The following link provides access to an
<A HREF="/ht_root/PostMail/demos.html">online demonstration</A>
of the various formats available:
) 

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

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

<LIST>(UNNUMBERED)

<LE> <EMPHASIS>(to\BOLD)
<LINE> Specifies the default destination address(es).

<LE> <EMPHASIS>(list\BOLD)
<LINE> Specifies the URL-style location of a file comprising a distribution list. 
If <EMPHASIS>(to\SMALLCAPS) is null it generates a selection box, if <QUOTE>(*)
(an asterisk) defaults to all in list.

<LE> <EMPHASIS>(subject\BOLD)
<LINE> Specifies the default subject field.

<LE> <EMPHASIS>(body\BOLD)
<LINE> Specifies the default message body.

<LE> <EMPHASIS>(message\BOLD)
<LINE> Specifies the URL-style location of a file comprising the default message
body.

<LE> <EMPHASIS>(fixed\BOLD)
<LINE> If this field is non-null it <EMPHASIS>(fixes) any defaults supplied so
that they cannot be changed.

<LE> <EMPHASIS>(TextArea\BOLD)
<LINE> Allows the specification of the message body text area window size, in
columns by rows (e.g. <QUOTE>(80x24)).

<ENDLIST>

<P> The HTTP POST method is used to send a message.  This is handled by the
message generation form and is not of operational concern.

<HEAD1>(Usage Similar to <EMPHASIS>(mailto:\SMALLCAPS)\head_postmail_mailto)

<P> The PostMail script may be used in a similar fashion to the
<EMPHASIS>(mailto:) URL.

<LIST>(UNNUMBERED)

<LE> <EMPHASIS>(mailto\BOLD)
<LINE> Any fields in a form following this field name will be mailed to the
destination in URL-escaped format.

<LE> <EMPHASIS>(deform\BOLD)
<LINE> Any fields in a form following this field name will be mailed to the
destination in <EMPHASIS>(deformed) format, that is, processed for easy
reading.  Each form field name occurs on a line by itself, terminated by a
full-colon.  The value of the field occurs immediately below it.  Multi-line
field values (such as <EMPHASIS>(textarea\SMALLCAPS)) appear as multiple lines. 
Where a blank line was input that line is replaced with a line containing a
single period.  Each field name and value pair is separated from the next with
a blank line.

<ENDLIST>

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

<COMMENT>(HTML=
<P> The following example demonstrates usage of the <TT>deform</TT> field name. 
Use your browser's "<I>(View source ...)</I>" facility to examine the underlying
HTML.

<FORM METHOD=POST ACTION="/PostMail">
<P>Demonstration message destination:
<BR>
<INPUT TYPE=text NAME=to SIZE=48>
<INPUT TYPE=hidden NAME=subject VALUE="Demonstration of DEFORM Field">
<!-- NOTE: everything following the deform field will be the message body -->
<INPUT TYPE=hidden NAME=deform>
<P> ay <INPUT TYPE=checkbox NAME=one VALUE="ay checked" CHECKED>
bee <INPUT TYPE=checkbox NAME=two VALUE="bee checked">
see <INPUT TYPE=checkbox NAME=three VALUE="see checked">
<P> one <INPUT TYPE=radio NAME=radio-box VALUE="one selected" CHECKED>
two <INPUT TYPE=radio NAME=radio-box VALUE="two selected">
three <INPUT TYPE=radio NAME=radio-box VALUE="three selected">
<P> Multi-line message area:
<BR>
<INPUT TYPE=textarea NAME=text-area ROWS=4 COLS=48>
<P> <INPUT TYPE=submit VALUE="mail form">
<INPUT TYPE=reset VALUE="reset all fields">
</FORM>
) 

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

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

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

<CHAPTER>(Menus\chapter_menus)

<P> To allow easy management of information by users not needing to explore 
the complexities of HTML (HyperText Markup Language) a simple menuing system 
is provided, allowing versatile document access and searching.  A plain-text 
file is interpreted by the server, providing a uniform and functional menu to 
the client.  This plain-text file may be edited on any platform (PC, VMS, 
Unix) and then just placed into the data area. 

<P> A menu is distinguished from other files by its type extension, 
<EMPHASIS>(.MENU\SMALLCAPS) (or <EMPHASIS>(.MNU\SMALLCAPS) for <QUOTE>(8.3) 
MS-DOS compliance). 

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

<COMMENT>(HTML=
<P> The 
 <A HREF="/ht_root/docs/hfrd_primer/hfrd_primer_0000.html">
 "HFRD Hypertext Management Primer"</A>
 provides a complete description on the use of menus.
) 

<COMMENT>(HTML/OFF)
<P> The <QUOTE>(HFRD Hypertext Management Primer) provides a complete 
description on the use of menus. 
<P><BOX>(online document available).
<COMMENT>(HTML/ON) 

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

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

