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

<CHAPTER>(Server Administration\chapter_server_admin)

<P> The online Server Administration facility provides a rich collection of
functionality, including server control, reports and configuration.  Some of
these are intended as general administration tools  while other provide more
detailed information intended for server debugging and development purposes. 

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

<COMMENT>(HTML=
<P><CENTER>
<IMG SRC="image.gif" BORDER=0 ALT="[graphic]" ALIGN=bottom>&nbsp;
<A HREF="admin.gif" TARGET="_blank">Server Administration Graphic</A>
</CENTER>)

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

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

<P> The value of the WATCH facility <REFERENCE>(chapter_watch) as a general
configuration and problem-solving tool cannot be overstated.

<P> All server configuration files, with the execption of the authentication
databases, are plain text and may be modified with any prefered editor. 
However the majority of these can also be administered online through a
browser.  In addition the <EMPHASIS>(update) facility allows some
administration of file system portions of the Web. See
<REFERENCE>(chapter_web_update).

<P> Access to many portions of the package is constrained by file protections
and directory listing access files.  See
<REFERENCE>(head_auth_sysuaf_profile_site) for a method for circumventing these
restrictions.

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

<HEAD1>(Access Without Configuration\head_admin_no_config)

<P> It is often a significant advantage for the inexperienced administrator on
a new and largely unconfigured installation to be able to gain access to the
facilities offered by Server Administration, particularly the WATCH facility
(<REFERENCE>(chapter_watch)).  This can be done quite simply by using the
authentication skeleton-key (<REFERENCE>(head_auth_skeleton_key)).  This allows
the site administrator to register a username and password from the commnd-line
that can be used to gain access to the server.  In addition, the server ensures
that requesting an otherwise non-authorized Server Administration facility
generates a challenge which invokes a username/password dialog at the browser
allowing the user to enter the previously registered username and password and
gain access. 

<HEAD>(Method\head_admin_no_config_method)

<LIST>(UNNUMBERED)

<LE> Register the skeleton-key username and password.

<CODE_EXAMPLE>
  $ HTTPD == "$HT_EXE:HTTPD.EXE"
  $! HTTPD == "$HT_EXE:HTTPD_SSL.EXE"
  $ HTTPD /DO=AUTH=SKELKEY=<EMPHASIS>(_username:password)
<ENDCODE_EXAMPLE>

<P> Note that the username must begin with an underscore, be at least 6
characters, is delimited by a colon, and that the password must be at least 8
characters.  By default this username and password remains valid for 60
minutes.  <EMPHASIS>(Choose strings that are less-than-obvious!\BOLD)

<LE> Access the server via a browser and use the server Server Administration
facility.

<COMMENT>(HTML=<PRE>
  <A HREF="/httpd/-/admin/">http://the.host.name:port/httpd/-/admin/</A>
</PRE>)

<COMMENT>(HTML/OFF)
<CODE_EXAMPLE>
  http://the.host.name:port/httpd/-/admin/
<ENDCODE_EXAMPLE>
<COMMENT>(HTML/ON)

<LE> After use the skeleton-key may be explicitly cancelled if desired.

<CODE_EXAMPLE>
  $ HTTPD /DO=AUTH=SKELKEY=0
<ENDCODE_EXAMPLE>

<ENDLIST>

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

<HEAD1>(Access Configuration\head_admin_access_config)

<P> One established the site should make the Server Administration facility a
configured facility of the site.  The value of it's facilities cannot be
overstated. The section <REFERENCE>(head_auth_quick_identifier) provides a
short guide to setting up authorization for server administration purposes.

<P> It is also recommended that for production sites the path to these reports
be controlled via authentication and authorization, using both host and
username restrictions, similar to the following:

<CODE_EXAMPLE>
  [WHATEVER-REALM]
  /httpd/-/admin/*  host.ip.addr,~WebMaster,~WhoEverElse,r+w
<ENDCODE_EXAMPLE>

<P> If a full authorization environment is not required but
administration via browser is still desired restrict access to browsers
executing on the server system itself, using an appropriate
SYSUAF-authenticated username. Provision of a VMS account for server
administration only is quite feasable, see
<REFERENCE>(head_auth_web_only).

<CODE_EXAMPLE>
  [VMS]
  /httpd/-/admin/*  #localhost,~<EMPHASIS>(username),r+w
<ENDCODE_EXAMPLE>

<P> If SSL is in use (<REFERENCE>(chapter_ssl)) then username/password
privacy is inherently secured via the encrypted communications. To restrict
server administration functions to this secure environment add the following
to the HTTPD$MAP configuration file:

<CODE_EXAMPLE>
  /httpd/-/admin/*  "403 Access denied."  ![sc:https]
<ENDCODE_EXAMPLE>

<P> When using the <EMPHASIS>(revise) capability of the Server Administration
facility is necessary to comply with all the requirements for Web update of
files. This is discussed in general terms in <REFERENCE>(chapter_web_update).
Revision of server configuration files requires path permissions allowing write
access for the username(s) doing the administration, as well as the required
ACL on the target directory (in the following example HT_ROOT:[LOCAL]).

<CODE_EXAMPLE>
  [VMS]
  /httpd/-/admin/*  #localhost,~<EMPHASIS>(username),r+w
  /ht_root/local/*  #localhost,~<EMPHASIS>(username),r+w
<ENDCODE_EXAMPLE>

<P> It is possible to allow general access to the Server Administration
facility and reports while restricting the ability to initiate server actions
such as a restart! Using the WORLD realm against the path is necessary, for the
obvious security reason, the server administration module will not allow itself
to be used without an authenticated username, provided as a
pseudo-authenticated
<QUOTE>(WORLD).

<CODE_EXAMPLE>
  [VMS]
  /httpd/-/admin/control/*  #localhost,~<EMPHASIS>(username),r+w
  [WORLD]
  /httpd/-/admin/* r
<ENDCODE_EXAMPLE>

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

<HEAD1>(Server Instances\head_server_reports_instances)

<P> With a single instance (<REFERENCE>(head_config_instances)) access to
Server Administration reports, etc. is always serviced by the one server
process.  If multiple instances are configured in common with all requests
administration requests will be serviced by any one of the associated processes
depending on the indeterminate current state of the round-robin distribution. 

<P> There are many circumstances where it is preferable to access only the one
server.  This can be accomplished for two differing objectives.

<LIST>(NUMBERED)

<LE> To facilitate access to a specific instance's Server Administration page,
including instance-specific reports etc.  This is provided through the use of
an <EMPHASIS>(administration service) port (<REFERENCE>(head_service_admin))
available from the Server Administration page.

<LE> The Server Administration page (<REFERENCE>(head_server_action_control))
and the command-line (<REFERENCE>(head_server_instance)) provides the
capability to explicitly set the number of instances supported, overriding any
configuration directive.  After explicitly setting this using either means the
server must be restarted.  The explicit startup setting remains in effect until
it's changed to <QUOTE>(max) allowing the HTTPD$CONFIG configuration directive
[InstanceMax] to once again determine the number of instances required.

<ENDLIST>

<P> The latter approach is particularly useful when performing detailed WATCH
activities (<REFERENCE>(chapter_watch)).

<P> When multiple per-node instances are executing the Server Administration
pages and reports all include an indication of which process serviced the
request.  When accessing no instance in particular the process name is
presented in parentheses after the page title

<CODE_EXAMPLE>
  HTTPd wasd.dsto.defence.gov.au:80
  Server Administration  (HTTPd:80)
<ENDCODE_EXAMPLE>

<CP> When a particular instance's administration service port is being used the
process name is separated from the page title by a hyphen

<CODE_EXAMPLE>
  HTTPd wasd.dsto.defence.gov.au:80
  Server Administration - HTTPd:80
<ENDCODE_EXAMPLE>

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

<HEAD1>(HTTPd Server Reports\head_server_reports)

<P> The server provides a number of internally generated reports.  Some of
these are of general interest.  Others are more for evaluating WASD behaviour
and performance for development purposes.  These are listed in the approximate
order in which they occur top-to-bottom, left-to-right in the menu layout.

<P> It is possible to use this facility standalone, without configuring
authorization (<REFERENCE>(head_admin_no_config)).

<LIST>(UNNUMBERED)

<LE><EMPHASIS>(Statistics - \BOLD)

Server process up-time, CPU-time and other resources consumed, number of
connections processed, number of requests of each HTTP method, type of
processing involved (HTTPd module used), number of bytes processed, etc.

<LE><EMPHASIS>(Log - \BOLD)

Display the server process (SYS$OUTPUT) log.

<LE><EMPHASIS>(Configuration - \BOLD)

A tabular summary of the server's current configuration.  This is
a convenient method for viewing the information from the HTTPD$CONFIG file.

<LE><EMPHASIS>(Services - \BOLD)

A tabular report listing the current services (virtual servers) and the
service-specific parameters.

<LE><EMPHASIS>(Messages - \BOLD)

A tabular report of the server's current message database, multiple
languages shown if configured that way.

<LE><EMPHASIS>(Mapping - \BOLD)

All loaded mapping rules and any cached USER rule paths.  A selector allows
rules applying only to one particular virtual server to be displayed.

<LE><EMPHASIS>(Path Authorization - \BOLD)

If authorization is in use (<REFERENCE>(chapter_authorization)) this
report lists the paths with associated authorization and access control.

<LE><EMPHASIS>(User Authentication - \BOLD)

List any users that have been authorized since the server was last
started, the realm authorized from, the group it applies to (if any), and what
the user's capabilities are (allowed HTTP methods). A time-stamp and counters
provide additional information.

<LE><EMPHASIS>(Secure Sockets - \BOLD)

The SSL report lists counts of the number of SSL transactions initiated
and completed, along with session cache statistics for the currently connected
SSL service.  It also lists the ciphers available and current session
information.  Other reports allow the Certificate Authority (CA) database to be
view and edited, if available due to X.509 authentication being enabled.

<LE><EMPHASIS>(Cache - \BOLD)

Allows monitoring of cache behaviour and performance, as well as the files
currently in the cache (<REFERENCE>(chapter_cache)).

<LE><EMPHASIS>(DCL Scripting - \BOLD)

Provides some DCL, CGI and CGIplus scripting information.

<P>  DCL module statistics (same information as displayed in the server
statistics report).  These are cumulative for the entire life of the system
(unless zeroed).

<P> Subprocess information shows how many actual subprocesses exist at the
time of the report, as indicated by the PID and bolded, non-zero liftime (in
minutes). The <EMPHASIS>(soft-limit) specifies how many CGIplus scripts are
allowed to continue existing before the least used is deleted and the
<EMPHASIS>(hard-limit) show how many subprocesses may actually exist at any
one time (the margin allows for subprocess deletion latency). A count of how
many times the CGIplus subprocesses have been explicitly purged (button
available on this report page). The <EMPHASIS>(life-time) of zombie processes
(in minutes, zero implying use of zombies is disabled) and the number that
have been purged due to expiry. CGIplus subprocess life-time (in minutes, zero
implying indefinite), the number purged due to life-time expiry and the number
of CGIplus subprocesses that the server has actually purged (deleted) to
maintain the soft-limit margin specified above.

<P> Each of the allocated subprocess data structures is listed.  There may
be zero up to hard-limit items listed here depending on demand for DCL
activities and the life of the server.  Items with a PID shown indicate an
actual subprocess existing.  This can be a zombie subprocess or a CGIplus
subprocess.  If no subprocess is indicated then the other information
represents the state the last time the item's associated subprocess completed.
Information includes the script (URL-style path) or DCL command, total count of
times the item has been used and the last time it was.  The zombie count
indicates the number of time the same subprocess finished a request and entered
the <EMPHASIS>(zombie) state.  The CGIplus column indicates it is/was a CGIplus
script and shows the total number of times that particular script has been/was
used.  If the subprocess is currently in use the client information show the
client host name.

<P> If any subprocesses are associated with any data structure a
<EMPHASIS>(purge) button is provided that forces all subprocesses to be
deleted.  This can be useful if a new script image is compiled and it is
required all scripts now use this.  If a script is currently processing a
request the subprocess deletion occurs when that processing is complete. The
purge button <EMPHASIS>(does not force\BOLD) a subprocess to delete, so a
second button <EMPHASIS>(forces\BOLD) all subprocesses to delete immediately. 
This can be used to forceably clear errant scripts, etc., but be warned script
processing is indiscrimately stopped!

<LE><EMPHASIS>(DECnet Scripting - \BOLD)

DECnet module information shows totals for DECnet scripting usage and the
DECnet connection list.

<P> This list will grow, up to the specified configuration maximum, as
conconurrent scripting demand occurs. Maintained connections are indicated by
the bolded, non-zero lifetime (in minutes). When this reaches zero the task is
disconnected. The current/last task for that connection is indicated, along
with the number of times the connection was reused and a total number of uses
for that list item.

<P> <EMPHASIS>(Purge) and <EMPHASIS>(force) buttons allow current links to be
broken after request completion or forcibly disconnected.

<LE><EMPHASIS>(Lock - \BOLD)

Lists the names and status of all lock resources used to manage single and
multiple instances across single systems or a cluster.  This report is more
relevant for evaluating and debugging WASD behaviour.

<LE><EMPHASIS>(Match - \BOLD)

To assist with the refinement of string matching patterns
(<REFERENCE>(chapter_string_matching)) this report allows the input of target
and match strings and allows direct access to the server's wildcard and regular
expression matching routines.  Successful matches show the matching elements
and a substitution field (<REFERENCE>(head_string_matching_subs)) allows
resultant strings to be assessed.

<LE><EMPHASIS>(Memory - \BOLD)

Provides a report and does an integrity check on each of the Virtual
Memory (VM) zones employed by the WASD HTTPd.

<LE><EMPHASIS>(Process - \BOLD)

Lists all processes on the current system owned by the server account. 
From this list a process can be selected to have a <QUOTE>(SHOW PROCESS /ALL)
performed on it, displayed on a report page.

<LE><EMPHASIS>(Proxy - \BOLD)

If proxy serving is enabled a report providing statistics on the various
HTTP methods used, network and cache traffic, cache reads and writes, requests
not cachable, and host name lookup are provided.  This may used to help guage
the effectiveness of the cache.

<LE><EMPHASIS>(Request - \BOLD)

Lists current requests (always shows at least your own connection
accessing this report :^) and if enabled by configuration an optional history
list of  the most recent requests (enabled by the configuration parameter
[RequestHistory]).  Current requests may be selected for
<EMPHASIS>(one-shot) WATCH-processing reports from this page
(<REFERENCE>(chapter_watch)).

<P> Two other diagnostic tools are available from the same link.  The first,
<EMPHASIS>(WATCH-peek Report), providing a snapshot of the contents
selected internal fields and data structures of the request.  This is primarily
intended as a problem investiagtion and development tool, and will be 
of limited value without an understanding of server internals.  The second
accesses the <QUOTE>(peek) internals plus a one-shot WATCH-processing report. 

<P> For servers handling a great quantity of concurrent traffic this can
generate a very large report.  The <EMPHASIS>(Supervisor) report can also
provide a profile of the servers current load.

<LE><EMPHASIS>(Supervisor - \BOLD)

Provides a simple table displaying each timer list and any associated request
count.  Shows how many requests are set be scanned and evaluated for continued
processing every so-many seconds.  For very busy servers this is another method
for gaining an idea of the traffic profile (this is perhaps more meaningful for
those with an understanding of WASD internals).

<LE><EMPHASIS>(System - \BOLD)

Shows the system, all users, memory and CPU status as a single report.

<LE><EMPHASIS>(Throttle - \BOLD)

This report provides a list of paths with throttle rules mapped against them. 
It provides the throttle values along with current and history activity
counters.

<LE><EMPHASIS>(Activity - \BOLD)

Provide a graphical <EMPHASIS>(snapshot) of server activity of a given period.

<P> The statistics are stored in a permanent global section and so carry-over
between server restarts.  Where multiple instances are executing the data
represents an accumulation of all instances' processing. It is enabled by the
configuration parameter [ActivityDays]. The Server Administration facility
provides several, represented as a period of hours before the present time.
Number of requests and bytes sent to the client are represented by a histogram
with respective means for each by a line graph.  A bar across the column of the
request histogram indicates the peak number of concurrent requests during the
period.  A <EMPHASIS>(greyed) area indicates no data available for that time
(i.e. before the latest server startup, or in the future).

<P> Server startup and shutdown events are indicated by solid, vertical lines
the full height of the graph (see example for a restart event).

<LIST>(SIMPLE)

<LE> startup - green
<LE> shutdown - black
<LE> restart - grey
<LE> error exit - red

<ENDLIST>

<P> Activity data is accumulated on a per-minute basis. This is the maximum
granularity of any report. When reports are selected that can display less
than this one minute granularity (i.e. with periods greater than four hours)
the value shown is the <EMPHASIS>(peak\BOLD) of the number of minutes sampled
for display. This better represents the load on the server than would a mean
of those samples.

<P> The graph is an image map, various regions of which allow the selection of
other reports with different periods or durations. This allows previous
periods to be examined at various levels of detail using the graph for
navigation. Various sections may have no mapping as appropriate to the current
report.

<P> For multiple hour reports the upper and lower sections have distinct
functions. The middle 50% of the upper section allows the same end time (most
commonly the current hour) to be examined over twice the current period, in
this case it would be over eight hours. The left 25% allows the previous fours
hours to be viewed (if such data exists), and for non-current reports the right
25% allows the next four hours to be viewed. The lower half can be divided into
sections representing hours or days depending on the period of the current
report. This allows that period to be viewed in greater detail. For single hour
reports this section, of course, is not mapped.

<P> Remember that the URL of the mapped section will be displayed in the
status bar of the browser. As the URL contains time components it is not a
difficult task to decipher the URL displayed to see the exact time and period
being selected.

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

<COMMENT>(HTML=
<P><CENTER>
<IMG SRC="image.gif" BORDER=0 ALT="[graphic]" ALIGN=bottom>&nbsp;
<A HREF="activity.gif" TARGET="_blank">Server Activity Graphic</A>
</CENTER>
)

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

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

<LE><EMPHASIS>(WATCH - \BOLD)

This report provides an online, real-time, in-browser-window view of request
processing on the <EMPHASIS>(running server\BOLD). See
<REFERENCE>(chapter_watch) for details.

<ENDLIST>

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

<HEAD1>(HTTPd Server Revise\head_server_revise)

<P> The server provides a comprehensive configuration revision facility.

<LIST>(UNNUMBERED)

<LE> <EMPHASIS>(Configuration - \BOLD)
A form-driven interface allows the current configuration of the server to be
altered online.  This configuration may then be saved to the on-disk file and
then the server could be restarted using the new parameters.  The source of the
current configuration can be either the server itself (from it's volatile,
in-memory parameters) or from the on-disk configuration file.  In addition it
is possible to directly edit and update the on-disk file.

<LE> <EMPHASIS>(Services - \BOLD)
A form-driven interface allows service (virtual server) configuration.
It is also possible to directly edit and update the on-disk file.  The server
must be restarted for service changes to take effect.

<LE> <EMPHASIS>(Messages - \BOLD)
A form-driven interface allows the the server messages to be modified.
It is also possible to directly edit and update the on-disk file.  The
server can then be restarted to use the modified database
(<REFERENCE>(head_server_action)).

<LE> <EMPHASIS>(Mapping - \BOLD)
No form-driven interface is currently available for changing the mapping rules. 
However it is possible to directly edit and update the on-disk file.  The
mapping rules could then be reloaded, changing the current server rules
(<REFERENCE>(head_server_action)).

<LE> <EMPHASIS>(Path Authorization - \BOLD)
No form-driven interface is currently available for changing the path
authorization configuration. However it is possible to directly edit and update
the on-disk file.  The path authorization directives could the be reloaded,
changing the current server authorization (<REFERENCE>(head_server_action)).

<LE> <EMPHASIS>(User Authentication - \BOLD)
User authentication comprises a number of dialogues that allow the
WASD-specific (HTA) authentication databases to be administered.  These
include:

<P>

<LIST>(SIMPLE)
<LE> creating databases
<LE> deleting databases
<LE> accessing databases for administering usernames
<LE> listing usernames within databases
<LE> adding usernames
<LE> deleting usernames
<LE> modifying username permissions and other data
<LE> reseting in-server (cached) authentication information
<ENDLIST>

<P> Chapter <REFERENCE>(chapter_authorization) covers authentication detail.

<LE> <EMPHASIS>(Site Log - \BOLD)
This accesses a plain-text file that could be used to record server or other
significant site configuration changes if desired.  Two methods of access are
provided.

<LIST>(NUMBERED)
<LE> Site-Log - open the file for editing, placing a
date/time/author timestamp at the top
<LE> Edit - open the file editing
<ENDLIST>

<P> The file name and/or location may be specified using HTTPD$SITELOG
(<REFERENCE>(head_server_logical_names)).

<ENDLIST>

<HEAD>(Enabling Server Access\head_server_access)

<P> Many of the server activites listed above require server account write
access to the directory in which the configuration files are stored.  Where an
autononmous scripting account is in use
(<REFERENCE>(config_securing_scripting)) this poses minimal threat to server  
configuration integrity.

<LIST>(NUMBERED)

<LE> Specifically map the /ht_root/local/ path and mark it as access always
requiring authorization (ensure this is one on the first mappings in the file
and certainly before any other /ht_root/ ones).

<CODE_EXAMPLE>
  # HTTPD$MAP
  pass /ht_root/local/* auth=all
<ENDCODE_EXAMPLE>

<LE> Add appropriate authorization rules (example from
<REFERENCE>(head_auth_quick_identifier)).

<CODE_EXAMPLE>
  # HTTPD$AUTH
  ["Web Admin"=WASD_WEBADMIN=id]
  /httpd/-/admin/* r+w
  /ht_root/local/* r+w
<ENDCODE_EXAMPLE>

<LE> Update access to the directory can be applied using the SECHAN utility
(<REFERENCE>(head_sechan)).

<CODE_EXAMPLE>
  $ SECHAN /WRITE HT_ROOT:[000000]LOCAL.DIR
  $ SECHAN /WRITE HT_ROOT:[LOCAL]
<ENDCODE_EXAMPLE>

<LE> Load the new mapping and authorization rules.

<CODE_EXAMPLE>
  $ HTTPD /DO=MAP
  $ HTTPD /DO=AUTH=LOAD
<ENDCODE_EXAMPLE>

<ENDLIST>

<HEAD>(Alternative Using /PROFILE\head_server_access_profile)

<P> If a site is using SYSUAF authentication and security profiles enabled
using the /PROFILE startup qualifier (<REFERENCE>(head_auth_security_profile))
then a more restrictive set up is possible, retaining the default no-access to
the [LOCAL] directory.  This relies on the administering account(s) having read
and write access to the [LOCAL] directory. It is then not necessary to grant
that to the server account.  It is possible to limit the application of VMS
user profiles.  This is an example.

<CODE_EXAMPLE>
  # HTTPD$MAP
  set /ht_root/local/* profile auth=all
  set * noprofile
<ENDCODE_EXAMPLE>

<P> To use this approach perform steps 1, 2 and 4 from above, substituting the
following for step 3.

<CODE_EXAMPLE>
  $ SECHAN /PACKAGE HT_ROOT:[000000]LOCAL.DIR
  $ SECHAN /PACKAGE HT_ROOT:[LOCAL]
  $ SECHAN /CONTROL HT_ROOT:[000000]LOCAL.DIR
<ENDCODE_EXAMPLE>

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

<HEAD1>(HTTPd Server Action\head_server_action)

<P> The server allows certain run-time actions to be initiated.  Many of these
functions can also be initiated from the command line, see
<REFERENCE>(head_httpd_control).

<P> When multiple servers are executing on a single node or within a cluster
a JavaScript-driven checkbox appears in the bottom left of the administration
menu. <EMPHASIS>(Checking that box applies any subsequently selected action to
all servers!\BOLD)

<HEAD>(Control Section\head_server_action_control)

<LIST>(UNNUMBERED)

<LE> <EMPHASIS>(Server Restart/restartNOW/restartQuiet/Exit/exitNOW - \BOLD)

The difference between restart/exit and restartNOW/exitNOW is the former waits
for any current requests to be completed, while the latter does it immediately
regardless of any current connections.  The restartQuiet variant continues
processing until demand drops to zero for more than one second at which point
it commences restart.  If the browser has JavaScript enabled a cautionary alert
requesting confirmation is generated (otherwise there is no confirmation).

<LE> <EMPHASIS>(Logging On/Off/Flush - \BOLD)
The HTTPD$LOG logical must be configured to allow access logging to be enabled
and disabled from this menu.

<LE> <EMPHASIS>(Caching On/Off/Purge - \BOLD)
Caching may be enabled and disabled in an ad hoc fashion using these controls.
When being disabled after being enabled all previous data is retained.  If
subsequently reenabled that data is then again available for use.  This allows
convenient assessment of the subject or even object benefits on the cahing.
If purged all entries in the cache are removed.

<LE> <EMPHASIS>(Instance Startup - \BOLD)
An instance value may be set that overrides the configuration directive
[InstanceMax] at next startup.  This may be used to change the number of server
processes on an ad hoc basis.  Reset to <QUOTE>(max) to return to
configuration control.  Note that this can be applied to the current node only
or to all servers within a cluster, and that a subsequent restart is required.

<ENDLIST>

<HEAD>(Configuration <EMPHASIS>(Action) Section\head_server_action_config)

<LIST>(UNNUMBERED)

<LE> <EMPHASIS>(Statistics Zeroed - \BOLD)
All counters are zeroed (except the <EMPHASIS>(number-of-times-zeroed)
counter!)

<LE> <EMPHASIS>(Mapping Rules Reload - \BOLD)
Reloads the path mapping rules from the on-disk file into the running server,
clears the user SYSUAF mapping cache.

<P> <EMPHASIS>(Caution! \BOLD) If changing CGIplus script mapping it is
advised to restart the server rather than reload.  Some conflict is possible
when using new rules while existing CGIplus scripts are executing.

<LE> <EMPHASIS>(Path Authorization Reload - \BOLD)
Reloads the path authorization directives from the on-disk file into the
running server.

<LE> <EMPHASIS>(User Authentication Cache Purge - \BOLD)
For efficiency reasons authenticated user information is cached for a limited
period within the running server.  All this cached information may be
completely purged using this action, forcing subsequent requests to be
reauthenticated from the on-disk database.

<ENDLIST>

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

<CHAPTER>(WATCH Facility\chapter_watch)

<P> The WATCH facility is a powerful adjunct in server administration. From
the Server Administration facility (<REFERENCE>(chapter_server_admin)) it
provides an <EMPHASIS>(online, real-time,  in-browser-window view of request
processing in the running server\BOLD). The ability to observe live request
processing on an ad hoc basis, without changing server configuration or
shutting-down/restarting the server process, makes this facility a great
configuration and problem resolution tool. It allows (amongst other uses)

<LIST>(SIMPLE)
<LE> assessment of mapping rules
<LE> assessment of authorization rules
<LE> investigation of request processing problems
<LE> observation of script interaction
<LE> general observation of server behaviour
<ENDLIST>

<P> A single client per server process can access the WATCH facility at any
one time.  It can be used in one of two modes.

<LIST>(UNNUMBERED)

<LE> As a <EMPHASIS>(one-shot), one-off WATCH of a particular request.  This is
available from the <EMPHASIS>(Request Report) page of the Server Administration
facility.  In this case the single indicated request is tagged to be WATCHed
in all categories (see below) for the duration of the request (or until the
client stops WATCHing).

<LE> As described in the following chapter the server and all new requests
being processed are candidates for being WATCHed.  Categories are selected
before initiating the WATCH and the report can be generated for a user-specified
number of seconds or aborted at any time using the browser's <EMPHASIS>(stop)
button.

<ENDLIST>

<P> Options immediately below the duration selector allows the WATCH output
to concurrently be included in the server process log.  This allows a permanent
record (at least as permanent as server logs) to be simply produced.

<HEAD1>(Server Instances\head_reports_watch_instances)

<P> With a single instance (<REFERENCE>(head_config_instances)) access to
WATCH is always through the one server process.  If multiple instances are
configured WATCH requests, in common with all others, will be serviced
by any one of the associated processes depending on the indeterminate current
state of the round-robin distribution.

<P> This is often an issue for request WATCHing.  The simplest scenario
involves two instances.  When the WATCH report is activated it will be serviced
by the first process, when the request wishing to be WATCHed is accessed it (in
the absence of any other server activity) will be serviced by the other process
and will not be reported by WATCH on the first.

<P> There is no simple solution for this issue as the round-robin distribution
of requests is determined by the network device driver.  When debugging server
or script behaviour often the simplest solution is to temporarily reset to one
the number of instances running on the system.  See
<REFERENCE>(head_server_reports_instances),
<REFERENCE>(head_server_action) and
<REFERENCE>(head_server_instance).

<HEAD1>(Event Categories\head_reports_watch_categories)

<P> An <EMPHASIS>(event) is considered any significant point for which the
server code has a reporting call provided. These have been selected to provide
maximum information with minimum clutter and impact on server performance.
Obvious examples are connection acceptance and closure, request path
resolution, error report generation, network reads and writes, etc. Events are
collected together into groupings to allow clearly defined areas of interest
to be selected for reporting.

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

<COMMENT>(HTML=
<P><CENTER>
<IMG SRC="image.gif" BORDER=0 ALT="[graphic]" ALIGN=bottom>&nbsp;
<A HREF="WATCH.gif" TARGET="_blank">WATCH Selection Graphic</A>
</CENTER>
)

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

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

<P> The report menu provides for the inclusion of any combination of the
following categories.

<HEAD>(Request\head_reports_watch_request)

<LIST>(UNNUMBERED)

<LE> <EMPHASIS>(Processing - \BOLD)
Each major step in a request's progress.  For example, path resolution and
final response status.

<LE> <EMPHASIS>(Header - \BOLD)
Provides the HTTP request header as a section of blank-line terminated text.

<LE> <EMPHASIS>(Body - \BOLD)
The content (if a POST or PUT method) of the request.   This is provided as a
hexadecimal dump on the  left and with printable characters rendered on the
right, 32 bytes per line.

<ENDLIST>

<HEAD>(Response\head_reports_watch_response)

<LIST>(UNNUMBERED)

<LE> <EMPHASIS>(Processing - \BOLD)
Each major step in generating a response to the request. These generally
reflect calls to a major server module such as file CACHE, FILE access,
INDEX-OF, SSI processing, etc. One or more of these events may occur for each
request. For instance a directory listing will show an INDEX-OF call and then
usually a FILE call as any read-me file is accessed.

<LE> <EMPHASIS>(Header - \BOLD)
The blank-line terminated HTTP header to the response. Only server-generated
headers are included. Scripts that provide a full HTTP stream do not have the
header explicitly reported. The response body category must be enabled to
observe these (indicated by a STREAM notation).

<LE> <EMPHASIS>(Body - \BOLD)
The content of the response.   This is provided as a hexadecimal dump on the
left and with printable characters rendered on the right, 32 bytes per line.
Some requests also generate very large responses which will clutter output.
Generally this category would be used when investigating specific request
response body problems.

<ENDLIST>

<HEAD>(General\head_reports_watch_general)

<LIST>(UNNUMBERED)

<LE> <EMPHASIS>(Connection - \BOLD)
Each TCP/IP connection acceptance and closure. The connect shows which service
the request is using (scheme, host name and port).

<LE> <EMPHASIS>(Path Mapping - \BOLD)
This, along with the authorization report, provides one of the most useful
aspects of the WATCH facility. It comprises an event line indicating the path
to be mapped (it can also show a VMS file specification if a
<EMPHASIS>(reverse-mapping) has been requested). Then as each rule is
processed a summary showing current path, match <QUOTE>(Y)/<QUOTE>(N) for each
path template and any conditional, then the result and conditional. Finally an
event entry shows the resulting path, VMS file specification, any script name
and specification resolved. The path mapping category allows the administrator
to directly assess mapping rule processing with live or generated traffic.

<LE> <EMPHASIS>(Authorization - \BOLD)
When authorization is deployed this category shows the rules examined to
determine if a path is controlled, any authentication events in assessing
username and password, and the consequent group, user and request capabilities
(read and/or write) for that path.  No password information is displayed.

<LE> <EMPHASIS>(Error - \BOLD)
The essential elements of a request error report are displayed. This may
include a VMS status value and associated system message.

<LE> <EMPHASIS>(CGI - \BOLD)
This category displays the generated CGI variable names and values as used by
various forms of scripting and by SSI documents, as well as the processing of
the response header returned by scripts.

<LE> <EMPHASIS>(DCL - \BOLD)
Debugging scripts can sometimes present particular difficulties. This category
may help. It reports on all input/output streams with the subprocess
(SYS$INPUT, SYS$OUTPUT, SYS$COMMAND, CGIPLUSIN).

<LE> <EMPHASIS>(DECnet - \BOLD)
For the same reason as above this category reports all DECnet scripting
input/output of the DECnet link. In particular, it allows the observation of
the OSU scripting protocol.

<ENDLIST>

<HEAD>(Network\head_reports_watch_network)

<LIST>(UNNUMBERED)

<LE> <EMPHASIS>(Activity - \BOLD)
For each raw network read and write the VMS status code and size of the I/O is
recorded.

<LE> <EMPHASIS>(Data - \BOLD)
For each raw network read or write the contents are provided as a hexadecimal
dump on the left and with printable characters rendered on the right, 32 bytes
per line.

<ENDLIST>

<HEAD>(Other\head_reports_watch_other)

<LIST>(UNNUMBERED)

<LE> <EMPHASIS>(Match - \BOLD)
Shows a significant level of detail during string matching activities.  May be
useful during mapping, authorization and conditional processing.

<LE> <EMPHASIS>(Logging - \BOLD)
Access logging events include log open, close and flush, as well as request
entries.

<LE> <EMPHASIS>(SSL - \BOLD)
If the Secure Sockets Layer image is in use this category provides a
indication of high-level activity.

<LE> <EMPHASIS>(Quotas - \BOLD)
Display available server process resource quotas with significant events.

<ENDLIST>

<HEAD>(Proxy\head_reports_watch_proxy)

<LIST>(UNNUMBERED)

<LE> <EMPHASIS>(Processing - \BOLD)
Each major step during the serving of a proxied request.

<LE> <EMPHASIS>(Request Header - \BOLD)
The proxy server rebuilds the request originally received from the client. 
This category shows that rebuilt request, the one that is sent to the remote
server.

<LE> <EMPHASIS>(Request Body - \BOLD)
In the case of HTTP POST or PUT methods any request body is displayed.
This is provided as a hexadecimal dump on the left and with printable
characters rendered on the right, 32 bytes per line.

<LE> <EMPHASIS>(Response Header - \BOLD)
The blank-line terminated HTTP header to the response from the remote, proxied
server.

<LE> <EMPHASIS>(Response Body - \BOLD)
The content of the response sent from the remote server. This is provided as a
hexadecimal dump on the left and with printable characters rendered on the
right, 32 bytes per line.

<LE> <EMPHASIS>(Cache - \BOLD)
When proxy caching is enabled this category provides information on cache
reading (serving a request from cache) and cache loading (writing a cache file
using the response from a remote server).  It will provide a reason for any
request or response it does not cache, as well as report errors during file
processing.

<LE> <EMPHASIS>(Cache Maintenance - \BOLD)
This category is not related to request processing.  It allows routine and
reactive cache purging activities to be watched.

<ENDLIST>

<HEAD>(Code Modules\head_reports_watch_codemodules)

<P> If the server has been compiled using the WATCH_MOD=1 macro a set of
module WATCHing statements is included.  These provide far more detailed
processing information than available with the generic WATCH, are intended
primarily for debugging the server during development and testing.  This is
considered a specialized tool, with the quantity and level of detail produced
most likely proving counter-productive in addressing general site configuration
issues.  The module items are shown below the usual WATCH items.

<HEAD1>(Request Filtering\head_reports_watch_filter)

<P> By default all requests to all services are WATCHed. Fine control may be
exercised over exactly which requests are reported, allowing only a selected
portion of all requests being processed to be concentrated on, even on a live
and busy server. This is done by <EMPHASIS>(filtering) requests according the
following criteria.

<LIST>(UNNUMBERED)

<LE> <EMPHASIS>(Client - \BOLD)
The originating host name or address. Unless server DNS host name resolution
is enabled this must be expressed in dotted-decimal notation.

<LE> <EMPHASIS>(Service - \BOLD)
The service connected to. This includes the <EMPHASIS>(scheme) of the service
(i.e. <QUOTE>(http:), <QUOTE>(https:)), the host name (real or virtual), and
the port. The host name is the <EMPHASIS>(official) name of the service as
reported during server startup. As the port number is a essential part of the
service specification it must always be explicitly supplied or wildcarded.

<LE> <EMPHASIS>(Path/Track - \BOLD) Either, the request path, or a specific
track identifier string.  A path may be specified with a leading <QUOTE>(/) for
local paths or if WATCHing proxy requests with a full, or part of a full, URL. 
To WATCH requests associated with a particular access track
(<REFERENCE>(head_log_tracking)) enter the track's unique identifier string 
preceded by a dollar symbol (e.g. <QUOTE>($ORoKJAOef8sAAAkuACc)).

<ENDLIST>

<P> These filters are controlled using fully-specified or wildcarded strings.
Requests that do not match the filter are not reported. In the case of
originating client and destination service, requests are eliminated before ever
appearing in the report. Path and track filtering is slightly different,
requiring some request processing before the target can be determined.
Depending on the categories selected this may result in some events begin
displayed. It will be eliminated, with an accompanying explanatory message, as
soon the path or track identifier has been determined.

<P> The following examples are grouped in the same order as the categories
listed above; client, service and path.

<CODE_EXAMPLE>
  alpha.wasd.dsto.defence.gov.au
  *.wasd.dsto.gov.au  
  131.185.250.202
  131.185.250.*

  beta.wasd.dsto.defence.gov.au:8000
  beta.wasd.dsto.defence.gov.au:*
  http://*
  https:*
  *:80

  /ht_root/src/*
  /cgi-bin/*
  /web/*/cyrillic/*
  $ORoKJAOef8sAAAkuACc
  http://proxied.host.name/*
<ENDCODE_EXAMPLE>

<HEAD1>(Report Format\head_reports_watch_format)

<P> The following example illustrates the format of the WATCH report. It
begins with multi-line heading. The first two record the date, time and
official server name, with underline. The third provides the WASD server
version.  The fourth provides some TCP/IP agent information.  Lines following
can show OpenSSL version (if deployed), system information, server startup
command-line, and then current server process quotas.  The last three lines of
the header provide a list of the categories being recorded, the filters in use,
and the last, column headings described as follows: 

<LIST>(SIMPLE)
<LE> <EMPHASIS>(time\BOLD) the event was recorded
<LE> the <EMPHASIS>(module\BOLD) name of the originating source code
<LE> the <EMPHASIS>(line\BOLD) in the code module
<LE> a unique <EMPHASIS>(item\BOLD) number for each thread being WATCHed
<LE> event <EMPHASIS>(category\BOLD) name
<LE> free-form, but generally interpretable <EMPHASIS>(event\BOLD) data
<ENDLIST>

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

<COMMENT>(HTML=
<P><CENTER>
<IMG SRC="image.gif" BORDER=0 ALT="[graphic]" ALIGN=bottom>&nbsp;
<A HREF="WATCHreport.gif" TARGET="_blank">WATCH Report Graphic</A>
</CENTER>
)

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

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

<P> Note that some items also include a block of data. The request header
category does this, providing the blank-line terminated text comprising the
HTTP header. Rule mapping also provides a block of information representing
each rule as it is interpreted. Generally WATCH-generated information can be
distinguished from other data by it's uniform format and delimiting vertical
bars. Initiative and imagination is sometimes required to interpret the
free-form data but a basic understanding of HTTP serving and a little
consideration is generally all that is required to deduce the essentials
of any report.

<CODE_EXAMPLE><LITERAL>
  29-MAY-2003 08:54:59  WATCH REPORT  wasd.dsto.defence.gov.au:80
  ---------------------------------------------------------------
  HTTPd-WASD/8.3.0 OpenVMS/AXP SSL (26-MAY-2003 08:07:52.96)
  Compaq TCPIP$IPC_SHR V5.3-18 (29-MAR-2002 05:01:04.60)
  OpenSSL 0.9.7b 10 Apr 2003 (12-APR-2003 09:31:08.21)
  $ CC (V7.3-1/60590001) /DECC /STAND=RELAXED_ANSI /PREFIX=ALL /OPTIMIZE /NODEBUG /WARNING=(NOINFORM,DISABLE=(PREOPTW)) /DEFINE=(WASD_VMS_V6,SESOLA,WATCH_CAT=1,WATCH_MOD=1)
  AlphaServer 1200 5/533 4MB with 1 CPU and 256MB running VMS V7.3-1 (ODS-5 enabled, VMS NAML, VMS FIB)
  $ HTTPD /PRIORITY=4 /SYSUAF=ID/PROFILE/PERSONA
  AST:1993/2000 BIO:1996/2000 BYT:671728/749424 DIO:1000/1000 ENQ:451/500 FIL:291/300 PGFL:472336/500000 PRC:0/100 TQ:97/100
  DCL Scripting: detached, as HTTP$NOBODY, PERSONA enabled
  Process: HTTPd:80 HT_ROOT:[STARTUP]STARTUP_SERVER.COM;5 HT_ROOT:[LOG_SERVER]WASD_20030520094358.LOG;1
  Instances: WASD::HTTPd:80
  Watching: connect, request, req-header, response, res-header, error (603)
  Client: "" Service: "" Path: ""
  |Time_______|Module__|Line|Item|Category__|Event...|
  |08:55:06.74 NET      1839 0001 CONNECT    ACCEPTED wasd,49846 on http://131.185.30.1:80 BG5372:|
  |08:55:06.75 REQUEST  1751 0001 REQ-HEADER HEADER 608 bytes|
  GET /web/colloquia/ HTTP/1.1
  Host: wasd.dsto.defence.gov.au
  User-Agent: Mozilla/5.0 (X11; U; OpenVMS AlphaServer_1200_5/533_4MB; en-US; rv:1.3) Gecko/20030313
  Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,video/x-mng,image/png,image/jpeg,image/gif;q=0.2,*/*;q=0.1
  Accept-Language: en-us,en;q=0.5
  Accept-Encoding: gzip,deflate,compress;q=0.9
  Accept-Charset: ISO-8859-1,utf-8;q=0.7,*;q=0.7
  Keep-Alive: 300
  Connection: keep-alive
  Referer: http://wasd.dsto.defence.gov.au/home.html
  If-Modified-Since: Fri, 10 Nov 2000 06:33:58 GMT
  Cache-Control: max-age=0
  
  |08:55:06.75 NET      1313 0001 CONNECT    VIRTUAL wasd.dsto.defence.gov.au:80|
  |08:55:06.75 REQUEST  2701 0001 REQUEST    GET /web/colloquia/|
  |08:55:06.75 CACHE    0466 0001 RESPONSE   CACHE search 8EE655F806C11A98E0B51D52FFE5B269|
  |08:55:06.77 CACHE    0712 0001 RESPONSE   CACHE revalidate WEB:[COLLOQUIA]INDEX.HTML;|
  |08:55:06.77 CACHE    0717 0001 RESPONSE   CACHE hit volatile WEB:[COLLOQUIA]INDEX.HTML;|
  |08:55:06.77 NET      2167 0001 RES-HEADER HEADER 249 bytes|
  HTTP/1.0 200 OK
  Server: HTTPd-WASD/8.3.0 OpenVMS/AXP SSL
  Date: Wed, 28 May 2003 23:25:06 GMT
  Last-Modified: Fri, 10 Nov 2000 06:33:58 GMT
  Content-Type: text/html; charset=ISO-8859-1
  Content-Length: 1596
  Connection: Keep-Alive
  Keep-Alive:
  
  |08:55:06.77 REQUEST  0682 0001 REQUEST    STATUS 200 rx:608 tx:1845 bytes 0.0208 seconds|
  |08:55:06.77 REQUEST  0326 0001 CONNECT    KEEP-ALIVE wasd,49846|
  |08:55:12.84 NET      2027 0001 CONNECT    CLOSE wasd,49846|
  |08:55:29.46 end|
<ENDLITERAL><ENDCODE_EXAMPLE>
 
<HEAD1>(Usage Suggestions\head_reports_watch_suggestions)

<P> The following provides a brief explanation on the way WATCH operates and
any usage implications.

<P> A single client may be connected to the WATCH facility at any given time.
When connecting the client is sent an HTTP response header and the WATCH
report heading lines.  The request then remains connected until the WATCH
duration expires or the client overtly aborts the connection.  During this
period the browser behaves as if receiving a sometimes very slow, sometimes
stalled, plain-text document.  As the server processes WATCHable events the
text generated is sent to the WATCH-connected client.

<P> If the connection is aborted by the user some browsers will consider
document retrieval to be incomplete and attempt to reconnect to the service if
an attempt is made to print or save the resulting document. As the printing of
WATCH information is often quite valuable during problem resolution this
behaviour can result in loss of information and generally be quite annoying.
Appropriate use of the duration selector when requesting a report can work
around this, as at expiry the <EMPHASIS>(server) disconnects, browsers
generally interpreting this as legitimate end-of-document (when no
content-length has been specified).

<P> During report processing some browsers may not immediately update the
on-screen information to reflect received data without some application
activity. If scroll-bars are present on the document window manipulating
either the horizonal or vertical slider will often accomplish this. Failing
that minimizing then restoring the application will usually result in the most
recent information being visible.

<P> Browser <EMPHASIS>(reload/refresh) may be used to restart the report. A
browser will quite commonly attempt to remain at the current position in the
document, which with a WATCH report's sustained but largely indeterminate data
stream may take some time to reach. It is suggested the user ensure that any
vertical scroll-bar is at the beginning of the current report, then refresh
the report.

<P> Selecting a large number of categories, those that generate copious output
for a single event (e.g. response body) or collecting for extended periods
can all result in the receipt of massive reports. Some browsers do not cope
well with documents megabytes in size.

<NOTE>
WATCH reports are written using blocking I/O. This means when large bursts of
data are being generated (e.g. when WATCHing network data, response bodies,
etc.) significant granularity may be introduced to server processing.  Also if
the WATCH client fails or blocks completely server processing could halt
completely!  (This has been seen when WATCHing through a firewall.)
<ENDNOTE>

<P> <EMPHASIS>(When supplying WATCH output as part of a problem report\BOLD)
please ZIP the file and include it an an e-mail attachment.  Mailers often
mangle the report format making it difficult to interpret.

<HEAD1>(Command-Line Use\head_reports_watch_cli)

<P> Although intended primarily as a tool for online use WATCH can be deployed
at server startup with a command-line qualifier and provide report output to
the server process log. This is slightly more cumbersome than the Web
interface but may still be useful in some circumstances. Full control over
event categories and filters is possible.

<LIST>(UNNUMBERED)

<LE> <EMPHASIS>(/NOWATCH\BOLD) Disables the use of the online WATCH facility.

<LE> <EMPHASIS>(/WATCH=\BOLD) Enables the server WATCH facility, dumping to
standard output (and the server process log if detached).  When in effect the
online facility is unavailable.  The string supplied to the qualifier may
comprise four comma-separated components.  Only the first is manadatory.
Stated order is essential.  It will probably be necessary to enclose the
complete string in quotation marks.

<LIST>(UNNUMBERED)

<LE><EMPHASIS>(LIST - \BOLD)
The LIST keyword provides a list of all the categories (items) available for
WATCHing.

<LE><EMPHASIS>(NOSTARTUP - \BOLD)
This keyword suppresses WATCH output until the server is ready to process
requests.  It must be the leading keyword.

<LE><EMPHASIS>(<EMPHASIS>(items) - \BOLD)
A parenthesized, comma-separated list of category keywords.  Available keywords
can be displayed using the LIST facility.

<LE><EMPHASIS>(<EMPHASIS>(filters) - \BOLD)
A client, service and path filters can be provided following the specification
of required items.  They must be provided in the order listed above.  Leading
filters that are not required must be provided as single, asterisk wildcards. 
WATCH parameter with filters containing forward-slashes will require quoting.

<ENDLIST>

<ENDLIST>

<P> The following examples illustrate the command-line WATCH specification.

<CODE_EXAMPLE>
  /NOWATCH
  /WATCH=NOSTARTUP,ITEMS=(REQUEST,RESPONSE,MAPPING)
  /WATCH="ITEMS=(REQUEST,RESPONSE,ERROR),*,*,/cgi-bin/*"
  /WATCH=LIST
<ENDCODE_EXAMPLE>

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