1 VMS Notes for Info-ZIP Zip 3.0 and UnZip 6.0 2 ============================================ 3 4 This document describes some VMS-specific behavior and implementation 5details of the Info-ZIP Zip and UnZip programs. 6 7 Last modified: 2009-03-02. 8 9 10 Command-line Case 11 ----------------- 12 13 Zip and UnZip now include code which can preserve the case of 14command-line parameters and options, which obviates quoting upper-case 15options like "-V" or "-Z". This works on non-VAX systems with a 16sufficiently recent C RTL, and SET PROCESS /PARSE_STYLE = EXTENDED. 17(Sufficiently recent here means __CRTL_VER >= 70301000, which includes 18VMS V7.3-1 with a C Run Time Library ECO, or V7.3-2 or newer.) This 19code uses the decc$feature_set_value() function to enable the 20DECC$ARGV_PARSE_STYLE feature. There is a small range of C RTL versions 21where this function is unavailable, but where manually setting the 22logical name DECC$ARGV_PARSE_STYLE to "ENABLE" will work. HELP CRTL 23leads to some additional information on these features. 24 25 26 File Name Case (ODS5) 27 --------------------- 28 29 In general, Zip 3.0 and UnZip 6.0 should handle file name case (and 30extended file names) in reasonable ways on ODS5 disks. 31 32 Zip offers a variety of "-C" (/PRESERVE_CASE) options to control how 33case is handled when adding files to an archive. The default settings 34("-C2-", /PRESERVE_CASE = NOODS2, down-case ODS2 file names; "-C5", 35/PRESERVE_CASE = ODS5, preserve case of ODS5 file names) should be 36consistent with previous Zip versions for files on ODS2 disks, and 37reasonable for files on ODS5 disks. 38 39 UnZip should preserve case when it extracts to an ODS5 destination 40disk (unless "-2" (/ODS2) is specified). (Note that previous UnZip 41versions, including version 5.52, did not properly preserve case for 42directories, which were always up-cased.) 43 44 The Zip and UnZip builders should work properly on ODS2 and ODS5 45disks, with old (pre-ODS5) and new (case-conscious) versions of MMS (or 46MMK). All testing was done with SET PROCESS /CASE_LOOKUP = BLIND. 47Various problems may be expected with /CASE_LOOKUP = SENSITIVE. 48 49 For consistency, the builders should always create product files 50(.OBJ, .EXE, .HLB, and so on) with upper-case names, whether the build 51is done on an ODS2 or ODS5 disk. Note, however, that in a world with 52both ODS2 and ODS5 disks, and old and new Zip and UnZip versions, it's 53possible to encounter lower-case product file names. For example, a VMS 54binary kit could be created on an ODS2 disk, and a Zip archive created 55from that (using Zip 2.x, or Zip 3.x with default settings). Such a Zip 56archive would contain down-cased names for those product files, and 57those lower-case names would then normally be preserved when UnZip was 58used to extract that archive onto an ODS5 destination. Normally, things 59will work regardless of such case changes, but there may be some 60untested combinations of unexpected name cases and quirky MMS (or MMK) 61behavior, where something goes wrong. Complaints are always welcome, 62but it may not be possible to get everything to work as expected with 63every version of VMS, MMS (or MMK), Zip, and UnZip, on every file 64system. 65 66 It might help matters if _all_ VMS binary kits were produced on ODS5 67disks, and packaged using (case-preserving) Zip version 3.x, but this 68would certainly be different from the way things have been done before, 69and maintaining control over this process is essentially impossible. 70 71 72 Symbolic Links (ODS5) 73 --------------------- 74 75 VMS V8.3 offers support for symbolic links (symlinks) on ODS5 disks. 76In previous Zip and UnZip versions, the generic code for symlinks was 77disabled, and there was no VMS-specific code for symlinks. Now, by 78default, Zip and UnZip attempt to support symlinks wherever the C 79headers and C run-time library include the functions needed for symlink 80support. This means non-VAX systems with __CRTL_VER >= 70301000, so 81this includes VMS V7.3-1 and up, and thus symlink-capable Zip and UnZip 82programs may be built on systems which do not themselves offer symlink 83support. (Various run-time failures may be expected if symlinks are 84encountered on pre-V8.3 systems, either in a file system or in a Zip 85archive.) 86 87 Symlink support can be disabled at build-time, if desired, by 88defining the C macro NO_SYMLINKS. (See comments in the builder 89regarding LOCAL_UNZIP or LOCAL_ZIP, as appropriate.) For example, using 90MMS to build UnZip: 91 92 MMS /DESCRIP = [.VMS] /MACRO = ("LOCAL_UNZIP=NO_SYMLINKS=1") 93 94or, using the command procedure to build Zip: 95 96 LOCAL_ZIP == "NO_SYMLINKS=1" 97 @ [.VMS]BUILD_ZIP.COM 98 DELETE /SYMBOL /GLOBAL LOCAL_ZIP 99 100 The Zip or UnZip "-v" (/VERBOSE) report should include 101SYMLINK_SUPPORT (Zip) or SYMLINKS (UnZip) in its list of "special 102compilation options" if the program was built with symlink support. 103 104 105 File I/O Performance 106 -------------------- 107 108 When compiled using DEC/Compaq/HP C (not GNU C or VAX C), the Zip and 109UnZip file I/O code now includes access callback functions which are 110used to try to set some RMS parameters to non-default values, with the 111intention of improving file I/O speed. This affects reading an archive 112file in UnZip and writing one in Zip. (Reading and writing the 113individual data files are handled in more exotic ways, making these 114parameters less important for them.) 115 116 Currently, the built-in default parameters enable read-ahead and 117write-behind, using a multi-buffer count of 2, and a multi-block count 118of 127 (the maximum). For writing the archive, the default extend 119quantity is 16384 blocks (8MB), with truncation enabled. This 120combination is believed to be, at worst, fairly harmless for most 121situations, and, in most cases, to provide a substantial speed 122improvement, especially with large archives. 123 124 This code allows SET RMS_DEFAULT parameters to override the built-in 125default values. On some old VMS versions, sys$getjpi() can not provide 126the SET RMS_DEFAULT values, and in this situation, the callback function 127will not try to use its improved parameter values. Users on such old 128VMS versions who seek improved I/O speed may wish to bypass this check, 129which requires changing the code in the get_rms_defaults() function in 130[.VMS]VMS.C. The "-vv" (/VERBOSE = MORE) option on both programs 131enables diagnostic messages which show the operation of the callback 132function. A message showing a failure status from sys$getjpi() 133indicates this problem. 134 135 Sample results (UnZip shown, Zip similar): 136 137 VMS VAX V5.4, VAX C. Callback code disabled, no messages: 138 WIMP $ unzip -tvv TESTMAKE.ZIP 139 Archive: SYS$SYSDEVICE:[UTILITY.SOURCE.ZIP.UNZIP60C]TESTMAKE.ZIP;1 140 [...] 141 142 VMS VAX V5.5-2, DEC C. SYS$GETJPI() fails (%SYSTEM-F-BADPARAM): 143 WEAK $ unzip -tvv TESTMAKE.ZIP 144 Get RMS defaults. getjpi sts = %x00000014. 145 Archive: DUA1:[UTILITY.SOURCE.ZIP.UNZIP60C]TESTMAKE.ZIP;1 146 [...] 147 148 VMS VAX V7.3, DEC/Compaq C. Callback code works: 149 WUSS $ unzip -tvv TESTMAKE.ZIP 150 Get RMS defaults. getjpi sts = %x00000001. 151 Default: deq = 0, mbc = 0, mbf = 0. 152 Open callback. ID = 1, deq = 16384, mbc = 127, mbf = 2. 153 Archive: ALP$DKA0:[UTILITY.SOURCE.ZIP.UNZIP60C]TESTMAKE.ZIP;1 154 [...] 155 156 VMSV5.5-2 is too old. V7.3 is new enough. Anyone with more precise 157information is invited to contribute it. 158 159 Users who find other parameter sets more beneficial, or who find 160particular problems with this set are welcome to comment. 161 162 In this version, as in previous versions, when UnZip expands a -V 163archive, it allocates the entire extent of a data file before writing 164any of its data. In some previous versions, this could cause the 165destination disk to be locked for a considerable time (minutes), if 166highwater marking was enabled on that disk. Now, the FAB SQO 167("sequential access only") flag (or equivalent) is set, which prevents 168this troublesome disk locking. 169 170 In some previous versions, when UnZip expanded a non-V archive, it 171did no pre-allocation, and used the default extension quantity. This 172could slow file creation significantly for large files. Now, space for 173extracted files is pre-allocated, and the same SQO ("sequential access 174only") flag is set, as with a -V archive. 175 176 177 Changes to the "-V" (/VMS) Option 178 --------------------------------- 179 180 The intent of the "-V" (/VMS) option was to store VMS file attributes 181in a Zip archive, allowing UnZip to extract an exact copy of a file on a 182VMS system, including all its VMS attributes. 183 184 In Zip before version 2.31, using the "-V" (/VMS) option created an 185archive which usually contained data from beyond the EOF (End-of-File) 186marker in a data file, but generally not all the disk blocks allocated 187for the file. When extracted on a VMS system, the result was usually 188acceptable (because the data from beyond the EOF marker were usually 189ignored). However, when extracted on a non-VMS system, the resulting 190file was usually corrupted by being NUL-padded to the next larger 16KB 191multiple in size. 192 193 Now (Zip 2.31 and later), with "-V" (/VMS), Zip truncates a data file 194at EOF, and portable-format files (Stream_LF, fixed-512) should be 195extracted properly on a non-VMS system. On a VMS system, well-formed 196files (that is, those with no valid data beyond EOF) should also be 197restored correctly. 198 199 With the new "-VV" (/VMS = ALL) option, the archive includes all 200allocated blocks for the file (including those beyond EOF). When 201extracted on a VMS system, the original file should be reproduced with 202as much fidelity as possible, but on a non-VMS system, most files will 203be seen as corrupt because of the data from beyond EOF. 204 205 206 Changes to Program Exit Status Values 207 ------------------------------------- 208 209 Zip and UnZip exit with 32-bit VMS status values which are formed 210from their internal OS-independent status values. In previous program 211versions, this was done by converting the internal success code (0) into 212%x00000001 (SS$_NORMAL), and converting the other internal warning and 213error codes using an artificial control/facility code, 0x7FFF (which 214includes some reserved bits), and a severity value which was determined 215according to rules specified in the VMS-specific exit function. 216Curiously, the internal status codes were left-shifted by 4 bits instead 217of 3, so all the resulting VMS message codes (bits 13:3) were even. 218 219 Zip and UnZip now have facility names and codes assigned by HP 220(UnZip: IZ_UNZIP, 1954; Zip: IZ_ZIP, 1955). Now, by default, the 221programs exit with standard 32-bit VMS status values which differ from 222the old ones in several ways: The official facility code is used, and 223the facility-specific bit is set. (For compatibility with older 224versions, the internal status codes are still left-shifted by 4 bits. 225This also makes it easier to extract the internal status code from a 226hexadecimal representation of the VMS status code.) The builders also 227create non-executable message files (UNZIP_MSG.EXE and ZIP_MSG.EXE) so 228that, after a suitable SET MESSAGE command, the program messages will be 229available from DCL. For example: 230 231 $ SET MESSAGE dev:[dir]ZIP_MSG.EXE 232 $ ZIP FRED.ZIP no_such_file 233 zip warning: name not matched: no_such_file 234 235 zip error: Nothing to do! 236 (dev:[dir]FRED.ZIP;) 237 238 ALP $ WRITE SYS$OUTPUT F$MESSAGE( $STATUS) 239 %IZ_ZIP-W-NONE, Nothing to do 240 241The message files may be copied into SYS$MESSAGE to make them generally 242available, although this could cause some confusion if multiple versions 243of the programs are used on the system, and their error message source 244files differ. Each different destination directory will get its own 245UNZIP_MSG.EXE or ZIP_MSG.EXE ([.ALPHA], [.ALPHAL], [.VAX], and so on), 246but all of the same-architecture files are equivalent to each other. 247That is, on an Alpha system, any of the [.ALPHA*]ZIP_MSG.EXE files could 248be used; on an IA64 system, any of the [.IA64*]ZIP_MSG.EXE files could 249be used; and on a VAX system, any of the [.VAX*]ZIP_MSG.EXE files could 250be used. (Similar for UNZIP_MSG.EXE, of course.) 251 252 If desired, the programs may be built to use the old exit status values 253by defining a C macro with the old facility value: 254"CTL_FAC_IZ_UNZIP=0x7FFF" (UnZip) or "CTL_FAC_IZ_ZIP=0x7FFF" (Zip). 255(See comments in the builder regarding LOCAL_UNZIP or LOCAL_ZIP, as 256appropriate.) This will maintain compatibility with older program 257versions, but will make the programs incompatible with the new error 258message files. 259 260 261 VMS File Attribute Schemes 262 -------------------------- 263 264 Zip's "-V" (/VMS) option causes VMS file attributes to be stored in 265an archive. Since Zip version 2.2 (released in 1996), Zip has, by 266default, stored VMS file attributes using a scheme ("PK") which is 267compatible with the one used by PKWARE in their PKZIP product. Before 268that, a different scheme ("IM") was used. UnZip versions before 5.2 269support only the older IM scheme, but since UnZip version 5.2, both 270schemes have been supported by UnZip. 271 272 The IM scheme has not been well tested recently, but it is still 273available. Some problems were seen when the IM scheme was used with 274symbolic links on VMS V8.3. Details on how build Zip to use the IM 275scheme instead of the PK scheme are included in comments in the main 276builder files. Look for VMS_IM_EXTRA in [.VMS]BUILD_ZIP.COM or IM in 277[.VMS]DESCRIP.MMS. 278 279 The "special compilation options" section of a "zip -v" ("zip 280/verbose") report should show either VMS_PK_EXTRA or VMS_IM_EXTRA, 281according to how Zip was built. 282 283 284 UTC Date-Times 285 -------------- 286 287 Zip archives traditionally include local (MS-DOS compatible) 288date-time information for files. Since Zip version 2.1, it has also 289been possible to store UTC date-time information in the archive, and 290since UnZip version 5.2, UnZip has been able to use this UTC date-time 291information when extracting files. 292 293 On VMS, support in the C run-time environment for UTC became 294available with VMS V7.0. UTC support in Zip and UnZip is automatically 295enabled at compile time, if it is available on the system where the code 296is compiled (__CRTL_VER >= 70000000). It may be disabled at compile 297time by defining the C macro NO_EF_UT_TIME. Details on how build Zip 298and UnZip with additional C macros defined are included in comments in 299the main builder files. Look for LOCAL_[UN]ZIP in 300[.VMS]BUILD_[UN]ZIP.COM or in [.VMS]DESCRIP.MMS. For example, using MMS 301to build UnZip: 302 303 MMS /DESCRIP = [.VMS] /MACRO = ("LOCAL_UNZIP=NO_EF_UT_TIME=1") 304 305or, using the command procedure to build Zip: 306 307 LOCAL_ZIP == "NO_EF_UT_TIME=1" 308 @ [.VMS]BUILD_ZIP.COM 309 DELETE /SYMBOL /GLOBAL LOCAL_ZIP 310 311 The "special compilation options" section of a "zip -v" ("zip 312/verbose") or "unzip -v" ("unzip /verbose") report should show 313USE_EF_UT_TIME if the program was built with UTC support. 314 315 316 Building with the LIST option using MMK or MMS 317 ---------------------------------------------- 318 319 Currently, building with MMK or MMS using the LIST option (as in 320"/MACRO = LIST=1") may cause a failure for some old versions of the DEC 321C compiler. The LIST option currently adds "/show = (all, nomessages)" 322to the CC command line, and some old DEC C compilers do not support the 323"nomessages" keyword. When VAX C is used, this keyword is omitted, but 324the builder does not distinguish between the various DEC/Compaq/HP C 325versions. The work-arounds are to use BUILD_[UN]ZIP.COM, or edit 326[.VMS]DESCRIP_SRC.MMS to remove the troublesome keyword. 327 328 329 GNU C 330 ----- 331 332 Zip and UnZip have been built using GNU C (VAX) version 2.3, mostly 333for fun, but serious users are encouraged to report any interest in 334continuing this activity. The GNU C 2.3 header files were missing some 335things, including definitions of SEEK_CUR, SEEK_END, and SEEK_SET. The 336VMS-specific code now expects to find unixio.h and unixlib.h, which were 337absent from the GNU C 2.3 distribution. 338 339 To work around these difficulties, the Zip and UnZip kits include 340some emergency replacement unixio.h and unixlib.h files which appear to 341work for these programs, at least. To install them, use commands like 342the following: 343 344 COPY [.VMS]UNIXIO_GCC.H GNU_CC_INCLUDE:[000000]UNIXIO.H 345 COPY [.VMS]UNIXLIB_GCC.H GNU_CC_INCLUDE:[000000]UNIXLIB.H 346 SET PROTECTION W:RE GNU_CC_INCLUDE:[000000]UNIXIO.H, UNIXLIB.H 347 348 There may be an error in the GNU C header file ATRDEF.H which can 349cause Zip to fail, when making a "-V" archive, with a spurious "could 350not open for reading" error message, followed by more bad behavior. It 351probably also causes trouble of some kind in UnZip. To check the 352questionable macro definition, use a command like the following: 353 354 SEARCH GNU_CC_INCLUDE:[000000]ATRDEF.H ATR$S_JOURNAL 355 356This should show something equivalent to this: 357 358 #define ATR$S_JOURNAL 0x001 359 360If you see "0x002" (or equivalent) instead of "0x001" (or equivalent), 361then this value must be corrected in the file before building Zip or 362UnZip. 363 364 You may also see several warnings from the compiler caused by other 365defects in the GNU C header files, such as: 366 367<various>: warning: passing arg 4 of `qsort' from incompatible pointer type 368 369[...]rab.h:134: warning: unnamed struct/union that defines no instances 370[...]rab.h:143: warning: unnamed struct/union that defines no instances 371 372These warnings appear to be harmless. 373