home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 9 Archive / 09-Archive.zip / unzip540.zip / vms / unzip_cli.help < prev    next >
Text File  |  1997-09-01  |  15KB  |  488 lines
  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.DOC).
  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); added "Exit_Codes"
  38. .!              subtopic (no version number change).
  39. .!
  40. <INIT>
  41. <MAIN>
  42. UNZIP
  43.  
  44. UnZip is used to extract files compressed and packaged by Zip (see HELP ZIP
  45. for information on ZIP).
  46.  
  47. For a brief help on Zip and Unzip, run each without specifying any
  48. parameters on the command line (or apply the /HELP qualifier).
  49. To get a brief help sceen about the alternate UNIX style command interface,
  50. run each with the -h option applied.
  51.  
  52. UNZIP will list, test, or extract from a ZIP archive.  ZIP archives are commonly
  53. found on MS-DOS systems; a VMS version of ZIP can also be found here.
  54.  
  55. Archive member extraction is implied by the absence of the /SCREEN (-c),
  56. /PIPE (-p), /TEST (-t), /LIST (-l, -v) or /COMMENT (-z) qualifiers (options).
  57. All archive members are processed unless a filespec is provided to
  58. specify a subset of the archive members.
  59. <FORMAT>
  60. UNZIP zipfile [file[,...]] [/qualifiers]
  61.  
  62. .!
  63. <TOPIC>
  64. Parameters
  65.  
  66. <PARAMETER>
  67. zipfile
  68.  
  69. <PTEXT>
  70. File specification for the ZIP archive(s) with optional wildcards. UnZip will
  71. perform actions specified for every zipfile matching the specification.
  72. The default file specification is SYS$DISK:[].ZIP.
  73.  
  74. Note that self-extracting ZIP files are supported; just specify the .EXE
  75. suffix yourself.
  76. <TXETP>
  77.  
  78. <PARAMETER>
  79. file
  80.  
  81. <PTEXT>
  82. An optional comma-separated list of archive members to be processed;
  83. if no list is given, all archive members are processed.  Expressions
  84. may be used to match multiple members.  Expressions should be enclosed
  85. in double-quotes to prevent interpretation by DCL.  Multiple filenames
  86. should be separated by blanks.  Each file specification is similar to
  87. a Unix egrep expression and may contain:
  88.  
  89. <LITERAL>
  90. |*       matches a sequence of 0 or more characters
  91. |?       matches exactly 1 character
  92. |[...]   matches any single character found inside the brackets;
  93. |        ranges are specified by a beginning character,
  94. |        a hyphen, and an ending character.  If a '!' or '^'
  95. |        immediately follows the left bracket, then any character
  96. |        not in the given range is matched.
  97. <LARETIL>
  98. <TXETP>
  99.  
  100. <QUALIFIERS>
  101. <QUALIFIER>
  102. /ZIPINFO
  103.  
  104. /ZIPINFO
  105.  
  106. Displays information about the Zip archive and the files contained therein.
  107. This function used to be provided by a separate ZipInfo program.
  108.  
  109. The following qualifiers may be specified with /ZIPINFO:
  110.  
  111. <LITERAL>
  112. |  /SHORT                 Short UNIX "ls -l" format (default)
  113. |  /MEDIUM                Medium UNIX "ls -l" format
  114. |  /LONG                  Long UNIX "ls -l" format
  115. |  /VERBOSE               Verbose, multi-page format
  116. |  /ONE_LINE              Filenames only, one per line
  117. |  /HEADER                Print header lines
  118. |  /TOTALS                Print totals for files
  119. |  /TIMES                 Print file times in sortable decimal format
  120. |  /[NO]CASE_INSENSITIVE  Match filenames case-insensitively
  121. |  /[NO]PAGE              Page screen output through built-in "more"
  122. <LARETIL>
  123. <QUALIFIER>
  124. /BINARY
  125.  
  126. /BINARY[=KEYWORD]
  127. /NOBINARY (default)
  128.  
  129. Selects conversion to VMS "standard" binary file format, which is
  130. "fixed length 512 byte records, no record attributes".
  131. The optional keywords recognized are:
  132. <LITERAL>
  133. |  AUTO     Automatically extracts files marked as "binary" (rather
  134. |           than "text") in standard VMS binary file format. (default)
  135. |  ALL      Extracts all files in standard VMS binary file format.
  136. |  NONE     Same as /NOBINARY.
  137. <LARETIL>
  138.  
  139. Note that a combination of /BINARY[=AUTO] and /TEXT[=AUTO] is allowed.
  140. (see /TEXT qualifier)
  141. <QUALIFIER>
  142. /BRIEF
  143.  
  144. /BRIEF (default)
  145.  
  146. When used with /LIST, specifies that a brief listing of the archive's
  147. contents is to be displayed.  A brief listing shows the length, date,
  148. time, and file name for the files in the archive.
  149. <QUALIFIER>
  150. /CASE_INSENSITIVE
  151.  
  152. /CASE_INSENSITIVE
  153. /NOCASE_INSENSITIVE (default)
  154.  
  155. Match filenames case-insensitively.  (Good default option under VMS.)
  156. <QUALIFIER>
  157. /COMMENT
  158.  
  159. /COMMENT
  160. /NOCOMMENT
  161.  
  162. Display the archive comment.
  163. <QUALIFIER>
  164. /DIRECTORY
  165.  
  166. /DIRECTORY=directory-spec
  167.  
  168. Specifies the output directory where all the extracted files are to be
  169. placed.
  170. <QUALIFIER>
  171. /EXCLUDE
  172.  
  173. /EXCLUDE=(file[,...])
  174.  
  175. A comma-separated list of files to exclude when extracting files.
  176. If multiple files are specified, the list should be included in
  177. parentheses.
  178.  
  179. <QUALIFIER>
  180. /FRESHEN
  181.  
  182. /FRESHEN
  183. /NOFRESHEN
  184.  
  185. Freshen existing files; replace if newer.  Does not cause any new files to
  186. be created.
  187. <QUALIFIER>
  188. /FULL
  189.  
  190. /FULL
  191.  
  192. When used with /LIST, specifies that a full listing of the archive's
  193. contents is to be displayed.  A full listing shows the length,
  194. compression method, compressed size, compression ratio, date,
  195. time, CRC value, and file name for the files in the archive.
  196. <QUALIFIER>
  197. /HELP
  198.  
  199. /HELP
  200.  
  201. Displays a one-page brief help screen and exits quietly.
  202. <QUALIFIER>
  203. /JUNK
  204.  
  205. /JUNK
  206. /NOJUNK (default)
  207.  
  208. Junk the stored paths (don't recreated the archive's directory
  209. structure.
  210. <QUALIFIER>
  211. /LIST
  212.  
  213. /LIST
  214.  
  215. List the contents of the archive.  /BRIEF and /FULL can be used to
  216. specify the amount of information displayed.  The default is /BRIEF.
  217. <QUALIFIER>
  218. /LOWERCASE
  219.  
  220. /LOWERCASE
  221. /NOLOWERCASE (default)
  222.  
  223. Convert filenames from all-uppercase operating systems to lowercase.  This
  224. option has no effect under VMS.
  225. <QUALIFIER>
  226. /OVERWRITE
  227.  
  228. /OVERWRITE
  229. /NOOVERWRITE
  230.  
  231. The qualifier /OVERWRITE forces overwriting of existing files when extracting.
  232. The negation /NOOVERWRITE results in never overwriting an existing file.
  233. The default action is to prompt for desired action when about to
  234. overwrite an existing file.
  235.  
  236. For VMS, "overwriting" results in the creation of a new version of the file,
  237. unless version numbers are stored in the archive and /VERSION is specified.
  238. <QUALIFIER>
  239. /PAGE
  240.  
  241. /PAGE
  242. /NOPAGE
  243.  
  244. Feed all screen output through the built-in "more" pager.
  245. <QUALIFIER>
  246. /PASSWORD
  247.  
  248. /PASSWORD=decryption-password
  249.  
  250. Specifies a decryption password and prevents UnZip from prompting for
  251. a password in case the specified decryption key was wrong. The supplied
  252. string must be enclosed in double-quotes whenever it contains lowercase
  253. or special characters.
  254. <QUALIFIER>
  255. /PIPE
  256.  
  257. /PIPE
  258.  
  259. Extract files to SYS$OUTPUT with no informational messages.
  260. <QUALIFIER>
  261. /QUIET
  262.  
  263. /QUIET[=SUPER]
  264.  
  265. Perform operations quietly.  The keyword SUPER can be specified to make
  266. operations even more quiet.
  267. <QUALIFIER>
  268. /RESTORE
  269.  
  270. /RESTORE
  271. /NORESTORE
  272.  
  273. Restore file owner and protection settings.
  274. <QUALIFIER>
  275. /SCREEN
  276.  
  277. /SCREEN
  278. /NOSCREEN
  279.  
  280. Extracts matching files to SYS$OUTPUT (the terminal).
  281. <QUALIFIER>
  282. /TEST
  283.  
  284. /TEST
  285. /NOTEST
  286.  
  287. Test archive files.
  288. <QUALIFIER>
  289. /TEXT
  290.  
  291. /TEXT[=KEYWORD]
  292. /NOTEXT (default)
  293.  
  294. Selects conversion to VMS standard text file format.
  295. The optional keywords recognized are:
  296. <LITERAL>
  297. |  AUTO     Automatically extracts files marked as "text" (rather
  298. |           than "binary") in standard VMS text file format. (default)
  299. |  ALL      Extracts all files in standard VMS text file format.
  300. |  NONE     Same as /NOTEXT.
  301. <LARETIL>
  302.  
  303. A similar functionality is available for binary files, see qualifier /BINARY.
  304. <QUALIFIER>
  305. /UPDATE
  306.  
  307. /UPDATE
  308. /NOUPDATE
  309.  
  310. Update existing files; create new ones if needed.
  311. <QUALIFIER>
  312. /VERSION
  313.  
  314. /VERSION
  315. /NOVERSION (default)
  316.  
  317. Retain VMS file version numbers.
  318.  
  319. <TOPIC>
  320. Authors
  321.  
  322. Info-ZIP; currently maintained by Greg Roelofs.  VMS support maintained
  323. by Igor Mandrichenko, Christian Spieler and Hunter Goatley.  Originally
  324. based on a program by Samuel H. Smith.
  325.  
  326. VMS on-line help ported from UNZIP.DOC by Hunter Goatley.
  327.  
  328. <TOPIC>
  329. Exit_Codes
  330.  
  331. On VMS, UnZip's UNIX style exit values are mapped into proper
  332. VMS status codes:
  333. <LITERAL>
  334. |   1                               (success)  normal exit,
  335. |   (0x7fff0000 + 16*UnZip_errnum)  -W- warnings
  336. |   (0x7fff0002 + 16*UnZip_errnum)  -E- normal errors
  337. |   (0x7fff0004 + 16*UnZip_errnum)  -F- fatal errors
  338. <LARETIL>
  339.  
  340. The UnZip error level (or exit code) approximates the exit
  341. codes defined by PKWARE and takes on the following values:
  342. <LITERAL>
  343. |  VMS       UnZip    Type of error
  344. |  severity  errcode
  345. |    -         0      normal; no errors or warnings detected.
  346. |
  347. |    W         1      one or more warning errors were encountered,
  348. |                     but processing completed  successfully  any-
  349. |                     way.   This  includes  zipfiles where one or
  350. |                     more files was skipped  due  to  unsupported
  351. |                     compression  method  or  encryption  with an
  352. |                     unknown password.
  353. |
  354. |    E         2      a generic error in the  zipfile  format  was
  355. |                     detected.   Processing  may  have  completed
  356. |                     successfully anyway;  some  broken  zipfiles
  357. |                     created by other archivers have simple work-
  358. |                     arounds.
  359. |
  360. |    F         3      a severe error in  the  zipfile  format  was
  361. |                     detected.   Processing probably failed imme-
  362. |                     diately.
  363. |
  364. |    F         4      unzip was unable to allocate memory for  one
  365. |                     or  more  buffers during program initializa-
  366. |                     tion.
  367. |
  368. |    F         5      unzip  was  unable  to  allocate  memory  or
  369. |                     unable  to  obtain a tty to read the decryp-
  370. |                     tion password(s).
  371. |
  372. |    F         6      unzip was unable to allocate  memory  during
  373. |                     decompression to disk.
  374. |
  375. |    F         7      unzip  was  unable to allocate memory during
  376. |                     in-memory decompression.
  377. |
  378. |    F         8      [currently not used]
  379. |
  380. |    E         9      the specified zipfiles were not found.
  381. |
  382. |    E         10     invalid options were specified on  the  com-
  383. |                     mand line.
  384. |
  385. |    E         11     no matching files were found.
  386. |
  387. |    F         50     the disk is (or was) full during extraction.
  388. |
  389. |    F         51     the end of the ZIP archive  was  encountered
  390. |                     prematurely.
  391. |
  392. |    E         80     the user aborted unzip prematurely with con-
  393. |                     trol-C (or similar)
  394. |
  395. |    E         81     no files were found due to unsupported  com-
  396. |                     pression  methods or unsupported decryption.
  397. |                     (If even one additional file is successfully
  398. |                     processed, however, the exit status is 1.)
  399. |
  400. |    E         82     no  files  were  found due to bad decryption
  401. |                     password(s).  This is also the  exit  status
  402. |                     if  no files were found due to a combination
  403. |                     of unsupported  compression  and  bad  pass-
  404. |                     words.   As in the previous case, however, a
  405. |                     single successful file  will  result  in  an
  406. |                     exit status of 1 instead.)
  407. <LARETIL>
  408.  
  409. In addition, there is a compilation option to expand upon this behavior:
  410. An executable compiled with the option RETURN_CODES defined displays
  411. a human-readable explanation of what the error status means.
  412.  
  413. <TOPIC>
  414. UNIX_Options
  415.  
  416. The default action of UnZip is to extract all zipfile entries.  The following
  417. options and modifiers can be provided:
  418.  
  419. <LITERAL>
  420. |  -Z   ZipInfo mode
  421. |  -c   extract files to SYS$OUTPUT (terminal)
  422. |  -f   freshen existing files (replace if newer); create none
  423. |  -h   show brief help screen and exit quietly
  424. |  -l   list archive files (short format)
  425. |  -p   extract files to SYS$OUTPUT; no informational messages
  426. |  -t   test archive files
  427. |  -u   update existing files; create new ones if needed
  428. |  -v   list archive files (verbose format)
  429. |  -z   display only the archive comment
  430. |
  431. |MODIFIERS
  432. |  -a   auto-extract only text files in standard VMS text file format
  433. |  -aa  extract all files as text
  434. |  -b   auto-extract only binary files in VMS fixed 512 bytes records
  435. |  -bb  extract all files as binary VMS fixed 512 byte record files
  436. |  -j   junk paths (don't recreate archive's directory structure)
  437. |  -n   never overwrite existing files; don't prompt
  438. |  -o   OK to overwrite files without prompting
  439. |  -q   perform operations quietly (-qq => even quieter)
  440. |  -C   match filenames case-insensitively
  441. |  -L   convert filenames to lowercase if created on MSDOS, VMS, etc.
  442. |  -P<pwd>  supply decryption password on the command line (insecure!)
  443. |  -M   page output through built-in "more" function
  444. |  -V   retain (VMS) file version numbers
  445. |  -X   restore owner/protection info (may require privileges)
  446. <LARETIL>
  447.  
  448. Note that uppercase options such as -C, -L, -M, -P, -V, -X and -Z must
  449. be specified in quotes.  For example:
  450.  
  451. <LITERAL>
  452. |  $ unzip "-VX" -a zipfile
  453. <LARETIL>
  454.  
  455. <TOPIC>
  456. UNZIP_OPTS_Default
  457.  
  458. UnZip allows to modify its default behaviour by specifying (UNIX style)
  459. option defaults via the UNZIP_OPTS logical name.
  460. For example, the following will cause UnZip to match filenames without regard
  461. to case, restore owner/protection information and perform all operations at
  462. quiet-level 1 by default:
  463.  
  464. <LITERAL>
  465. |  $ define UNZIP_OPTS "-qCX"
  466. <LARETIL>
  467.  
  468. Note that the quotation marks here are required to preserve lowercase options
  469. (opposite of the command-line behavior). To negate a default option on the
  470. command line, add one or more minus  signs before the option letter, in
  471. addition to the leading switch character `-':
  472.  
  473. <LITERAL>
  474. |  $ unzip --ql zipfile
  475. <LARETIL>
  476.  
  477. or
  478.  
  479. <LITERAL>
  480. |  $ unzip -l-q zipfile
  481. <LARETIL>
  482.  
  483. At present it is not possible to decrement an option below zero--that is,
  484. more than a few minuses have no effect.
  485.  
  486. UNZIP_OPTS may be defined as a symbol rather than a logical, but if both
  487. are defined, the logical is used.
  488.