[next] [previous] [contents] [full-page]4.1 - Source Archive, Object Module Archives
4.2 - ODS-5 Volumes
4.3 - Installation DCL Procedure
4.4 - Update DCL Procedure
4.5 - Quick-Check
4.6 - Re-Linking
4.7 - VMS 5.5-2
4.8 - Local Setup Suggestions
4.9 - Organizing Documents
4.10 - Reporting Problems
The WASD package and updates will always be distributed as ZIP archives.
It generally pays to use the latest version of VMS UNZIP available.
Archives will contain a comment about the minimum version required, check that
as described in the next paragraph. To show the version of the current UNZIP
utility, use
$ UNZIP -v
The ZIP archive will contain brief installation instructions. Use the
following command to read this and any other information provided.
$ UNZIP -z device:[dir]archive.ZIP
It is recommended to check the integrity of, then list the contents of, the
archive before UNZIPping.
$ UNZIP -t device:[dir]archive.ZIP
$ UNZIP -l device:[dir]archive.ZIP
Installation UNZIP
For complete package distributions the archive will contain the complete
directory tree. Hence to install or do a complete update it is necessary to
SET DEFAULT into the top-level directory of the disk the package is to
be installed on.
$ SET DEFAULT device:[000000]
A complete installation/update will have the structure:
Archive: HT_ROOT:[000000]HTROOT430.ZIP;1
WASD (HFRD) VMS Hypertext Services, Copyright (c) 1996,1997 Mark G.Daniel.
This package (all associated programs), comes with ABSOLUTELY NO WARRANTY.
This is free software, and you are welcome to redistribute it
under the conditions of the GNU GENERAL PUBLIC LICENSE, version 2.
* Complete v4.3.0 package.
* $ SET DEFAULT device:[000000]
* $ UNZIP "-V" device:[dir]HTROOT430.ZIP
VMS file attributes saved ... use UnZip 5.n+ on OpenVMS
Archive created 1-AUG-1997
Length Date Time Name
------ ---- ---- ----
0 07-30-97 14:15 ht_root/$_read_1st/
0 07-30-97 14:15 ht_root/aacrt060/
0 07-30-97 14:15 ht_root/auth/
0 07-30-97 14:15 ht_root/axp/
5360 07-30-97 13:23 ht_root/changes.html
0 07-30-97 14:15 ht_root/doc/
.
.
.
16896 07-30-97 09:23 ht_root/vax/wwwrkout.exe
------ -------
19109754 996 files
Update UNZIP
For updates to portions of the package only the tree below HT_ROOT:[000000]
is provided, hence it is necessary to SET DEFAULT to HT_ROOT:[000000] before
UNZIPping.
$ SET DEFAULT HT_ROOT:[000000]
An update will have the structure:
Archive: HT_ROOT:[000000]HTROOT430_UPD_01.ZIP;1
WASD (HFRD) VMS Hypertext Services, Copyright (c) 1996,1997 Mark G.Daniel.
This package (all associated programs), comes with ABSOLUTELY NO WARRANTY.
This is free software, and you are welcome to redistribute it
under the conditions of the GNU GENERAL PUBLIC LICENSE, version 2.
* Mostly minor updates to scripts and utilities for the v4.3.0 package.
* A couple nuisance-value-bugs have also been fixed in these.
* SDM2HTM can now generate <FRAMESET> documents (see [DOC]*.COM)
VMS file attributes saved ... use UnZip 5.n+ on OpenVMS
Archive created 6-AUG-1997
Length Date Time Name
------ ---- ---- ----
42957 08-04-97 07:57 src/utils/wwwrkout.c
59664 08-04-97 07:57 src/utils/obj_axp/wwwrkout.obj
19674 08-04-97 07:57 src/utils/obj_vax/wwwrkout.obj
26624 08-04-97 07:57 axp/wwwrkout.exe
.
.
.
45056 08-05-97 11:02 vax/sdm2htm.exe
617 08-05-97 09:23 doc/all_docs_framed.com
44 08-05-97 09:23 doc/all_docs_not_framed.com
544 08-05-97 09:22 doc/readme.html
------ -------
2773107 90 files
Existing Installations
When installing either a full archive or to a lesser extent an update archive "over the top" of an existing installation consider the following.
$ BACKUP HT_ROOT:[000000...] location:HTROOT.BCK/SAVE/VERIFY $ ZIP "-V" location:HTROOT.ZIP device:[HT_ROOT...]*.* $ ZIP "-T" location:HTROOT.ZIPIf using ZIP then ensure that a previous version of the target ZIP file does not already exist. If it does then that version is updated, a new version is not created.
$ SET DEFAULT device:[000000] $ UNZIP "-V" device:[dir]archive-AXP.ZIP ht_root/src/httpd/obj_axp/*.*
The complete package, source code, documentation, examples, etc., is provided in a single main archive. Installation and other build procedures allow the entire package to be compiled and linked from this if prefered. This requires a later version of DEC C (preferably v5.n or greater). VAX C is no longer supported.
In addition, for those unable or not wishing to fully build the distribution, two other platform-specific archives are available, AXP (Alpha) and VAX, containing a complete set of object modules, allowing the package to be built via a link operation only.
If a complete build is planned then only the main archive is required. If
a link-only build then an additional archive for each architecture must be
UNZIPped as described above. This applies to both full installations and
subsequent updates. The archives will be clearly identified with the
architecture type, as illustrated in this example.
$ UNZIP "-V" device:[dir]archive-AXP.ZIP
$ UNZIP "-V" device:[dir]archive-VAX.ZIP
NOTE
The WASD distribution and package organisation fully supports mixed-architecture clusters (both AXP and VAX in the one cluster) as one integrated installation.
The WASD server has been successfully installed on and used from ODS-5
(extended file specification) volumes. Note that the installation procedures
and file system organisation of the package tree has been designed for ODS-2
compliance. As long as this is maintained there should be no issues with
actually having it resident on an extended file system compliant volume. (Of
course the issue of installing WASD on an ODS-5 volume is completely separate
from it's ability to serve the contents of an ODS-5 volume!)
4.3 - Installation DCL Procedure
The INSTALL.COM procedure assists with the first installation of WASD. It provides a vanilla setup, using the standard directories and account environment described in this document. All sections prompt before performing any action and default to "no". Read the questions carefully!
It performs the following tasks:
After UNZIPping the package do the following:
$ SET DEFAULT device:[HT_ROOT]
$ @INSTALL
NOTE
The installation procedure provides a reasonable, vanilla, single-node set-up. If something different is required a little time and thought may be required further configuring startup, etc.
Support files to consider when customizing startup, etc. (see 5.2 - Account Support Files for further detail):
NOTE
When using WASD's SSL functionality TWO consecutive updates will need to be performed. First, the update of the basic WASD package, immediately followed by an update of the SSL components (see 14.4 - SSL Quick-Start).
The UPDATE.COM procedure assists with subsequent updates of WASD. It assumes a vanilla setup, using the standard directories and account environment described in this document. All sections prompt before performing any action and default to "no". Read the questions carefully!
It provides the following functions:
CAUTION!
Of course it is best (read mandatory) for the server to be shut down during an update!
After UNZIPping the updated package do the following:
$ SET DEFAULT HT_ROOT:[000000]
$ @UPDATE
Post-Update
When confident regarding the success of the update (these activities can be part of the update DCL procedure).
$ SET DEFAULT HT_ROOT:[000000] $ @UPDATEAFTER
Once installed or updated it is possible to check the basic package at any
time using the
FREEWARE_DEMO.COM
procedure. Follow the displayed instructions.
@device:[HT_ROOT]FREEWARE_DEMO
Problem? SYSTEM-F-SHRIDMISMAT? See next section!
4.6 - Re-Linking
After an update to the operating system the package may refuse to start,
reporting a message like:
%DCL-W-ACTIMAGE, error activating image WHAT$EVER
-CLI-E-IMGNAME, image file DKA0:[SYS0.SYSCOMMON.][SYSLIB]WHAT$EVER_SHR.EXE
-SYSTEM-F-SHRIDMISMAT, ident mismatch with shareable image
This implies the executables require re-linking for your particular version
of VMS. This can be accomplished quite simply, perform the linking section
only of the update DCL procedure, 4.4 - Update DCL Procedure.
4.7 - VMS 5.5-2
WASD is only officially supported for VMS V6.0 or greater. However it has been known to successfully build and run under V5.5-2. It will, in all probability, require the AACRTL060 kit (which is part of DECC for this version of VMS, or can be obtained and installed separately).
One issue was a difficulty in using the CGI-BIN logical. This was isolated
to the hyphen it contains and resolved by changing the definition of this in
STARTUP.COM, using instead "CGI-BIN". This is now the default for the
example startup procedure, allowing both 5.5-2 and later VMS versions to
function correctly.
4.8 - Local Setup Suggestions
Package updates will never contain anything in these three directories:
To prevent the overwriting of local configuration files it is suggested these be placed in the HT_ROOT:[LOCAL] directory. Startup files will most probably be placed where-ever the local site manages system startup. These could be placed in the HT_ROOT:[LOCAL] directory if there is nowhere more appropriate. Authentication databases could also be placed in the [LOCAL] directory. The server account's support files (LOGIN.COM, etc.) may be copied from the HT_ROOT:[EXAMPLE] directory into HT_ROOT:[HTTP$SERVER] and customized as necessary.
In like manner, local DCL scripts or DCL wrappers for executable scripts should be placed in HT_ROOT:[SCRIPT_LOCAL]. Executables should continue to be placed in HT_EXE:
Changes that are made in package configuration files, etc., can then be
propagated to the local areas as appropriate.
4.9 - Organizing Documents
It is recommended that the server distribution tree and any document and
other Web-specific data areas be kept separate and distinct. The former in
HT_ROOT:[000000], the latter in something like WEB:[000000].
This logical device could be provided with the following DCL introduced into
the server startup procedures:
$ DEFINE /SYSTEM /TRANSLATION=CONCEALED WEB DSA811:[WEB.]
The logical organisation of served data is largely hierarchical, organised under the Web-server path root, and is achieved via two mechanisms.
WASD has a single section of the file system for the core Web files, such as the Division home page, help areas, Web documentation, etc., it can be accessed using the logical device WEB:[000000]. Incorporated with this are other subdirectories providing storage for specific collections of data, such as committee minutes, administration announcements, etc.
Physically distinct areas are used for good physical reasons (e.g. the area can best be hosted on a task-local disk), for historical reasons (e.g. the area existed before any Web environment existed) or for reasons of convenience (e.g. lets put this where access controls already allow the maintainers to manage it).
Reasons for an area being physically integrated with the core Web data
area can be legitimate (e.g. there is really nowhere else it reasonably
belongs), convenience (e.g. let's quickly put it here) or by logical necessity
(it really does below as part of the core Web enviroment, e.g. documentation
on HTML, etc.)
Guidelines
In general, only Web-related files need to go into the core physical Web file area. All other groupings should, if possible, be decentralised into the portion of the file system they represent and logically placed in the server's path using rules in the mapping file. That is, a given project's Web files should be located in the project's part of the file system. If it doesn't have any then it may be a candidate for location in the core area.
When locating a Web area in a physically distinct area it is possible the maintainers of that data will already have the correct access controls. If locating an area in the core hypertext environment it will be necessary to give the mantainer ownership of the directory area (and possibly disk quota), or provide ACL access if multiple maintains are involved.
When locating Web-accessable data in a physically distinct area it will be
necessary to update the mapping file with a new rule (see
10 - Mapping Rules). If located within the core Web area the
rules do not need to be adjusted.
4.10 - Reporting Problems
This package, as is generally the case with freeware, is mainly developed and supported outside of the author's main occupation and working hours. Reports of problems and bugs (while not necessarily welcome :^), as well as general queries, are responded to as soon as practicable. If the documentation is inaccurate or could benefit from clarification in some area please advise of this also (the better the documentation the less queries you have to field personally ... or so the theory goes).
With all reports please include the version of the server or script, and the hardware platform, operating system and TCP/IP package and version in use.
If a server error message is being generated please examine the HTML source of the error page. The "<META...>" information contains version information as well as valuable source code module and line information. Include this with the report.
If the server is exiting with a server-generated error message this information also contains module and line information. Please include this with the report.
The WATCH facility (see 16 - WATCH Facility) is often a powerful tool for problem investigation. It is also very useful when supplying details during problem resolution. When supplying WATCH output as part of a problem report please ZIP the file and include it an an e-mail attachment. Mailers often mangle the report format making it difficult to interpret.
Image crash dumps may also be generated, although these are of less value than the case of the previous two.
Reports may be e-mailed to
Mark.Daniel@wasd.vsm.com.au.au
Should the above address present problems or provide no response for an
extended period then use
Mark.Daniel@dsto.defence.gov.au