1.! 2.! File: UNZIP_CLI.HELP 3.! 4.! Author: Hunter Goatley 5.! 6.! Date: 12 Jul 94 (orig. UNZIP.RNH, 23 Oct 91) 7.! 8.! Description: 9.! 10.! TPU-processable source file to produce VMS on-line help for 11.! portable UnZip. Adapted from UNZIP.RNH, originally based on 12.! UNZIP.MAN (now UNZIP.TXT). 13.! 14.! To build: 15.! $ EDIT /TPU/NOSECTION/NODISPLAY/COMMAND=CVTHELP.TPU UNZIP_CLI.HELP 16.! $ RUNOFF /OUT=UNZIP.HLP UNZIP_CLI.RNH 17.! $ LIBR /HELP/INSERT libr UNZIP 18.! 19.! Modification history: 20.! 21.! 02-001 Hunter Goatley 12-JUL-1994 16:59 22.! Genesis. 23.! 02-002 Cave Newt 14-JUL-1994 11:36 24.! Fixed /*TEXT options and added/removed various options. 25.! 02-003 Cave Newt 28-JUL-1994 08:54 26.! Removed semicolons from comments and moved /ZIPINFO. 27.! 02-004 Christian Spieler 06-OCT-1995 02:02 28.! Changed to conform to revised .CLD definition. 29.! 02-005 Christian Spieler 06-FEB-1996 02:20 30.! Added description of /HELP qualifier. 31.! 02-006 Christian Spieler 12-MAY-1996 00:50 32.! Some clarifications/cleanups. 33.! 02-007 Christian Spieler 04-MAR-1997 22:25 34.! Added /[NO]CASE_INSENSITIVE to ZipInfo mode; 35.! documented the new /PASSWORD="decryption_key" option. 36.! 02-007 Christian Spieler 22-JUL-1997 22:37 37.! Formatting changes (prevent line wraps); 38.! added "Exit_Codes" subtopic (no version number change). 39.! 02-007 Christian Spieler 28-APR-2000 03:22 40.! Changed references to plaintext UnZip documentation file 41.! into UNZIP.TXT (no version number change). 42.! 02-007 Hunter Goatley 07-Feb-2001 15:43 43.! Reformatted qualifier item headers to show negated form of 44.! option qualifier on separate line (no version number change). 45.! 02-008 Christian Spieler 18-Apr-2001 22:29 46.! Added description for extended functionality of -b option. 47.! 02-009 Christian Spieler 10-Dec-2001 13:37 48.! Added description for new /TRAVERSE_DIRS option. 49.! 02-010 Steven Schweda 28-Jan-2005 16:16:36 50.! Added /TIMESTAMP (-T) qualifier. 51.! 02-010 Christian Spieler 29-Jan-2005 01:50 52.! Completed description of -T qualifier (also for UNIX style). 53.! 02-011 Steven Schweda 14-FEB-2005 20:04 54.! Added /DOT_VERSION (-Y) and /ODS2 (-2) qualifiers. 55.! 02-012 Steven Schweda 07-JUL-2006 01:30 56.! Added /TEXT = STMLF (-s) qualifier. 57.! 02-012 Christian Spieler 04-Mar-2007 14:39 58.! Changed -s qualifier into -S; 59.! updated documentation of UnZip's exit codes. 60.! 03-002 S. Schweda, C. Spieler 09-Jan-2008 03:35 61.! Added documentation of extended /RESTORE=(...) qualifier. 62.! 03-003 S. Schweda, C. Spieler 13-Sep-2008 20:00 63.! Added /EXISTING qualifier. 64.! 65<INIT> 66<MAIN> 67UNZIP 68 69UnZip is used to extract files compressed and packaged by Zip (see HELP ZIP 70for information on ZIP). 71 72For a brief help on Zip and Unzip, run each without specifying any 73parameters on the command line (or apply the /HELP qualifier). 74To get a brief help sceen about the alternate UNIX style command interface, 75run each with the -h option applied. 76 77UNZIP will list, test, or extract from a ZIP archive. ZIP archives are commonly 78found on MS-DOS systems; a VMS version of ZIP can also be found here. 79 80Archive member extraction is implied by the absence of the /SCREEN (-c), 81/PIPE (-p), /TEST (-t), /TIMESTAMP (-T), /LIST (-l, -v) or /COMMENT (-z) 82qualifiers (options). 83All archive members are processed unless a filespec is provided to 84specify a subset of the archive members. 85<FORMAT> 86UNZIP zipfile [file[,...]] [/qualifiers] 87 88.! 89<TOPIC> 90Parameters 91 92<PARAMETER> 93zipfile 94 95<PTEXT> 96File specification for the ZIP archive(s) with optional wildcards. UnZip will 97perform actions specified for every zipfile matching the specification. 98The default file specification is SYS$DISK:[].ZIP. 99 100Note that self-extracting ZIP files are supported; just specify the .EXE 101suffix yourself. 102<TXETP> 103 104<PARAMETER> 105file 106 107<PTEXT> 108An optional comma-separated list of archive members to be processed; 109if no list is given, all archive members are processed. Expressions 110may be used to match multiple members. Expressions should be enclosed 111in double-quotes to prevent interpretation by DCL. Multiple filenames 112should be separated by blanks. Each file specification is similar to 113a Unix egrep expression and may contain: 114 115<LITERAL> 116|* matches a sequence of 0 or more characters 117|? matches exactly 1 character 118|[...] matches any single character found inside the brackets; 119| ranges are specified by a beginning character, a hyphen, 120| and an ending character. If a '!' or '^' immediately 121| follows the left bracket, then any character not in the 122| given range is matched. 123| Hint: To specify a verbatim left bracket '[', the 124| three-character sequence "[[]" has to be used. 125<LARETIL> 126<TXETP> 127 128<QUALIFIERS> 129<QUALIFIER> 130/ZIPINFO 131 132/ZIPINFO 133 134Displays information about the Zip archive and the files contained therein. 135This function used to be provided by a separate ZipInfo program. 136 137The following qualifiers may be specified with /ZIPINFO: 138 139<LITERAL> 140| /SHORT Short UNIX "ls -l" format (default) 141| /MEDIUM Medium UNIX "ls -l" format 142| /LONG Long UNIX "ls -l" format 143| /VERBOSE Verbose, multi-page format 144| /ONE_LINE Filenames only, one per line 145| /HEADER Print header lines 146| /TOTALS Print totals for files 147| /TIMES Print file times in sortable decimal format 148| /[NO]CASE_INSENSITIVE Match filenames case-insensitively 149| /[NO]PAGE Page screen output through built-in "more" 150<LARETIL> 151<QUALIFIER> 152/BINARY 153 154/BINARY[=KEYWORD] 155<NEXT> 156/NOBINARY (default) 157 158Selects conversion to VMS "standard" binary file format for 159extracted files, which is "fixed length 512 byte records, 160no record attributes". When extracting to SYS$OUTPUT (/SCREEN 161or /PIPE qualifier), this qualifier deactivates the default 162"text data" conversion, instead. 163The optional keywords recognized are: 164<LITERAL> 165| AUTO Automatically extracts files marked as "binary" (rather 166| than "text") in standard VMS binary file format. (default) 167| ALL Extracts all files in standard VMS binary file format. 168| NONE Same as /NOBINARY. 169<LARETIL> 170 171Note that a combination of /BINARY[=AUTO] and /TEXT[=AUTO] is allowed. 172(see /TEXT qualifier) 173<QUALIFIER> 174/BRIEF 175 176/BRIEF (default) 177 178When used with /LIST, specifies that a brief listing of the archive's 179contents is to be displayed. A brief listing shows the length, date, 180time, and file name for the files in the archive. 181<QUALIFIER> 182/CASE_INSENSITIVE 183 184/CASE_INSENSITIVE 185<NEXT> 186/NOCASE_INSENSITIVE (default) 187 188Match filenames case-insensitively. (Good default option under VMS.) 189<QUALIFIER> 190/COMMENT 191 192/COMMENT 193<NEXT> 194/NOCOMMENT 195 196Display the archive comment. 197<QUALIFIER> 198/DIRECTORY 199 200/DIRECTORY=directory-spec 201 202Specifies the output directory where all the extracted files are to be 203placed. 204<QUALIFIER> 205/DOT_VERSION 206 207/DOT_VERSION 208<NEXT> 209/NODOT_VERSION (default) 210 211Causes UnZip to treat archived file name endings of ".nnn" (where "nnn" 212is a decimal number) as if they were VMS version numbers (";nnn"). (The 213default is to treat them as file types.) Example: "a.b.3" -> "a.b;3". 214<QUALIFIER> 215/EXCLUDE 216 217/EXCLUDE=(file[,...]) 218 219A comma-separated list of files to exclude when extracting files. 220If multiple files are specified, the list should be included in 221parentheses. 222<QUALIFIER> 223/EXISTING 224 225/EXISTING = keyword 226 227Valid keywords (exactly one must be specified) are: 228<LITERAL> 229| NEW_VERSION Create a new version of an existing file. 230| OVERWRITE Overwrite the same version of an existing file. 231| (But only if the archive member name includes a 232| version number.) 233| NOEXTRACT Do not extract. An existing file is not affected. 234<LARETIL> 235 236When UnZip would extract an archive member, but the destination file 237already exists, UnZip will, by default, ask the user what to do. 238/EXISTING lets the user specify on the command line what to do in this 239situation, eliminating the interactive question(s). 240 241NOEXTRACT will always stop UnZip from extracting an archive member if 242the destination file already exists. 243 244If an archive member name does not include a VMS version number, or if 245UnZip is run with /NOVERSION (the default, causing it to ignore version 246numbers), then either NEW_VERSION or OVERWRITE will cause UnZip to 247create a new version of the existing file. 248 249If an archive member name does include a VMS version number, and if 250UnZip is run with /VERSION, then NEW_VERSION will cause UnZip to create 251a new version of the existing file, and OVERWRITE will cause UnZip to 252overwrite the existing file which has the version specified by the 253archive member name. 254<QUALIFIER> 255/FRESHEN 256 257/FRESHEN 258<NEXT> 259/NOFRESHEN 260 261Freshen existing files; replace if newer. Does not cause any new files to 262be created. 263<QUALIFIER> 264/FULL 265 266/FULL 267 268When used with /LIST, specifies that a full listing of the archive's 269contents is to be displayed. A full listing shows the length, 270compression method, compressed size, compression ratio, date, 271time, CRC value, and file name for the files in the archive. 272<QUALIFIER> 273/HELP 274 275/HELP 276 277Displays a one-page brief help screen and exits quietly. 278<QUALIFIER> 279/JUNK 280 281/JUNK 282<NEXT> 283/NOJUNK (default) 284 285Junk the stored paths (don't recreated the archive's directory 286structure. 287<QUALIFIER> 288/LIST 289 290/LIST 291 292List the contents of the archive. /BRIEF and /FULL can be used to 293specify the amount of information displayed. The default is /BRIEF. 294<QUALIFIER> 295/LOWERCASE 296 297/LOWERCASE 298<NEXT> 299/NOLOWERCASE (default) 300 301Convert filenames from all-uppercase operating systems to lowercase. This 302option has no effect under VMS. 303<QUALIFIER> 304/ODS2 305 306/ODS2 307<NEXT> 308/NOODS2 (default) 309 310Causes UnZip to convert archived file names to ODS2-compatible file 311names (substituting "_" for any invalid characters), regardless of the 312type of the destination file system. 313 314The default is to use ODS5-compatible file names when the destination 315file system is ODS5, and to convert the names to ODS2-compatible names 316when the destination file system is ODS2. 317 318Beginning in UnZip 6.0, ODS2-compatible names are explicitly set to 319upper case. 320<QUALIFIER> 321/OVERWRITE 322 323/OVERWRITE 324<NEXT> 325/NOOVERWRITE 326 327See /EXISTING. 328 329/OVERWRITE is equivalent to /EXISTING = NEW_VERSION. 330<NEXT> 331/NOOVERWRITE is equivalent to /EXISTING = NOEXTRACT. 332<QUALIFIER> 333/PAGE 334 335/PAGE 336<NEXT> 337/NOPAGE 338 339Feed all screen output through the built-in "more" pager. 340<QUALIFIER> 341/PASSWORD 342 343/PASSWORD=decryption-password 344 345Specifies a decryption password and prevents UnZip from prompting for 346a password in case the specified decryption key was wrong. The supplied 347string must be enclosed in double-quotes whenever it contains lowercase 348or special characters. 349<QUALIFIER> 350/PIPE 351 352/PIPE 353 354Extract files to SYS$OUTPUT with no informational messages. 355<QUALIFIER> 356/QUIET 357 358/QUIET[=SUPER] 359 360Perform operations quietly. The keyword SUPER can be specified to make 361operations even more quiet. 362<QUALIFIER> 363/RESTORE 364 365/RESTORE[=(KEYWORD, ...)] 366 367Selects restoration options for some meta-data. 368The optional keywords recognized are: 369<LITERAL> 370| OWNER_PROT Restore file owner and ACL protection settings. 371| NOOWNER_PROT Do not restore file owner and ACL protection settings. 372| NODATE Do not restore any timestamps. 373| DATE=ALL Restore timestamps for all extracted entries, files 374| and directories. 375| DATE=FILES Restore timestamps for extracted files. (default) 376<LARETIL> 377 378By default, VMS UnZip restores the original date-time attributes for files, 379but not for directories. This agrees with the behavior of VMS BACKUP 380(and UnZip versions before 5.52 where the capability to restore directory 381timestamps was added). 382 383For compatibility with UnZip versions before 6.0 (5.53), the following 384obsolete short forms are still accepted: 385<LITERAL> 386| Obsolete form: Modern form: 387| /RESTORE /RESTORE = OWNER_PROT 388| /NORESTORE /RESTORE = NOOWNER_PROT 389<LARETIL> 390<QUALIFIER> 391/SCREEN 392 393/SCREEN 394<NEXT> 395/NOSCREEN 396 397Extracts matching files to SYS$OUTPUT (the terminal). 398<QUALIFIER> 399/TEST 400 401/TEST 402<NEXT> 403/NOTEST 404 405Test archive files. 406<QUALIFIER> 407/TEXT 408 409/TEXT[=(KEYWORD, ...)] 410<NEXT> 411/NOTEXT (default) 412 413Selects conversion to VMS standard text file format. 414The optional keywords recognized are: 415<LITERAL> 416| AUTO Automatically extracts files marked as "text" (rather 417| than "binary") in standard VMS text file format. (default) 418| ALL Extracts all files in standard VMS text file format. 419| NONE Same as /NOTEXT. 420| STMLF Use Stream_LF record format for text files (instead of the 421| default variable-length record format). 422<LARETIL> 423 424A similar functionality is available for binary files, see qualifier /BINARY. 425<QUALIFIER> 426/TIMESTAMP 427 428/TIMESTAMP 429 430Sets the timestamp of an archive to that of its newest file. This qualifier 431corresponds to zip's /APPEND/LATEST (-go) option, but can be applied to 432wildcard zipfile specifications (e.g. "*.zip") and is much faster. 433<QUALIFIER> 434/TRAVERSE_DIRS 435 436/TRAVERSE_DIRS 437<NEXT> 438/NOTRAVERSE_DIRS (default) 439 440Allows to extract archive members into locations outside of the currently 441active "extraction root dir". For security reasons, UnZip normally 442removes "parent dir" path components ("../") from the names of extracted 443files. This feature (new for UnZip 5.50) prevents UnZip from accidentally 444writing files to "sensitive" areas outside the directory tree below the 445specified "extraction root". By specifying the /TRAVERSE_DIRS option, 446this security feature can be switched off. This allows users to extract 447(older) archives that made use of "../" to create multiple directory 448trees at the level of the current extraction folder. 449<QUALIFIER> 450/UPDATE 451 452/UPDATE 453<NEXT> 454/NOUPDATE 455 456Update existing files; create new ones if needed. 457<QUALIFIER> 458/VERSION 459 460/VERSION 461<NEXT> 462/NOVERSION (default) 463 464Retain VMS file version numbers. 465 466<TOPIC> 467Authors 468 469Info-ZIP; currently maintained by Christian Spieler. VMS support maintained 470by Igor Mandrichenko, Steven M. Schweda, Christian Spieler and Hunter Goatley. 471Originally based on a program by Samuel H. Smith. 472 473VMS on-line help ported from UNZIP.TXT by Hunter Goatley. 474 475<TOPIC> 476Exit_Status 477 478On VMS, UnZip's UNIX-style exit values are mapped into VMS-style status 479codes with facility code 1954 = %x7A2, and with the inhibit-message 480(%x10000000) and facility-specific (%x00008000) bits set: 481<LITERAL> 482| %x17A28001 normal exit 483| %x17A28000 + 16*UnZip_error_code warnings 484| %x17A28002 + 16*UnZip_error_code normal errors 485| %x17A28004 + 16*UnZip_error_code fatal errors 486<LARETIL> 487 488Note that multiplying the UNIX-style UnZip error code by 16 places it 489conveniently in the hexadecimal representation of the VMS exit code, 490"__" in %x17A28__s, where "s" is the severity code. For example, a 491missing archive might cause UnZip error code 9, which would be 492transformed into the VMS exit status %X17A28092. 493 494The UnZip VMS exit codes include severity values which approximate those 495defined by PKWARE, as shown in the following table: 496<LITERAL> 497| VMS UnZip err 498| severity code Error description 499| ----------+---------+---------------------------------------------- 500| Success 0 Normal. No errors or warnings detected. 501| Warning 1 One or more warnings were encountered, but 502| processing completed successfully anyway. 503| This includes archives where one or more 504| (but not all) files were skipped because of 505| unsupported compress or encrypt methods, or 506| bad passwords. 507| Error 2 Error in the archive format. Processing may 508| have completed successfully anyway. Some 509| defects in archives (made by other programs) 510| can be repaired transparently. 511| Fatal 3 Severe error in the archive format. Process- 512| ing probably failed immediately. 513| Fatal 4 Memory allocation failed in program initial- 514| ization. 515| Fatal 5 Memory allocation failed in password pro- 516| cessing. 517| Fatal 6 Memory allocation failed while decompressing 518| to disk. 519| Fatal 7 Memory allocation failed while decompressing 520| in memory. 521| Fatal 8 Memory allocation failed (reserved for 522| future use). 523| Error 9 Specified archive files were not found. 524| Error 10 Invalid command-line options or parameters. 525| Error 11 No files matched selection criteria. 526| Fatal 50 Disk full. 527| Fatal 51 Unexpected end-of-file while reading the 528| archive. 529| Error 80 User interrupt (Ctrl/C). 530| Error 81 No files were processed, because of unsup- 531| ported compress or encrypt methods. 532| Error 82 No files were processed, because of bad 533| password(s). 534| Fatal 83 Large-file archive could not be processed by 535| this small-file program. 536<LARETIL> 537 538<TOPIC> 539UNIX_Options 540 541The default action of UnZip is to extract all zipfile entries. The following 542options and modifiers can be provided: 543 544<LITERAL> 545| -Z ZipInfo mode 546| -c extract files to SYS$OUTPUT (terminal) 547| -f freshen existing files (replace if newer); create none 548| -h show brief help screen and exit quietly 549| -l list archive files (short format) 550| -p extract files to SYS$OUTPUT; no informational messages 551| -t test archive files 552| -T set zipfile timestamps to that of each archive's newest entry 553| -u update existing files; create new ones if needed 554| -v list archive files (verbose format) 555| -z display only the archive comment 556| 557|MODIFIERS 558| -a extract text files in standard VMS text file format 559| -aa extract all files as text 560| -b auto-extract only binary files in fixed 512-byte record format 561| -bb extract all files as binary in fixed 512-byte record format 562| -j junk paths (don't recreate archive's directory structure) 563| -n never overwrite or make a new version of an existing file 564| -o always make a new version (-oo: overwrite orig) existing file 565| -q perform operations quietly (-qq => even quieter) 566| -C match filenames case-insensitively 567| -D do not restore any timestamps (--D restore them even for dirs) 568| -L convert filenames to lowercase if created under DOS, VMS, etc. 569| -M feed screen output through built-in "more" pager 570| -P<password> supply decryption password on the cmd line (insecure!) 571| -S use Stream_LF record format to extract text files (with -a[a]) 572| -V retain (VMS) file version numbers 573| -X restore owner/ACL protection info (may require privileges) 574| -Y treat ".nnn" suffix as version number ("a.b.3" -> "a.b;3") 575| -: allow "../" path components to traverse across top extract dir 576| -2 force creation of ODS2-compatible file names 577<LARETIL> 578 579Note that uppercase options such as -C, -D, -L, -M, -P, -S, -T, -V, -X, -Y, 580and -Z must be specified in quotes (unless SET PROC/PARSE=EXTEND is set). 581For example: 582 583<LITERAL> 584| $ unzip "-VX" -a zipfile 585<LARETIL> 586 587<TOPIC> 588UNZIP_OPTS_Default 589 590UnZip allows to modify its default behaviour by specifying (UNIX style) 591option defaults via the UNZIP_OPTS logical name. 592For example, the following will cause UnZip to match filenames without regard 593to case, restore owner/protection information and perform all operations at 594quiet-level 1 by default: 595 596<LITERAL> 597| $ define UNZIP_OPTS "-qCX" 598<LARETIL> 599 600Note that the quotation marks here are required to preserve lowercase options 601(opposite of the command-line behavior). To negate a default option on the 602command line, add one or more minus signs before the option letter, in 603addition to the leading switch character `-': 604 605<LITERAL> 606| $ unzip --ql zipfile 607<LARETIL> 608 609or 610 611<LITERAL> 612| $ unzip -l-q zipfile 613<LARETIL> 614 615At present it is not possible to decrement an option below zero--that is, 616more than a few minuses have no effect. 617 618UNZIP_OPTS may be defined as a symbol rather than a logical, but if both 619are defined, the logical is used. 620