      VMS Notes for Info-ZIP Zip 3.0 and UnZip 6.0
      ============================================

   This document describes some VMS-specific behavior and implementation
details of the Info-ZIP Zip and Unzip programs.

   Last modified: 2004-12-13.


   Building UnZip
   --------------

   Some of the standard code in UnZip 6 will misbehave when the off_t
type (declared in DECC$TYPES.H or STAT.H) is unsigned.  This seems to be
true on VAX using GNU C, VAX C, or older versions of DEC C.  UnZip
senses this condition at run time, and complains:

      NEXTBYTE macro failed.  Try compiling with ALT_NEXTBYTE defined?

   If this happens, the current work-around is to re-build UnZip,
defining the C macro ALT_NEXTBYTE.  This may be done using the MMK/MMS
macro LOCAL_UNZIP, or the LOCAL_UNZIP symbol with BUILD_UNZIP.COM.  For
example:

      $ mms /des = [.vms] /MACRO = (MMS$ARCH_NAME=VAX, VAXC=1) clean
      $ mms /des = [.vms] /MACRO = -
       (MMS$ARCH_NAME=VAX, VAXC=1, "LOCAL_UNZIP=ALT_NEXTBYTE")
or:
      $ LOCAL_UNZIP == "ALT_NEXTBYTE"
      $ @ [.vms]BUILD_UNZIP.COM VAXC


   Building with the LIST option using MMK or MMS
   ----------------------------------------------

   Currently, building with MMK or MMS using the LIST option (as in
"/MACRO = LIST=1") may cause a failure for some old versions of the DEC
C compiler.  The LIST option currently adds "/show = (all, nomessages)"
to the CC command line, and some old DEC C compilers do not support the
"nomessages" keyword.  When VAX C is used, this keyword is omitted, but
the builder does not distinguish between the various DEC/Compaq/HP C
versions.  The work-arounds are to use BUILD_[UN]ZIP.COM, or edit
[.VMS]DESCRIP_SRC.MMS to remove the troublesome keyword.


   Command-line Case
   -----------------

   Zip and UnZip now include code which can preserve the case of
command-line parameters and options, which obviates quoting upper-case
options like "-V" or "-Z".  This works on non-VAX systems with a
sufficiently recent C RTL, and SET PROCESS /PARSE_STYLE = EXTENDED.
(Sufficiently recent here means __CRTL_VER >= 70301000, which includes
VMS V7.3-1 with a C Run Time Library ECO, or V7.3-2 or newer.)   This
code uses the decc$feature_set_value() function to enable the DEC
C$ARGV_PARSE_STYLE feature.  There is a small range of C RTL versions
where this function is unavailable, but where manually setting the
logical name DECC$ARGV_PARSE_STYLE to "ENABLE" will work.   HELP CRTL
leads to some additional information on these features.


   File I/O Performance
   --------------------

   When compiled using DEC/Compaq/HP C (not GNU C or VAX C), the Zip and
UnZip file I/O code now includes open callback functions which are used
to try to set some RMS parameters to non-default values, with the
intention of improving file I/O speed.  This affects reading an archive
file in UnZip and writing one in Zip.  (Reading and writing the
individual data files is handled in more exotic ways, making these
parameters less important for them.)

   Currently, the built-in default parameters enable read-ahead and
write-behind, using a multi-buffer count of 2, and a multi-block count
of 127 (the maximum).  For writing the archive, the default extend
quantity is 16384 blocks (8MB), with truncation enabled.  This
combination is believed to be, at worst, fairly harmless for most
situations, and, in most cases, to provide a substantial speed
improvement, especially with large archives.

   This code allows SET RMS_DEFAULT parameters to override the built-in
default values.  On some old VMS versions, sys$getjpi() can not provide
the SET RMS_DEFAULT values, and in this situation, the callback function
will not try to use its improved parameter values.  Users on such old
VMS versions who seek improved I/O speed may wish to bypass this check,
which requires changing the code in the get_rms_defaults() function in
[.VMS]VMS.C.  The "-v" option on both programs enables diagnostic
messages which show the operation of the callback function.  A message
showing a failure status from sys$getjpi() indicates this problem.

   Sample results (UnZip shown, Zip similar):

   VMS VAX V5.4, VAX C.  Callback code disabled, no messages:
      WIMP $ UNZIP.EXE -vt TESTMAKE.ZIP
      Archive:  SYS$SYSDEVICE:[UTILITY.SOURCE.ZIP.UNZIP60C]TESTMAKE.ZIP;1
      [...]

   VMS VAX V5.5-2, DEC C.  SYS$GETJPI() fails (%SYSTEM-F-BADPARAM):
      WEAK $ exec UNZIP.EXE -vt TESTMAKE.ZIP
      Get RMS defaults.  getjpi sts = %x00000014.
      Archive:  DUA1:[UTILITY.SOURCE.ZIP.UNZIP60C]TESTMAKE.ZIP;1
      [...]

   VMS VAX V7.3, DEC/Compaq C.  Callback code works:
      WUSS $ unzip6c -tv TESTMAKE.ZIP
      Get RMS defaults.  getjpi sts = %x00000001.
                     Default: deq =      0, mbc =   0, mbf =   0.
      Open callback.  ID = 1, deq =  16384, mbc = 127, mbf =   2.
      Archive:  ALP$DKA0:[UTILITY.SOURCE.ZIP.UNZIP60C]TESTMAKE.ZIP;1
      [...]

   VMSV5.5-2 is too old.  V7.3 is new enough.  Anyone with more precise
information is invited to contribute it.

   Users who find other parameter sets more beneficial, or who find
particular problems with this set are welcome to comment.

   In this version, as in previous versions, when UnZip expands a -V
archive, it allocates the entire extent of a data file before writing
any of its data.  In previous versions, this could cause the destination
disk to be locked for a considerable time (minutes).  Now, the FAB
"sequential access only" flag (or equivalent) is set, which prevents
this troublesome disk locking.

   In previous versions, when UnZip expanded a non-V archive, it did no
pre-allocation, and used the default extension quantity.  This could
slow file creation significantly for large files.  Now, space for
extracted files is pre-allocated, and the same "sequential access only
"flag is set, as with a -V archive.


   GNU C
   -----

   Zip and UnZip have been built using GNU C (VAX) version 2.3, mostly
for fun, but serious users are encouraged to report any interest in
continuing this activity.  The GNU C 2.3 header files were missing some
things, including definitions of SEEK_CUR, SEEK_END, and SEEK_SET.  The
VMS-specific code now expects to find unixio.h and unixlib.h, which were
absent from the GNU C 2.3 distribution.

   To work around these difficulties, the Zip and UnZip kits include
some emergency replacement unixio.h and unixlib.h files which appear to
work for these programs, at least.  To install them, use commands like
the following:

      COPY [.VMS]UNIXIO_GCC.H GNU_CC_INCLUDE:[000000]UNIXIO.H
      COPY [.VMS]UNIXLIB_GCC.H GNU_CC_INCLUDE:[000000]UNIXLIB.H
      SET PROTECTION W:RE GNU_CC_INCLUDE:[000000]UNIXIO.H, UNIXLIB.H

   There may be an error in the GNU C header file ATRDEF.H which can
cause Zip to fail, when making a "-V" archive, with a spurious "could
not open for reading" error message, followed by more bad behavior.  It
probably also causes trouble of some kind in UnZip.  To check the
questionable macro definition, use a command like the following:

      SEARCH GNU_CC_INCLUDE:[000000]ATRDEF.H ATR$S_JOURNAL

This should show something equivalent to this:

      #define ATR$S_JOURNAL           0x001

If you see "0x002" (or equivalent) instead of "0x001" (or equivalent),
then this value must be corrected in the file before building Zip or
UnZip.

   You may also see several warnings from the compiler caused by other
defects in the GNU C header files, such as:

<various>: warning: passing arg 4 of `qsort' from incompatible pointer type

[...]rab.h:134: warning: unnamed struct/union that defines no instances
[...]rab.h:143: warning: unnamed struct/union that defines no instances      

These warnings appear to be harmless.

