            UnZip Installation Supplement for VMS (OpenVMS)
            -----------------------------------------------

   UnZip version 6.10.  Revised: 2013-01-11.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

      Source Kits
      -----------

   UnZip source kits are distributed as Zip archives and tar+gzip kits.
A Zip archive is usually the more convenient form for a VMS user.  If an
UnZip program is not already available on the target system, pre-built
UnZip programs may be found in many freeware collections, and on the
Info-ZIP server:

      ftp://ftp.info-zip.org/pub/infozip/vms/

   To unpack the UnZip source kit, choose a suitable working directory,
and UnZip the UnZip kit there.  For example:

      SET DEFAULT dev:[dir.unzip]       ! Some convenient directory.
      UNZIP unzip61.zip                 ! Unpack the UnZip source kit.

If the UnZip kit is elsewhere, specify its actual location:

      UNZIP dn_ld_dev:[dn_ld_dir]unzip61.zip


   Some optional UnZip features may require additional source kits.

   o Bzip2 Compression

     By default, UnZip can use the Deflate compression method.  To add
     support for the optional "bzip2" compression method, obtain and
     build the bzip2 software ("http://www.bzip.org/" or, for a more
     VMS-friendly kit, "http://antinode.info/dec/sw/bzip2.html").  The
     build instructions below explain how to use the appropriate bzip2
     header files and object library to build UnZip with bzip2 support.

   o Encryption

     This UnZip release includes the Traditional encryption code
     ("CRYPT") previously supplied in the separate package zcrypt29.zip,
     but you still can decide whether to activate the CRYPT code or not.
     CRYPT is enabled by default, but you may disable it by specifying
     the C macro "NO_CRYPT" in the LOCAL_UNZIP symbol/macro (explained
     below).  See README_CR.txt for more on CRYPT.

     This UnZip release offers optional support for Advanced Encryption
     Standard (AES) encryption, which is a stronger encryption method
     than Traditional Zip encryption.  A separate IZ_AES_WG source kit
     is required to enable this AES encryption option.  See
     README_AES_WG.txt for more on the optional AES encryption.  The
     IZ_AES_WG source kit must be unpacked in the UnZip source
     directory, where it creates a [.aes_wg] subdirectory.  File and
     path names may vary, but commands like the following should extract
     the IZ_AES_WG source kit in the right place:

        SET DEFAULT [.unzip61]          ! The main UnZip source dir.
        UNZIP [-]iz_aes_wg.zip          ! Unpack the IZ_AES_WG kit.

     The IZ_AES_WG code may be too modern for VAX C.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

      Building
      --------

   On VMS, two build methods are provided: a DCL command procedure, and
description files for MMS or MMK.  Both methods must be run from the
main source directory, not the [.VMS] subdirectory.

   A simple build using the command procedure looks like this:
      @ [.VMS]BUILD_UNZIP.COM

   A simple build using MMS or MMK looks like this:
     MMS /DESCRIP = [.VMS]DESCRIP.MMS   ! Or, with MMK, ...
     MMK /DESCRIP = [.VMS]DESCRIP.MMS

   Various options for each build method are explained in comments in
each main builder file, either [.VMS]BUILD_UNZIP.COM or
[.VMS]DESCRIP.MMS.

   On VAX, the builders attempt to cope with the various available C
compilers, DEC/Compaq/HP C, VAX C, or GNU C.  If DEC/Compaq/HP C is not
available or not desired, comments in each main builder file explain the
command-line options used to select a different compiler.

      Note that on non-VAX systems with VMS V7.2 or later (and with a
      sufficiently new C compiler), UnZip 6.0 (and later) can support
      files (both data files and Zip archives) larger than 2GB.  For the
      greatest compatibility with previous UnZip versions, by default,
      the builders create old-style, small-file programs.  The user must
      specify the appropriate builder command-line option to create
      large-file-capable programs.

   Here are some more complex build examples:

   o Build with the large-file option enabled (non-VAX only):

        @ [.VMS]BUILD_UNZIP LARGE
     or:
        MMS /DESC = [.VMS] /MACRO = LARGE=1

   o Re-link the executables (small-file and large-file):

        @ [.VMS]BUILD_UNZIP NOCOMPILE
        @ [.VMS]BUILD_UNZIP LARGE NOCOMPILE
     or
        MMK /DESC = [.VMS] CLEAN_EXE  ! Delete existing executables.
        MMK /DESC = [.VMS]            ! Build new executables.
        MMK /DESC = [.VMS] /MACRO = LARGE=1 CLEAN_EXE
        MMK /DESC = [.VMS] /MACRO = LARGE=1

   o Build a large-file product from scratch, for debug, getting
     compiler listings and link maps:

        MMS /DESC = [.VMS] CLEAN
        MMS /DESC = [.VMS] /MACRO = (DBG=1, LARGE=1. LIST=1)

   o Bzip2 Compression

      We assume that bzip2 has been built according to its own
      instructions.  To build UnZip with bzip2 support, define the macro
      IZ_BZIP2 on the BUILD_UNZIP.COM or MMS/MMK command line to specify
      the directory where the bzip2 files may be found.  For example:

         @ [.VMS]BUILD_UNZIP LARGE -
          IZ_BZIP2=SYS$SYSDEVICE:[UTILITY.SOURCE.BZIP2.BZIP2-1_0_6A_VMS]
      or:
         MMS /DESC = [.VMS] /MACRO = (LARGE=1, -
          IZ_BZIP2=SYS$SYSDEVICE:[UTILITY.SOURCE.BZIP2.BZIP2-1_0_6A_VMS])

      Note that historically, UnZip has been built with the default
      compiler option, /NAMES = UPPERCASE, while bzip2 is normally built
      with /NAMES = AS_IS, to avoid name collisions.  With modern
      compilers, the "#pragma names" directives in [.VMS]BZLIB.H will
      handle these differences without user intervention.  An old
      compiler (for example, DEC C V4.0-000) will emit complaints
      %CC-I-UNKNOWNPRAGMA, and will mishandle the bzip2 library function
      names, which will cause the link to fail.  To solve this problem,
      either build the bzip2 BZ_NO_STDIO object library with /NAMES =
      UPPERCASE, or else build UnZip with /NAMES = AS_IS.  For example:

         @ [.VMS]BUILD_UNZIP LARGE "CCOPTS=/NAMES=AS_IS" -
          IZ_BZIP2=SYS$SYSDEVICE:[UTILITY.SOURCE.BZIP2.BZIP2-1_0_6A_VMS]
      or:
         MMS /DESC = [.VMS] /MACRO = (LARGE=1, "CCOPTS=/NAMES=AS_IS", -
          IZ_BZIP2=SYS$SYSDEVICE:[UTILITY.SOURCE.BZIP2.BZIP2-1_0_6A_VMS])

      The %CC-I-UNKNOWNPRAGMA complaints are still emitted, but the link
      (and the program) should work.

   o Other Optional Compression Methods (LZMA, PPMd)

      LZMA and PPMd compression (new in UnZip version 6.10) are not
      enabled by default, but the required source code is included in
      the UnZip source kit.  To enable LZMA and/or PPMd compression, add
      the appropriate option to the builder command line.  For example:

         @ [.VMS]BUILD_UNZIP LARGE LZMA PPMD
      or:
         MMS /DESC = [.VMS] /MACRO = (LARGE=1, LZMA=1, PPMD=1)

   o Encryption

      By default, Traditional Zip encryption is enabled.  To disable it,
      the C macro NO_CRYPT must be defined at build time.  This can be
      done by adding NO_CRYPT to the LOCAL_UNZIP symbol/macro.  For
      example:

         LOCAL_UNZIP == "NO_CRYPT"
         @ [.VMS]BUILD_UNZIP LARGE
      or:
         MMS /DESC = [.VMS] /MACRO = (LARGE=1, "LOCAL_UNZIP=NO_CRYPT")

      By default, AES encryption is not enabled.  To enable it, first
      download and unpack the separate IZ_AES_WG source kit, as
      explained above.  With the IZ_AES_WG source kit unpacked into its
      [.aes_wg] subdirectory, add the appropriate AES_WG option to the
      builder command line.  For example:

         @ [.VMS]BUILD_UNZIP LARGE AES_WG
      or:
         MMS /DESC = [.VMS] /MACRO = (LARGE=1, AES_WG=1)


   By default, system-architecture-specific files (like objects and
executables) are placed in separate subdirectories, such as [.ALPHA],
[.IA64], or [.VAX].  Large-file products get their own subdirectories,
[.ALPHAL] or [.IA64L].  On VAX, VAX C products are placed in [.VAXV],
GNU C products in [.VAXG].  If desired, the user may specify some other
subdirectory, using the PROD symbol/macro.  For example, to build
large-file programs in a [.ALPHA_LARGE] subdirectory:

         @ [.VMS]BUILD_UNZIP LARGE PROD=ALPHA_LARGE
      or:
         MMS /DESC = [.VMS] /MACRO = (LARGE=1, PROD=ALPHA_LARGE)

This option makes it easier to build multiple UnZip variants with
different options using the same source tree.

   Each product builder announces what the destination directory will be
when it is run.

   Common files, such as the help libraries (UNZIP.HLP for the default
UNIX-like command-line interface, UNZIP_CLI.HLP for the VMS-like
command-line interface), are placed in the main directory.  With a
mixed-architecture VMS cluster, the same main directory on a shared disk
may be used by all system types.  (Using the NOHELP option with
BUILD_UNZIP.COM can keep it from making the same help files repeatedly.)
Building the help files is detailed below.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

      Testing
      -------

   A set of basic UnZip tests can be run using the builders:

      @ [.VMS]BUILD_UNZIP LARGE TEST
   or:
      MMS /DESC = [.VMS] /MACRO = (LARGE=1) TEST

   Specify "LARGE" or not, the same as when building the programs.  (On
VAX, also specify same the compiler option: VAXC, ...)  Other normal
build options are allowed, but not required.  The builders use a DCL
procedure, [.vms]test_unzip.com, to do this job.  This procedure may be
run directly, but it needs to be told where to find the program
executables, so it's normally easier to use one of the builders to run
it, because they know where the executables are stored.  (Which is why
those options which affect the destination directory are required for
TEST.)

   If PPMd compression was enabled, then a separate PPMd test can be run
similarly:

      @ [.VMS]BUILD_UNZIP LARGE TEST_PPMD
   or:
      MMS /DESC = [.VMS] /MACRO = (LARGE=1) TEST_PPMD

   The test procedure leaves its results files in place (for inspection,
as desired).  To clean up after running the tests, use the CLEAN_TEST
target in the MMS/MMK builder, or do the job manually:

      MMS /DESC = [.VMS] CLEAN_TEST
   or:
      DELETE [.TEST_DIR_*...]*.*;*  ! Repeat as needed.
      DELETE TEST_DIR_*.DIR;*

   Note: For its self-extracting archive (SFX) tests, the test procedure
uses SET FILE /ATTRIBUTES to adjust the attributes of the UnZip SFX
executable to match those of the test archive in the UnZip kit
(rfm:stmlf).  Thus, these tests will fail ("%DCL-W-IVQUAL, unrecognized
qualifier - check validity, spelling, and placement \ATTRIBUTES\", ...)
on systems where this command is not available (that is, on VMS versions
before V6.0).  While this kind of attribute adjustment is required for
the test archive (which was created on a non-VMS system), it should not
be needed when creating a self-extracting archive from an archive which
is created on a VMS system, where the archive file attributes should be
more convenient (rfm:fix, mrs=512).

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

      Installation
      ------------

   To complete the installation, the executables may be left in place,
or moved (or copied) to a convenient place.  While other methods (like
DCL$PATH) exist, it is usual to define symbols to make the UnZip
executables available as foreign commands.  These symbol definitions may
be placed in a user's SYS$LOGIN:LOGIN.COM, or in a more central
location, like SYS$MANAGER:SYLOGIN.COM.  Typical symbol definitions
might look like these:

   UNZIP :== $ dev:[dir]UNZIP.EXE       ! UNIX-like command line.
or:
   UNZIP :== $ dev:[dir]UNZIP_CLI.EXE   ! VMS-like command line.

On a non-VAX system, different symbols could be defined for the
small-file and large-file programs.  For example:

   UNZIPS  :== $ dev:[dir.ALPHA]UNZIP.EXE  ! UNZIPS = small-file UnZip.
   UNZIP*L :== $ dev:[dir.ALPHAL]UNZIP.EXE ! UNZIP[L] =large-file UnZip.


   The builders create help library source files, UNZIP.HLP and
UNZIP_CLI.HLP.  These may be incorporated into an existing help library,
or a separate UnZip help library may be created using commands like
these, using either UNZIP.HLP (as shown) or UNZIP_CLI.HLP:

   $ LIBRARY /HELP dev:[dir]existing_library.HLB UNZIP.HLP

   $ LIBRARY /CREATE /HELP UNZIP.HLB UNZIP.HLP

UnZip help may then be accessed from a separate UnZip help library using
a command like:

   $ HELP /LIBRARY = device:[directory]UNZIP.HLB

   For greater ease, the user (or system manager) may define a
HLP$LIBRARY logical name to allow the HELP utility to find the UnZip help
library automatically.  See HELP HELP /USERLIBRARY for more details.
The command procedure [.vms]hlp_lib_next.com may be used to determine
the next available HLP$LIBRARY logical name, and could be adapted to
define a HLP$LIBRARY logical name for an UnZip help library.

   The builders also create VMS message files, UNZIP_MSG.EXE, in the
destination directory with the program executables.  A user may gain DCL
access to the UnZip error messages using a command like:

   $ SET MESSAGE device:[directory]UNZIP_MSG.EXE

For system-wide access, the system manager may move or copy this file to
SYS$MESSAGE, although this could cause some confusion if multiple
versions of UnZip are used on the system, and their error message source
files differ.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

      Self-Extracting Archives
      ------------------------

   The UnZip kit includes a DCL procedure, [.vms]makesfx.com, which is
intended to help make a self-extracting archive from a normal Zip
archive.  Comments in the procedure explain its use.  It uses a DCL
symbol, "UNZIPSFX", to locate the appropriate UNZIPSFX.EXE (or
UNZIPSFX_CLI.EXE) program to use.  Note that, unlike the DCL symbols for
the normal UnZip or Zip programs, this is not a foreign command symbol,
and does not include the "$" prefix.  For example:

      UNZIPSFX == "dev:[dir]UNZIPSFX.EXE"

   The user must define "UNZIPSFX" to point to an UNZIPSFX.EXE program
which is appropriate for the destination architecture, which may differ
from the architecture of the system where the self-extracting archive is
being created.  For example, on an Alpha system, one might create a
self-extracting archive for use on an IA64 system:

      ZIP new_archive.zip [...]
      UNZIPSFX == "utility_root:[ia64l]unzipsfx.exe"
      @ utility:MAKESFX.COM new_archive

   In some cases, the COPY command in makesfx.com may have trouble
("%COPY-W-INCOMPAT, [...] incompatible attributes") if the UNZIPSFX.EXE
program and the Zip archive have different record formats.  SET FILE
/ATTRIBUTES should be able to adjust the record format of one file or
the other to make them compatible.

   By default, the UNZIPSFX.EXE and UNZIPSFX_CLI.EXE programs include
support for only the default Deflate compression method, and for no
form of encryption.  Other, optional compression and/or encryption
methods may be enabled in the SFX programs at build time, and support
for Deflate may be disabled.  See the comments in the main builder files
and the generic INSTALL document for details.

   Building an optimal UnZipSFX executable is more complicated when
optional compression methods will be used (or when the standard method,
Deflate, will not be used).  Ideally, UnZipSFX should be built with only
the required compression methods enabled, but the list of required
compression methods is determined when an archive is created, while the
list of available methods is determined when UnZipSFX is built.  As
always, when creating a self-extracting archive, the resulting
program+archive should be tested (on the target system).  Options like
"-q -t" should be helpful for this.

