unzip/vms/INSTALL.VMS

  VMS (OpenVMS):

     On VMS, two build methods are provided: a command procedure, and
     description files for MMS or MMK.  Both methods must be run from
     the main 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
     the main builder file, either BUILD_UNZIP.COM or DESCRIP.MMS.

     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 LINK
          @ [.VMS]BUILD_UNZIP LARGE LINK
       or
          MMK /DESC = [.VMS] CLEAN_EXE  ! Deletes existing executables.
          MMK /DESC = [.VMS]            ! Builds 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)

     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 the relevant builder file
     explain the command-line options used to select a different
     compiler.

     By default, Zip uses (and UnZip supports) the "deflate" compression
     method.  To add support for the optional "bzip2" compression method,
     first obtain and build the bzip2 software (http://www.bzip.org/ or,
     for a more VMS-friendly kit, http://antinode.info/dec/sw/bzip2.html).
     Then, 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_4B_VMS]
     or:
          MMS /DESC = [.VMS] /MACRO = (LARGE=1, -
           IZ_BZIP2=SYS$SYSDEVICE:[UTILITY.SOURCE.BZIP2.BZIP2-1_0_4B_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_4B_VMS]
     or:
          MMS /DESC = [.VMS] /MACRO = (LARGE=1, "CCOPTS=/NAMES=AS_IS", -
           IZ_BZIP2=SYS$SYSDEVICE:[UTILITY.SOURCE.BZIP2.BZIP2-1_0_4B_VMS])

     System-architecture-specific files (like objects and executables)
     are placed in separate directories, such as [.ALPHA], [.IA64], or
     [.VAX].  Large-file products get their own directories, [.ALPHAL]
     or [.IA64L].  On VAX, VAX C products are placed in [.VAXV], GNU C
     products in [.VAXG].  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 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.

  Completing 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, most users 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 text 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 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 a 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.