 

















                                        WASD Hypertext Services
                                        - Environment Overview



                   21st June 1998

                   Supercedes:

                      1st March 1998
                      2nd November 1997
                      17th August 1997
                      1st June 1997,
                      17th May 1996 (initial freeware release),
                      19th July 1995,
                      1st May 1995,
                      1st December 1994

                   Please Note

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

                   Abstract

                   This document is a guide to supporting hypertext
                   documentation within the WASD Hypertext Services
                   environment. It is not a tutorial on writing HTML
                   documents.

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

                   It is strongly suggested those using printed versions
                   of this document also access the hypertext version. It
                   provides online demonstrations of some concepts.

 






                   Author

                   Mark G. Daniel
                   Senior Information Technology Officer
                   Wide Area Surveillance Division
                   Defence Science and Technology Organisation

                   Mark.Daniel@dsto.defence.gov.au

                   +61 (8) 82596031 (bus)
                   +61 (8) 82596673 (fax)

                   PO Box 1500
                   Salisbury
                   South Australia 5108

                   Printed Copy

                   This book is available for printing to a PostScript
                   printer. Use a hypertext browser to access a print
                   menu in this same location.





























            ii

 






                   WASD VMS Hypertext Services

                   Copyright  1996-1998 Mark G. Daniel.

                   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.

                   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.

                   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.

                   Eric A. Young

                   This package can include cryptographic software
                   (SSLeay) copyright by Eric Young (eric@CryptSoft.com):

                      This library is free for commercial and non-commercial use provided ...
                      Eric Young should be given attribution as the author ...
                      copyright notice is retained

                   MadGoat Software

                   For supporting non-Digital-TCP/IP (UCX) this software
                   uses the NETLIB package by Matthew Madison:

                      permission is granted to copy and redistribute ...
                      for no commercial gain

                   Ohio State University

                   This package contains software provided with the OSU
                   (DECthreads) HTTP server package, authored by David
                   Jones:

                      Copyright 1994,1997 The Ohio State University.
                      The Ohio State University will not assert copyright with respect
                      to reproduction, distribution, performance and/or modification
                      of this program by any person or entity that ensures that all
                      copies made, controlled or distributed by or for him or it bear
                      appropriate acknowlegement of the developers of this program.

                                                                           iii

 






                   RSA Data Security

                   This software contains code derived in part from RSA
                   Data Security, Inc:

                      permission granted to make and use derivative works provided that such
                      works are identified as "derived from the RSA Data Security, Inc.
                      MD5 Message-Digest Algorithm" in all material mentioning or referencing
                      the derived work.

                   Bailey Brown Jr.

                   LZW compression is implemented using code derived in
                   part from the PBM suite. This code is copyright by the
                   original author:

                      * GIF Image compression - LZW algorithm implemented with Tree type
                      *                         structure.
                      *                         Written by Bailey Brown, Jr.
                      *                         last change May 24, 1990
                      *                         file: compgif.c
                      *
                      *  You may use or modify this code as you wish, as long as you mention
                      *  my name in your documentation.

                   Other

                   OpenVMS, Digital TCP/IP Services for OpenVMS, VAX C,
                   DEC C, VAX and AXP
                   are registered trademarks of Digital Equipment
                   Corporation.

                   MultiNet is a registered trademark of Cisco Systems,
                   Inc.

                   Pathway is a registered trademark of Attachmate, Inc.

                   TCPware is a registered trademark of Process Software
                   Corporation.











            iv

 









               Contents_________________________________________________________

               Chapter_1__Introduction__________________________________________



               Chapter_2__HyperText_Transport_Protocol_Daemon___________________

               2.1    Auto-Scripting.........................................2-2


               Chapter_3__Document_Access_and_Specification_____________________

               3.1    Document Content Type..................................3-1

               3.2    Explicitly Specifying Content-Type.....................3-2

               3.3    Document Specification.................................3-3

                      3.3.1     Absolute File Path...........................3-4

                      3.3.2     Partial (or Relative) File Path..............3-4

               Chapter_4__Directory_Listing_____________________________________

               4.1    Controlling Access To A Directory......................4-2

               4.2    "Hidden" Files.........................................4-3

               4.3    Server Directives......................................4-3

                      4.3.1     Layout.......................................4-3

                      4.3.2     Readme Files.................................4-4

                      4.3.3     Listing Delimiters...........................4-5

                      4.3.4     Suppressing Directories......................4-5

                      4.3.5     Listing Refresh and Expiry...................4-6

                      4.3.6     Scripting From Directory Listings............4-6

                      4.3.7     Auto-Scripting...............................4-6

                      4.3.8     Specifying Content-Type......................4-6

               4.4    Directory Tree.........................................4-7

               Chapter_5__Server_Side_Includes_(SSI)____________________________

               5.1    Pre-Expiring Documents.................................5-2

               5.2    Directive Syntax.......................................5-2

               5.3    Directive Commands.....................................5-3

                      5.3.1     #ACCESSES....................................5-3

                      5.3.2     #CONFIG......................................5-3

                      5.3.3     #DIR.........................................5-4

                                              iii

 






                   5.3.4     #DCL.........................................5-5

                   5.3.5     #ECHO........................................5-6

                   5.3.6     #ELIF........................................5-7

                   5.3.7     #ELSE........................................5-7

                   5.3.8     #ENDIF.......................................5-7

                   5.3.9     #EXEC........................................5-7

                   5.3.10    #FCREATED....................................5-8

                   5.3.11    #FLASTMOD....................................5-8

                   5.3.12    #FSIZE.......................................5-8

                   5.3.13    #IF..........................................5-9

                   5.3.14    #INCLUDE.....................................5-9

                   5.3.15    #ORIF.......................................5-10

                   5.3.16    #PRINTENV...................................5-10

                   5.3.17    #SET........................................5-10

                   5.3.18    #SSI........................................5-11

                   5.3.19    #STOP.......................................5-11

                   5.3.20    #TRACE......................................5-11

            5.4    Variables.............................................5-12

            5.5    Flow Control..........................................5-14

            5.6    Query Strings.........................................5-15

            5.7    File and Virtual Specifications.......................5-16

            5.8    Time Format...........................................5-16

            Chapter_6__Clickable_Image_Support_______________________________

            6.1    Image Configuration File...............................6-1

            6.2    Examples...............................................6-3

            Chapter_7__Document_Searching____________________________________

            7.1    Plain-Text Search......................................7-1

            7.2    HTML Search............................................7-1

            7.3    Search Syntax..........................................7-2

                   7.3.1     "ISINDEX" Search.............................7-2

                   7.3.2     Forms-Based Search...........................7-2

                   7.3.3     Search Options...............................7-3

                   7.3.4     Example Search Form..........................7-3

                                            iv

 






            Chapter_8__VMS_Help_and_Text_Libraries___________________________



            Chapter_9__Bookreader_Books_and_Libraries________________________


            Chapter_10__Web_Document_Update__________________________________



            Chapter_11__dBASEIV_Query_Interface______________________________



            Chapter_12__Document_Printing____________________________________


            Chapter_13__Menus________________________________________________































                                             v

 








            Chapter__1_______________________________________________________

            Introduction


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

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

               The document assumes a basic understanding of hypertext
               technologies and uses some terms without explaining them
               (e.g. HTTP, HTML, URL, CGI, etc.) It is not a tutorial on
               writing HTML documents. The reader is refered to documents
               specifically on these topics (some are available on-line
               within WASD, but are often best consulted from the Internet
               WWW).

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

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

               It is strongly suggested those using printed versions of this
               document also access the Hypertext version. It provides online
               demonstrations of some concepts.

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

                                                             Introduction  1-1

 








            Chapter__2_______________________________________________________

            HyperText Transport Protocol Daemon


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

               The WASD version provides a complete implementation of a basic
               HTTP server, including:

               o  concurrent, multi-threaded client support

               o  "DELETE", "GET", "HEAD", "POST" and "PUT" HTTP method
                  support

               o  "If-Modified-Since:" / "304 Not Modified" functionality
                  (document is only sent if modified since time specified by
                  client)

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

               o  versatile directory listing (generic and VMS-style)

               o  CGI-compliant scripting (with configurable, automatic, MIME
                  content-type initiated activation)

               o  CGIplus scripting (offering reduced latency, increased
                  throughput and reduced system impact when scripting)

               o  script processor (e.g. PERL) configurable on file type
                  (extension)

               o  Server-Side Includes (HTML pre-processing)

               o  configurable cache, with automatic, time-based and forced
                  re-validation (reload)

               o  clickable-image support (both NCSA and CERN formats)

               o  smart rule mapping (conditional rules)

               o  "Basic" and "Digest" user authentication and path/group-
                  based authorization

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

                                      HyperText Transport Protocol Daemon  2-1

 






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

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

               o  host-level access control, on per-host or per-domain
                  acceptance or rejection

               o  single server can support multi-homed (host name) and
                  multiple port services

               o  on-line server configuration, including reports on re-
                  quests, loaded configuration, mapping rules, authorization
                  information and graphical activity displays

               o  cookie support ("Cookie:" HTTP header field)

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

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

               Scripts

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

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

            2.1 Auto-Scripting

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

               This auto-scripting can occur whenever the document speci-
               fication 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 save as dialog). A simple way
               of suppressing the auto-scripting facility is to include a

            2-2  HyperText Transport Protocol Daemon

 






               latest-version number (i.e. ";0"), as in this specification
               "/sys$common/syshlp/helplib.hlb;0".

               The current scripts supported by the WASD hypertext environ-
               ment include:

               o  Search and Extract (retrieves sections of plain-text
                  documents in conjunction with Search)

               o  Conan The Librarian, providing VMS help and text library
                  access

               o  HyperReader, providing access to Bookreader libraries and
                  books

               o  A dBASEIV database query interface

               o  A crude WordPerfect interface

               o  Print (local printing of documents)

               o  MX (MadGoat application) mailing-list interface

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
























                                      HyperText Transport Protocol Daemon  2-3

 








            Chapter__3_______________________________________________________

            Document Access and Specification


               Arbitrary documents may not be accessed.

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

               Documents must be read-accessable.

               The server can only access files that are world readable,
               or that have an ACL specifically controlling access for
               "HTTP$SERVER", the server account.

            3.1 Document Content Type

               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 Section 2.1). The file type
               (extension) determines the content type by which the server
               returns (and/or interprets) the file.

               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.












                                        Document Access and Specification  3-1

 






                  .BKB        Bookreader document (BNU)   text/html, gateway script activated
                  .BKS        Bookreader shelf (BNU)      text/html, gateway script activated
                  .C          C source                    text/plain
                  .COM        DCL procedure               text/plain
                  .CONF       configuration file          text/plain
                  .CPP        C++ source                  text/plain
                  .DECW$BOOK  Bookreader document         text/html, gateway script activated
                  .FOR        Fortran source              text/plain
                  .GIF        GIF image                   image/gif
                  .H          C header                    text/plain
                  .HLB        VMS Help library            text/html, gateway script activated
                  .HTML       HyperText Markup Language   text/html
                  .HTM        HyperText Markup Language   text/html
                  .JPG        JPEG image                  image/jpeg
                  .LIS        Listing                     text/plain
                  .MAR        Macro source                text/plain
                  .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

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

            3.2 Explicitly Specifying 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.

               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.

            3-2  Document Access and Specification

 






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

                  ?httpd=content&type=text/plain

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

                  ?httpd=content&type=application/octet-stream

               This is an example:

               <online hypertext demonstration>

               It is also posssible to "force" the content-type for all files
               in a particular directory. See Section 4.3.8.

            3.3 Document Specification

               For the "http:" protocol, file and directory locations are
               specified using URL path syntax where slash-separated ("/")
               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.

               A VMS directory specification

                  WEB:[TECHNICAL.HTML-PRIMER]

               would be represented in URL syntax as

                  /web/technical/html-primer/

               and a VMS file specification

                  WEB:[TECHNICAL.HTML-PRIMER]HTML-PRIMER.HTML

               represented as

                  /web/technical/html-primer/html-primer.html

                                             Note

                     It is not required (although not forbidden) to
                     supply a VMS master file directory component
                     ("[000000]", "[000000.", etc.) in a URL specifi-
                     cation. Hence the file specification

                       WEB:[000000]HOME.HTML

                     should be represented as

                       /web/home.html

                                        Document Access and Specification  3-3

 






            3.3.1 Absolute File Path

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

                  /web/committee/minutes/1994/1994-09-27.txt
                  /web/committee/constitution.txt
                  /web/committee/membership/fred-bloggs.txt

            3.3.2 Partial (or Relative) File Path

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

               A file may be specified 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 never begin with forward-slash
               ("/").

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

                  1994-07-22.txt
                  1994-08-24.txt
                  1994-09-27.txt

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

                  1993/1993-02-17.txt
                  1993/reports/membership.txt
                  other/etc.txt

               Documents in a related part of the hierarchy may be referenced
               using the "../" construct. As with MS-DOS and Unix this syntax
               indicates the immediately superior directory.

                  ../other_committee/1993/1993-02-17.txt
                  ../other_committee/1993/reports/balance-sheet.txt
                  ../../other_section/committee/constitution.txt






            3-4  Document Access and Specification

 








            Chapter__4_______________________________________________________

            Directory Listing


               A directory listing is sometimes refered to as a document
               Index, and is generally titled "Index of . . . ".

               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.

               All specifications must be made using URL-style paths. See
               Section 3.3.

               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:

               o  iconic indication of the data type

               o  file name

               o  last revison date/time

               o  size

               o  description

               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 "<TITLE></TITLE>" element.

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

               The following link illustrates the directory listing format:

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

               <online hypertext demonstration>

                                                        Directory Listing  4-1

 






               VMS-ish Format

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

            4.1 Controlling Access To A Directory

               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.

               o  ".WWW_HIDDEN"
                  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.

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

               o  ".WWW_NOP"
                  Any parent directory is not listed.

               o  ".WWW_NOS"
                  Any subdirectories are not listed.

               o  ".WWW_NOPS"
                  Any parent directory or subdirectories are not listed.







            4-2  Directory Listing

 






            4.2 "Hidden" Files

               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:

               o  ".WWW_NOPS"

               o  ".CANT_BE_SEEN"

               o  ".HIDDEN_FROM_VIEW"

               o  ".;1"

            4.3 Server Directives

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

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

                  ?httpd=index&autoscript=no
                  ?httpd=index&readme=no
                  ?httpd=index&type=text/plain
                  ?httpd=index&layout=format
                  ?httpd=index&script=script-name
                  ?httpd=index&script=script-name&readme=no
                  ?httpd=index&delimit=none&readme=no&nos=yes

            4.3.1 Layout

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

               o  C - creation date

               o  D - description (often best specified last)

                  o  D:L - for files, make a link out of the description text

               o  I - icon (takes no field-width attribute)

                                                        Directory Listing  4-3

 






               o  L - link (highlighted anchor using the name of the file)

               o  N - name (no link, why bother? who knows!)

               o  O - owner (can be disabled)

               o  R - revision date

               o  S - size

                  o  S:B - in bytes (comma-formatted)

                  o  S:D - decimal kilos (see below)

                  o  S:F - kilo and mega are displayed to one decimal place

                  o  S:K - in kilo-bytes (and fractions thereof)

                  o  S:M - in mega-bytes (and fractions thereof)

               o  U - upper-case file and directory names (must be the first
                  character)

               The default layout is:

                  I__L__R__S__D

               The following provide other examples:

                  ?httpd=index&layout=UI__L__R__S__D
                  ?httpd=index&layout=I__L__R__S:b__D
                  ?httpd=index&layout=I__L__R__S__D
                  ?httpd=index&layout=I__15L__S__D
                  ?httpd=index&layout=15L__9R__S
                  ?httpd=index&layout=15N_9C_9R_S

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

                  ?httpd=index&layout=I__L__R__S:d__D

               If unsure of the kilo value being used check the "<META>"
               information in the directory listing.

               <online hypertext demonstration>

            4.3.2 Readme Files

               When a directory listing is generated any "README.",
               "README.TXT" or "README.HTML" file (or others as configured
               for the particular server) in the directory will have
               its contents displayed immediately below the title of the
               page. This allows additional information on the directory's
               contents, function, etc., to be presented. This can be

            4-4  Directory Listing

 






               suppressed by appending the following query-string to the
               directory specification, as in the accompanying example:

                  ?httpd=index&readme=no

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

               Read-me files can be SSI documents if configured by the server
               administrator. General SSI guidelines apply to these, see
               Chapter 5

            4.3.3 Listing Delimiters

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

               o  header -  a header comprising a horizontal rule and column
                  heading is generated

               o  footer -  a footer comprising a horizontal rule is
                  generated

               o  none -  no header or footer is generated

               o  both -  both header and footer is generated (default)

                  ?httpd=index&delimit=none

                  ?httpd=index&delimit=top

            4.3.4 Suppressing Directories

               Parent and subdirectories may be suppressed in a listing using
               the "nop", "nops" and "nos" directives. These parallel the
               purpose of the directory listing control files described in
               Section 4.1, and if set to true suppress the listing of the
               corresponding directories.

               o  nop -  any parent directory is not listed

               o  nops -  any subdirectories are not listed

               o  nos -  any parent directory or subdirectories are not
                  listed

                  ?httpd=index&nop=yes

                  ?httpd=index&nops=yes

                  ?httpd=index&nos=yes

                                                        Directory Listing  4-5

 






            4.3.5 Listing Refresh and Expiry

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

                  /dir1/dir2/*.*?httpd=index?expired=yes
                  /dir1/dir2/*.*?httpd=index?expired=no
                  /tree/dir1/dir2/?httpd=index?expired=yes
                  /tree/dir1/dir2/?httpd=index?expired=no

            4.3.6 Scripting From Directory Listings

               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.

                  ?httpd=index&script=script_name

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

               <online hypertext demonstration>

            4.3.7 Auto-Scripting

               The server's auto-scripting facility (see Section 2.1) can
               be suppressed by appending the following query-string to the
               directory specification, as in the accompanying example:

                  ?httpd=index&autoscript=no

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

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

            4.3.8 Specifying 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 Section 3.2.

            4-6  Directory Listing

 






               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:

               <online hypertext demonstration>

            4.4 Directory Tree

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

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

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

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

               <online hypertext demonstration>

                                                        Directory Listing  4-7

 






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

                                             Note

                     The "tree" internal script supercededs the "Dtree"
                     external script which has been retired.











































            4-8  Directory Listing

 








            Chapter__5_______________________________________________________

            Server Side Includes (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 Section 5.5. These extensions
               allow quite versatile documents to be created without
               resorting to script processing.

               Two documents are provided as examples of SSI processing.

               o  A simple SSI document.

                  HT_ROOT:[DOC.ENV]SSI.SHTML <online hypertext demonstration>

               o  An SSI document using variable assignment and flow-control.

                  HT_ROOT:[DOC.ENV]SSI.SHTML <online hypertext demonstration>

               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.

               Virtual Documents

               One effective use for pre-processed HTML is the creation of
               single virtual documents from two or more physical documents.
               That is, the pre-processed document is used to include
               multiple physical documents, that may even be independently
               administered, to return a composite document to the client.
               This is a relatively low-overhead activity, but because it
               is a dynamic document loses the advantages of "If-Modified-
               Since:" processing (see Chapter 2).




                                               Server Side Includes (SSI)  5-1

 






            5.1 Pre-Expiring Documents

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

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

                  <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
                  <HTML>
                  <HEAD>
                  <META HTTP-EQUIV="expires" CONTENT="Thu, 01-Jan-1970, 00:00:01 GMT">
                  <TITLE> etc. </TITLE>
                  </HEAD>
                  <BODY>
                     etc.
                  </BODY>
                  </HEAD>

            5.2 Directive Syntax

               The syntax follows closely that used by the other implemen-
               tations, but some directives are tailored to the WASD and VMS
               environment. The directive is enclosed within an HTML comment
               and takes the form:

                  <!--#directive [[tag1="value"] [tag2="value"] ...] -->

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

               A directive can be split over multiple lines provided the new
               line begins naturally on white-space within the directive. For
               example, this is correctly split

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

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

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

            5-2  Server Side Includes (SSI)

 






               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.


            5.3 Directive Commands

            5.3.1 #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:

               o  ORDINAL

                     <!--#accesses ordinal -->

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

               o  SINCE

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

               o  TIMEFMT

                     <!--#accesses since="text" timefmt="[time-format]" -->

                  Allows the time format of the since tag to be supplied,
                  where time-format is specified according to Section 5.8.

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

               o  ERRMSG

                                               Server Side Includes (SSI)  5-3

 






                  This directive, provided in other implementations, is
                  ignored for the WASD HTTPd. It controls whether an error
                  message is generated upon encountering a pre-processor
                  error. For the WASD implementation an error is always
                  reported and aborts the processing of the document.

               o  TIMEFMT

                     <!--#config timefmt="time-format" -->

                  Where time-format is specified according to Section 5.8.

               o  SIZEFMT

                     <!--#config sizefmt="size-format" -->

                  Where size-format is specified using the following
                  keywords:

                  o  "abbrev" (as bytes, kbytes, Mbytes)

                  o  "blocks" (VMS blocks, used)

                  o  "bytes" (e.g. "1,256,731 bytes")

            5.3.3 #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 4), 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.

               o  FILE

                  Listing specified using a VMS file path.

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

               o  VIRTUAL

                  Listing specified using URL-style syntax.

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

               For example:

                  <!--#dir /ht_root/src/httpd/" -->

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

            5-4  Server Side Includes (SSI)

 






            5.3.4 #DCL

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

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

                  type="text/html"

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

               o  SAY

                  Execute the DCL "WRITE SYS$OUTPUT" command, using the
                  specified parameter.

                     <!--#dcl say="hello." -->

               o  SHOW

                  Execute the DCL "SHOW" command, using the specified
                  parameter.

                     <!--#dcl show="device/full tape1:" -->

               o  DIR

                  Execute the DCL "DIRECTORY" command, using the supplied
                  file specification. Qualifiers may be included in the
                  optional "par" tag to control the format of the listing.

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

               o  EXEC (privileged)

                  Execute the specified DCL command.

                     <!--#dcl exec="show device/full tape1:" -->

               o  FILE (privileged)

                                               Server Side Includes (SSI)  5-5

 






                  Execute the DCL command procedure specified as a VMS
                  file path, with any specified parameters applied to the
                  procedure.

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

               o  VIRTUAL (privileged)

                  Execute the DCL command procedure specified in URL-style
                  syntax, with any specified parameters applied to the
                  procedure.

                     <!--#dcl virtual="../shtml/test.com" par="PARAM1 PARAM2" -->

            5.3.5 #ECHO

               The #echo directive incorporates the specified information
               into the processed document. Multiple tags may be used within
               the one directive.

               o  VALUE=
                  VAR=

                  Any SSI variable (e.g. CREATED), CGI variable (e.g. HTTP_
                  USER_AGENT), or document assigned variable (e.g. EXAMPLE1),
                  see Section 5.4.

                     <!--#echo value={created} var={example1} -->

               o  CREATED

                  The date/time of the current document's creation.

                     <!--#echo created[="time-format"] -->

               o  DATE_LOCAL

                  Include the current date/time.

                     <!--#echo date_local[="time-format"] -->

               o  DATE_GMT

                  Include the current Greenwich Mean Time (UTC) date/time.

                     <!--#echo date_gmt[="time-format"] -->

               o  DOCUMENT_NAME

                  The current document's URL-style path.

                     <!--#echo document_name -->

               o  FILE_NAME

                  The current document's VMS file path.

                     <!--#echo file_name -->

               o  LAST_MODIFIED

            5-6  Server Side Includes (SSI)

 






                  The date/time of the current document's last modification.

                     <!--#echo last_modified[="time-format"] -->

            5.3.6 #ELIF

               The #elif directive (else-if) allows blocks of HTML markup and
               SSI directives to be conditionally processed, see Section 5.5
               and Section 5.3.13. This directive effectively allows a case
               statement to be constructed.

                  <!--#elif var="[{variable}|literal" -->

            5.3.7 #ELSE

               The else directive allows blocks of HTML markup and SSI
               directives to be conditionally processed, see Section 5.5.
               It is the default block after an "#if", "#orif" or "#elif".

                  <!--#else -->

            5.3.8 #ENDIF

               The #endif directive marks the end of a block of document text
               being conditionally processed, see Section 5.5.

                  <!--#endif -->

            5.3.9 #EXEC

               The #exec directive executes a DCL command and incorporates
               the output into the processed document. It is the VMS equiva-
               lent 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 sup-
               ports only the cmd tag, the cgi tag, allowing execution of
               CGI scripts, is not supported.

                  <!--#exec cmd="show device/full tape1:" -->

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




                                               Server Side Includes (SSI)  5-7

 






            5.3.10 #FCREATED

               The #fcreated directive incorporates the creation date/time of
               a specified file/document into the processed document.

               o  FILE

                  Document specified using a VMS file path.

                     <!--#fcreated file="file-name" [fmt="time-format"] -->

               o  VIRTUAL

                  Document specified using URL-style syntax.

                     <!--#fcreated virtual="path" [fmt="time-format"] -->

            5.3.11 #FLASTMOD

               The #flastmod directive incorporates the last modification
               date/time of a specified file/document into the processed
               document.

               o  FILE

                  Document specified using a VMS file path.

                     <!--#flastmod file="file-name" [fmt="time-format"] -->

               o  VIRTUAL

                  Document specified using URL-style syntax.

                     <!--#flastmod virtual="path" [fmt="time-format"] -->

            5.3.12 #FSIZE

               The #fsize directive incorporates the size, in bytes, kbytes
               or Mbytes, of a specified file/document into the processed
               document.

               o  FILE

                  Document specified using a VMS file path.

                     <!--#fsize file="file-name" [fmt="size-format"] -->

               o  VIRTUAL

                  Document specified using URL-style syntax.

                     <!--#fsize virtual="path" [fmt="size-format"] -->

            5-8  Server Side Includes (SSI)

 






            5.3.13 #IF

               The #if directive allows blocks of HTML markup and SSI
               directives to be conditionally processed, see Section 5.5.

               o  VAR=

                  Variable the decision will be based upon.

                     <!--#if var="[{variable}|literal]" -->

               o  EQS=

                  Is the string the same as in the variable?

               o  EQ=

                  If the variable is a number is it the same as this?

               o  GT=

                  If the variable is a number is it greater than this?

               o  LT=

                  If the variable is a number is it less than this?

               o  SRCH=

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

               As in the following examples:

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

            5.3.14 #INCLUDE

               The #include directive incorporates the contents of a
               specified file/document into the processed document.

               o  FILE

                     <!--#include file="file-name" -->

               o  VIRTUAL

                  Include the contents of the document specified using URL-
                  style syntax.

                     <!--#include virtual="path" -->

                                               Server Side Includes (SSI)  5-9

 






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

                  <!--#include virtual="example.html" type="text/plain" -->

               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.

            5.3.15 #ORIF

               The #orif directive (or-if) allows blocks of HTML markup and
               SSI directives to be conditionally processed, see Section 5.5
               and Section 5.3.13. 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" -->

            5.3.16 #PRINTENV

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

                  <!--#printenv -->

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

               <online hypertext demonstration>

            5.3.17 #SET

               The #set directive allows a user variable to be assigned or
               modified, see Section 5.4.

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

            5-10  Server Side Includes (SSI)

 






            5.3.18 #SSI

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

                  <!--#ssi
                  #set var=HOUR value={DATE_LOCAL,12,2}
                  #if var={HOUR} lt=12
                    #set var=GREETING value="Good morning"
                  #elif var={HOUR} lt=19
                    #set var=GREETING value="Good afternoon"
                  #else
                    #set var=GREETING value="Good evening"
                  #endif
                  -->

               The example SSI document, HT_ROOT:[DOC.ENV]XSSI.SHTML,
               illustrates this concept.

            5.3.19 #STOP

               The #stop directive causes the server to stop processing
               the document. It can be used with flow control structures
               to conditionally process only part of a document.

                  <!--#stop -->

            5.3.20 #TRACE

               The #trace directive switches document processing trace on
               or off. This directive is intended for use when debugging
               flow-controlled SSI documents.

                  <!--#trace ON|OFF -->

               Output from a trace is colour-coded.

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

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

                                              Server Side Includes (SSI)  5-11

 






               o  Magenta -  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 (":").

               o  Black -  Document (HTML and text) output is displayed as
                  black plain text.

               The following link provides an example of a document trace.

               <online hypertext demonstration>

            5.4 Variables

               The SSI processor maintains information about the server, date
               and time, request path, request parameters, etc., accessable
               via variable name. Although these server variables cannot be
               modified by the document the processor also allows the author
               to create and assign new document variables by name.

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

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

               <online hypertext demonstration>

               Whenever a directive uses information from a tag (see
               Section 5.2) 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.

            5-12  Server Side Includes (SSI)

 






               Substrings

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

                  {variable-name,start-index,count}

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

               To illustrate,

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

               would output

                  That was an example!

               Other "Functions"

               o  LENGTH -  This "function" returns the length of the
                  parameter string (or substring).

                     {variable-name[,start-index],count]],length}

                  For example

                     <!--#set var=EXAMPLE value="This is an example!" -->
                     <!--#echo "\"{EXAMPLE}\" is {EXAMPLE,length} characters long." -->
                     <!--#echo "\"{EXAMPLE,5,2}\" is {EXAMPLE,5,2,length} characters long!" -->

                  would output

                     "This is an example!" is 19 characters long.
                     "is" is 2 characters long!

               o  EXISTS -  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!

                     {variable-name,exists}

                  For example

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

                                              Server Side Includes (SSI)  5-13

 






               Example

               The example SSI document, HT_ROOT:[DOC.ENV]XSSI.SHTML,
               illustrates these concepts.

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


               o  #if -  Marks the start of a conditionally processed block.
                  If evaluated true the block is processed.

               o  #orif -  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)

               o  #elif -  Allows a series of conditionals to be tested each
                  with it's own document block available for processing.
                  Allows a type of case statement to be constructed.

               o  #else -  Provides a default document block following un-
                  successful "#if", "orif" and "elif" testing and consequent
                  non-processed blocks.

               o  #endif -  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.

               o  eqs -  If the supplied string is the same as the variable
                  string.

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

            5-14  Server Side Includes (SSI)

 






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

               o  lt -  If the numeric value of the variable is less than
                  that of the supplied number.

               o  gt -  If the numeric value of the variable is greater than
                  that of the supplied number.

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

                  <!--##trace par=ON -->
                  <HTML>
                  <!--#set var=HOUR value={DATE_LOCAL,12,5} -->
                  <!--#if var={HOUR} lt=12 -->
                  <!--#set var=GREETING value="Good morning" -->
                  <!--#elif var={HOUR} lt=19 -->
                  <!--#set var=GREETING value="Good afternoon" -->
                  <!--#else -->
                  <!--#set var=GREETING value="Good evening" -->
                  <!--#endif -->
                  <HEAD>
                  <TITLE><!--#echo var={GREETING} -->
                  <!--#echo var="{REMOTE_HOST}!" --></TITLE>
                  </HEAD>
                  <BODY>
                  <H1>Simple XSSI Demonstration</H1>
                  <!--#echo var={GREETING} --> <!--#echo var={REMOTE_HOST} -->,
                  the time here is <!--#echo var={DATE_LOCAL,12,5} -->.
                  <!--#if var={REMOTE_HOST} eqs={REMOTE_ADDR} -->
                  (Sorry, I do not know your name, DNS lookup must be disabled!)
                  <!--#endif -->
                  </BODY>
                  </HTML>

               The example SSI document, HT_ROOT:[DOC.ENV]XSSI.SHTML, further
               illustrates these concepts.

            5.6 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

                                              Server Side Includes (SSI)  5-15

 






               query string components to this as if they were form elements.
               For example:

                  ?httpd=ssi&printenv=no
                  ?httpd=ssi&printenv=yes
                  ?httpd=ssi&trace=yes&test2=one&test2=two&test3=three

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

               <online hypertext demonstration>

            5.7 File and Virtual Specifications

               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 Section 3.3 for
               further details.

            5.8 Time Format

               Note:  Time formatting only applies if the HTTPd server has
               been compiled using DEC C.

               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 speci-
               fiers. For futher information on the formatting process refer
               to a C programming library document on the strftime()  func-
               tion.

            5-16  Server Side Includes (SSI)

 






                  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

                                              Server Side Includes (SSI)  5-17

 






                  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

            5-18  Server Side Includes (SSI)

 






                  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.

                  %              %








































                                              Server Side Includes (SSI)  5-19

 








            Chapter__6_______________________________________________________

            Clickable Image Support


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


               Digression . . . How It Works

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

               Steps For Using a Clickable Image

               1. create an image configuration file (see Section 6.1),
                  mapping pixel coordinates of regions within the image to
                  URLs

               2. specify an HTML anchor using an inline "<IMG...>" tag, the
                  "HREF=" specifies the path to the image configuration file

               3. specify "ISMAP" in the "<IMG...>" tag

                  For example:

                     <A HREF="ismap_demo.ismap">
                     <IMG SRC="ismap_demo.gif" ISMAP></A>

            6.1 Image Configuration File

               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

                                                  Clickable Image Support  6-1

 






               with a default keyword. These can be supplied in either of two
               formats. The NCSA format may be more commonly used.

               1. NCSA

                  o  circle URL x1,y1 x2,y2
                     URL to be returned when the click is within a circle of
                     centre-point x1,y1 and a circumference specified by the
                     edge-point x2,y2.

                  o  rectangle URL x1,y1 x2,y2
                     URL to be returned when the click is within a rectangle
                     having opposite corners x1,y1 and x2,y2.

                  o  point URL x,y
                     With multiple points specified, the URL of the point
                     closest to the click.

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

                  o  default URL
                     URL to be returned when the click is not within any of
                     the specified coordinates, and there has been no point
                     specified.

               2. CERN

                  o  circle (x,y) r URL
                     URL to be returned when the click is within a circle of
                     radius r at centre-point (x,y).

                  o  rectangle (x1,y1)(x2,y2) URL
                     URL to be returned when the click is within a rectangle
                     having opposite corners (x1,y1) and (x2,y2).

                  o  point (x1,y1) URL
                     With multiple points specified, the URL of the point
                     closest to the click (strictly speaking, this is NCSA
                     only).

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

            6-2  Clickable Image Support

 






                  o  default URL
                     URL to be returned when the click is not within any of
                     the specified coordinates, and there has been no point
                     specified.

               For online examples of rule usage within configuration files
               see Section 6.2 below. Note that:

               o  There must be only one region keyword on each line.

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

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

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

               o  The keywords may be abbreviated to circ, rect, poly, poin
                  and def.

               o  Blank lines are ignored.

               o  Commentary must be preceded by a "#" or "!" character.

                                          hint . . .

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

            6.2 Examples

               See example in the HT_ROOT:[EXERCISE] directory.







                                                  Clickable Image Support  6-3

 








            Chapter__7_______________________________________________________

            Document 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 3) will be searched. Others may be specified, or be
               selected from wildcard file specification, but they will not
               actually have their contents searched.

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

            7.2 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

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

               only the following text would actually be searched

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

                                                       Document Searching  7-1

 






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


            7.3 Search Syntax

               A search may be initiated in one of two ways:

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

               2. Forms-based search, which allows the format and mechanism
                  of the search to be controlled.

            7.3.1 "ISINDEX" Search

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

               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:

                  /web/html/html-primer/*.html?problem

            7.3.2 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

               <online hypertext demonstration>

            7-2  Document Searching

 






            7.3.3 Search Options

               Additional URI components may be appended after the initial
               "search=" parameter. These are appended with intervening "&"
               characters.

               o  Case-Sensitivity.  An optional URI component of "case=yes"
                  or "case=no" makes the search case-sensistive or case-
                  insensistive (the default). The following example illus-
                  trates the use of this syntax:

                     /web/html/.../*.html?search=Protocol&case=yes
                     /web/html/.../*.html?search=PrOtOcOl&case=no

                  <online hypertext demonstration>

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

                  <online hypertext demonstration>

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

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

               <online hypertext demonstration>

               Bells and Whistles

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

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

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

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

                                                       Document Searching  7-3

 






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

               <online hypertext demonstration>







































            7-4  Document Searching

 








            Chapter__8_______________________________________________________

            VMS Help and Text Libraries


               Affectionately known as Conan the Librarian, and with all
               due acknowlegement to Wierd Al.Yankovic ":^)", this script
               makes VMS Help and Text libraries accessable in the hypertext
               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:

                  <A HREF="/sys$common/syshlp/helplib.hlb">VMS help</A>
                  <A HREF="/conan/sys$common/syshlp/helplib.hlb">VMS help via /Conan</A>

               <online hypertext demonstration>

               Other Librarian Functionality

               To obtain an index of matching libraries explicitly activate
               the Conan script providing a wildcard file specification.

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

               <online hypertext demonstration>

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

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

               <online hypertext demonstration>










                                              VMS Help and Text Libraries  8-1

 








            Chapter__9_______________________________________________________

            Bookreader Books and Libraries


               Access to DEC's Bookreader format documentation (and any
               generated internally) is provided in the WASD hypertext
               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). The
               following examples illustrate the syntax:

                  <A HREF="env.decw$book">This document from Bookreader</A>
                  <A HREF="env.decw$bookshelf">The shelf DEC Document creates for this</A>

                  <A HREF="/HyperReader/ht_root/doc/env/env.decw$book">
                    This document from Bookreader</A>
                  <A HREF="/HyperShelf/ht_root/doc/env/env.decw$bookshelf">
                    The shelf DEC Document creates for this document</A>

               <online hypertext demonstration>





















                                           Bookreader Books and Libraries  9-1

 








            Chapter__10______________________________________________________

            Web Document Update


               The Update 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 that this is not designed as a full
               hypertext administration or authoring tool, and for document
               preparation relies on the editing capabilities of the
               "<TEXTAREA>" widget of the user's browser. It does however,
               allow ad-hoc changes to be made to documents fairly easily, as
               well as allowing documents to be deleted, and directories to
               be created and deleted.

               Consult the current Update documentation for usage detail.

               <online hypertext link>

               Update Access Permission

               Of course, the user must have write (POST/PUT) access to
               the document or area on the server (i.e. the path) and the
               server account have file system permission to write into the
               parent_directory.

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

               The server will report "Insufficient privilege or object
               protection violation ... /path/" if it does not have file
               system permission to write into a directory.

               Write access by the server into VMS directories (using the
               POST or PUT HTTP methods) is controlled using VMS ACLs. This
               is in addition to the path authorization of the server itself
               of course! 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.

               Two different ACLs implement two grades of access.

               1. If the ACL grants CONTROL access to the server account then
                  only VMS-authenticated usernames with security profiles
                  can potentially write to the directory. Only potentially,

                                                     Web Document Update  10-1

 






                  because a further check is made to assess whether that VMS
                  account in particular has write access.

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

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

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

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

               2. If the ACL grants WRITE access then the directory can
                  be written into by any authenticated username for the
                  authorized path.

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

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

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

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


















            10-2  Web Document Update

 








            Chapter__11______________________________________________________

            dBASEIV Query Interface


               The "dBASEIV" script provides query access to VMS-based
               dBASEIV databases.

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

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

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

               A Submit Query button allows the completed query form to be
               sent to the server, and the report generated and returned to
               the user.

               Query Strings

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

               Query Form Builder

               To assist in building query interfaces for specific databases
               the "dBASEIV" 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.




                                                 dBASEIV Query Interface  11-1

 








            Chapter__12______________________________________________________

            Document Printing


               The print script allows the printing of PostScript, text and
               other files on WASD printers. It is restricted to browsers
               from WASD hosts for obvious reasons!.

               The print script may be accessed by specifying /print as a
               prefix to the document specification to be printed, as in the
               following example:

                  <A HREF="/print/ht_root/doc/htd/htd.ps">This Document</A>

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

               <online hypertext demonstration>

























                                                       Document Printing  12-1

 








            Chapter__13______________________________________________________

            Menus


               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.

               A menu is distinguished from other files by its type
               extension, ".MENU" (or ".MNU" for "8.3" MS-DOS compliance).

               The "WASD Hypertext Management Primer" provides a complete
               description on the use of menus.

               <online document available>.



























                                                                   Menus  13-1
