view release on metacpan or  search on metacpan

unzip-6.0/vms/NOTES.TXT  view on Meta::CPAN

   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 access 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 are 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 "-vv" (/VERBOSE = MORE) 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 -tvv 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 $ unzip -tvv 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 $ unzip -tvv 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 some previous versions, this could cause the
destination disk to be locked for a considerable time (minutes), if
highwater marking was enabled on that disk.  Now, the FAB SQO
("sequential access only") flag (or equivalent) is set, which prevents
this troublesome disk locking.

   In some 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 SQO ("sequential access
only") flag is set, as with a -V archive.


   Changes to the "-V" (/VMS) Option
   ---------------------------------

   The intent of the "-V" (/VMS) option was to store VMS file attributes
in a Zip archive, allowing UnZip to extract an exact copy of a file on a
VMS system, including all its VMS attributes.

   In Zip before version 2.31, using the "-V" (/VMS) option created an
archive which usually contained data from beyond the EOF (End-of-File)
marker in a data file, but generally not all the disk blocks allocated
for the file.  When extracted on a VMS system, the result was usually
acceptable (because the data from beyond the EOF marker were usually
ignored).  However, when extracted on a non-VMS system, the resulting
file was usually corrupted by being NUL-padded to the next larger 16KB
multiple in size.

   Now (Zip 2.31 and later), with "-V" (/VMS), Zip truncates a data file
at EOF, and portable-format files (Stream_LF, fixed-512) should be
extracted properly on a non-VMS system.  On a VMS system, well-formed
files (that is, those with no valid data beyond EOF) should also be
restored correctly.

   With the new "-VV" (/VMS = ALL) option, the archive includes all
allocated blocks for the file (including those beyond EOF).  When
extracted on a VMS system, the original file should be reproduced with
as much fidelity as possible, but on a non-VMS system, most files will
be seen as corrupt because of the data from beyond EOF.


   Changes to Program Exit Status Values
   -------------------------------------

   Zip and UnZip exit with 32-bit VMS status values which are formed
from their internal OS-independent status values.  In previous program
versions, this was done by converting the internal success code (0) into
%x00000001 (SS$_NORMAL), and converting the other internal warning and
error codes using an artificial control/facility code, 0x7FFF (which
includes some reserved bits), and a severity value which was determined
according to rules specified in the VMS-specific exit function.
Curiously, the internal status codes were left-shifted by 4 bits instead
of 3, so all the resulting VMS message codes (bits 13:3) were even.

   Zip and UnZip now have facility names and codes assigned by HP
(UnZip: IZ_UNZIP, 1954; Zip: IZ_ZIP, 1955).  Now, by default, the
programs exit with standard 32-bit VMS status values which differ from
the old ones in several ways: The official facility code is used, and
the facility-specific bit is set.  (For compatibility with older
versions, the internal status codes are still left-shifted by 4 bits.
This also makes it easier to extract the internal status code from a