unzip/vms/unzip_cli.help

.!
.!  File:       UNZIP_CLI.HELP
.!
.!  Author:     Hunter Goatley
.!
.!  Date:       12 Jul 94 (orig. UNZIP.RNH, 23 Oct 91)
.!
.!  Description:
.!
.!      TPU-processable source file to produce VMS on-line help for
.!      portable UnZip.  Adapted from UNZIP.RNH, originally based on
.!      UNZIP.MAN (now UNZIP.TXT).
.!
.!      To build:
.!          $ EDIT /TPU/NOSECTION/NODISPLAY/COMMAND=CVTHELP.TPU UNZIP_CLI.HELP
.!          $ RUNOFF /OUT=UNZIP.HLP UNZIP_CLI.RNH
.!          $ LIBR /HELP/INSERT libr UNZIP
.!
.!  Modification history:
.!
.!      02-001          Hunter Goatley          12-JUL-1994 16:59
.!              Genesis.
.!      02-002          Cave Newt               14-JUL-1994 11:36
.!              Fixed /*TEXT options and added/removed various options.
.!      02-003          Cave Newt               28-JUL-1994 08:54
.!              Removed semicolons from comments and moved /ZIPINFO.
.!      02-004          Christian Spieler       06-OCT-1995 02:02
.!              Changed to conform to revised .CLD definition.
.!      02-005          Christian Spieler       06-FEB-1996 02:20
.!              Added description of /HELP qualifier.
.!      02-006          Christian Spieler       12-MAY-1996 00:50
.!              Some clarifications/cleanups.
.!      02-007          Christian Spieler       04-MAR-1997 22:25
.!              Added /[NO]CASE_INSENSITIVE to ZipInfo mode;
.!              documented the new /PASSWORD="decryption_key" option.
.!      02-007          Christian Spieler       22-JUL-1997 22:37
.!              Formatting changes (prevent line wraps);
.!              added "Exit_Codes" subtopic (no version number change).
.!      02-007          Christian Spieler       28-APR-2000 03:22
.!              Changed references to plaintext UnZip documentation file
.!              into UNZIP.TXT (no version number change).
.!      02-007          Hunter Goatley          07-Feb-2001 15:43
.!              Reformatted qualifier item headers to show negated form of
.!              option qualifier on separate line (no version number change).
.!      02-008          Christian Spieler       18-Apr-2001 22:29
.!              Added description for extended functionality of -b option.
.!      02-009          Christian Spieler       10-Dec-2001 13:37
.!              Added description for new /TRAVERSE_DIRS option.
.!      02-010          Steven Schweda          28-Jan-2005 16:16:36
.!              Added /TIMESTAMP (-T) qualifier.
.!      02-010          Christian Spieler       29-Jan-2005 01:50
.!              Completed description of -T qualifier (also for UNIX style).
.!      02-011          Steven Schweda          14-FEB-2005 20:04
.!              Added /DOT_VERSION (-Y) and /ODS2 (-2) qualifiers.
.!      02-012          Steven Schweda          07-JUL-2006 01:30
.!              Added /TEXT = STMLF (-s) qualifier.
.!      02-012          Christian Spieler       04-Mar-2007 14:39
.!              Changed -s qualifier into -S;
.!              updated documentation of UnZip's exit codes.
.!      03-002          S. Schweda, C. Spieler  09-Jan-2008 03:35
.!              Added documentation of extended /RESTORE=(...) qualifier.
.!      03-003          S. Schweda, C. Spieler  13-Sep-2008 20:00
.!              Added /EXISTING qualifier.
.!
<INIT>
<MAIN>
UNZIP

UnZip is used to extract files compressed and packaged by Zip (see HELP ZIP
for information on ZIP).

For a brief help on Zip and Unzip, run each without specifying any
parameters on the command line (or apply the /HELP qualifier).
To get a brief help sceen about the alternate UNIX style command interface,
run each with the -h option applied.

UNZIP will list, test, or extract from a ZIP archive.  ZIP archives are commonly
found on MS-DOS systems; a VMS version of ZIP can also be found here.

Archive member extraction is implied by the absence of the /SCREEN (-c),
/PIPE (-p), /TEST (-t), /TIMESTAMP (-T), /LIST (-l, -v) or /COMMENT (-z)
qualifiers (options).
All archive members are processed unless a filespec is provided to
specify a subset of the archive members.
<FORMAT>
UNZIP zipfile [file[,...]] [/qualifiers]

.!
<TOPIC>
Parameters

<PARAMETER>
zipfile

<PTEXT>
File specification for the ZIP archive(s) with optional wildcards. UnZip will
perform actions specified for every zipfile matching the specification.
The default file specification is SYS$DISK:[].ZIP.

Note that self-extracting ZIP files are supported; just specify the .EXE
suffix yourself.
<TXETP>

<PARAMETER>
file

<PTEXT>
An optional comma-separated list of archive members to be processed;
if no list is given, all archive members are processed.  Expressions
may be used to match multiple members.  Expressions should be enclosed
in double-quotes to prevent interpretation by DCL.  Multiple filenames
should be separated by blanks.  Each file specification is similar to
a Unix egrep expression and may contain:

<LITERAL>
|*       matches a sequence of 0 or more characters
|?       matches exactly 1 character
|[...]   matches any single character found inside the brackets;
|        ranges are specified by a beginning character, a hyphen,
|        and an ending character.  If a '!' or '^' immediately
|        follows the left bracket, then any character not in the
|        given range is matched.
|        Hint: To specify a verbatim left bracket '[', the
|              three-character sequence "[[]" has to be used.
<LARETIL>
<TXETP>

<QUALIFIERS>
<QUALIFIER>
/ZIPINFO

/ZIPINFO

Displays information about the Zip archive and the files contained therein.
This function used to be provided by a separate ZipInfo program.

The following qualifiers may be specified with /ZIPINFO:

<LITERAL>
|  /SHORT                 Short UNIX "ls -l" format (default)
|  /MEDIUM                Medium UNIX "ls -l" format
|  /LONG                  Long UNIX "ls -l" format
|  /VERBOSE               Verbose, multi-page format
|  /ONE_LINE              Filenames only, one per line
|  /HEADER                Print header lines
|  /TOTALS                Print totals for files
|  /TIMES                 Print file times in sortable decimal format
|  /[NO]CASE_INSENSITIVE  Match filenames case-insensitively
|  /[NO]PAGE              Page screen output through built-in "more"
<LARETIL>
<QUALIFIER>
/BINARY

/BINARY[=KEYWORD]
<NEXT>
/NOBINARY (default)

Selects conversion to VMS "standard" binary file format for
extracted files, which is "fixed length 512 byte records,
no record attributes". When extracting to SYS$OUTPUT (/SCREEN
or /PIPE qualifier), this qualifier deactivates the default
"text data" conversion, instead.
The optional keywords recognized are:
<LITERAL>
|  AUTO     Automatically extracts files marked as "binary" (rather
|           than "text") in standard VMS binary file format. (default)
|  ALL      Extracts all files in standard VMS binary file format.
|  NONE     Same as /NOBINARY.
<LARETIL>

Note that a combination of /BINARY[=AUTO] and /TEXT[=AUTO] is allowed.
(see /TEXT qualifier)
<QUALIFIER>
/BRIEF

/BRIEF (default)

When used with /LIST, specifies that a brief listing of the archive's
contents is to be displayed.  A brief listing shows the length, date,
time, and file name for the files in the archive.
<QUALIFIER>
/CASE_INSENSITIVE

/CASE_INSENSITIVE
<NEXT>
/NOCASE_INSENSITIVE (default)

Match filenames case-insensitively.  (Good default option under VMS.)
<QUALIFIER>
/COMMENT

/COMMENT
<NEXT>
/NOCOMMENT

Display the archive comment.
<QUALIFIER>
/DIRECTORY

/DIRECTORY=directory-spec

Specifies the output directory where all the extracted files are to be
placed.
<QUALIFIER>
/DOT_VERSION

/DOT_VERSION
<NEXT>
/NODOT_VERSION (default)

Causes UnZip to treat archived file name endings of ".nnn" (where "nnn"
is a decimal number) as if they were VMS version numbers (";nnn").  (The
default is to treat them as file types.)  Example: "a.b.3" -> "a.b;3".
<QUALIFIER>
/EXCLUDE

/EXCLUDE=(file[,...])

A comma-separated list of files to exclude when extracting files.
If multiple files are specified, the list should be included in
parentheses.
<QUALIFIER>
/EXISTING

/EXISTING = keyword

Valid keywords (exactly one must be specified) are:
<LITERAL>
|  NEW_VERSION   Create a new version of an existing file.
|  OVERWRITE     Overwrite the same version of an existing file.
|                (But only if the archive member name includes a
|                version number.)
|  NOEXTRACT     Do not extract.  An existing file is not affected.
<LARETIL>

When UnZip would extract an archive member, but the destination file
already exists, UnZip will, by default, ask the user what to do.
/EXISTING lets the user specify on the command line what to do in this
situation, eliminating the interactive question(s).

NOEXTRACT will always stop UnZip from extracting an archive member if
the destination file already exists.

If an archive member name does not include a VMS version number, or if
UnZip is run with /NOVERSION (the default, causing it to ignore version
numbers), then either NEW_VERSION or OVERWRITE will cause UnZip to
create a new version of the existing file.

If an archive member name does include a VMS version number, and if
UnZip is run with /VERSION, then NEW_VERSION will cause UnZip to create
a new version of the existing file, and OVERWRITE will cause UnZip to
overwrite the existing file which has the version specified by the
archive member name.
<QUALIFIER>
/FRESHEN

/FRESHEN
<NEXT>
/NOFRESHEN

Freshen existing files; replace if newer.  Does not cause any new files to
be created.
<QUALIFIER>
/FULL

/FULL

When used with /LIST, specifies that a full listing of the archive's
contents is to be displayed.  A full listing shows the length,
compression method, compressed size, compression ratio, date,
time, CRC value, and file name for the files in the archive.
<QUALIFIER>
/HELP

/HELP

Displays a one-page brief help screen and exits quietly.
<QUALIFIER>
/JUNK

/JUNK
<NEXT>
/NOJUNK (default)

Junk the stored paths (don't recreated the archive's directory
structure.
<QUALIFIER>
/LIST

/LIST

List the contents of the archive.  /BRIEF and /FULL can be used to
specify the amount of information displayed.  The default is /BRIEF.
<QUALIFIER>
/LOWERCASE

/LOWERCASE
<NEXT>
/NOLOWERCASE (default)

Convert filenames from all-uppercase operating systems to lowercase.  This
option has no effect under VMS.
<QUALIFIER>
/ODS2

/ODS2
<NEXT>
/NOODS2 (default)

Causes UnZip to convert archived file names to ODS2-compatible file
names (substituting "_" for any invalid characters), regardless of the
type of the destination file system.

The default is to use ODS5-compatible file names when the destination
file system is ODS5, and to convert the names to ODS2-compatible names
when the destination file system is ODS2.

Beginning in UnZip 6.0, ODS2-compatible names are explicitly set to
upper case.
<QUALIFIER>
/OVERWRITE

/OVERWRITE
<NEXT>
/NOOVERWRITE

See /EXISTING.

/OVERWRITE is equivalent to /EXISTING = NEW_VERSION.
<NEXT>
/NOOVERWRITE is equivalent to /EXISTING = NOEXTRACT.
<QUALIFIER>
/PAGE

/PAGE
<NEXT>
/NOPAGE

Feed all screen output through the built-in "more" pager.
<QUALIFIER>
/PASSWORD

/PASSWORD=decryption-password

Specifies a decryption password and prevents UnZip from prompting for
a password in case the specified decryption key was wrong. The supplied
string must be enclosed in double-quotes whenever it contains lowercase
or special characters.
<QUALIFIER>
/PIPE

/PIPE

Extract files to SYS$OUTPUT with no informational messages.
<QUALIFIER>
/QUIET

/QUIET[=SUPER]

Perform operations quietly.  The keyword SUPER can be specified to make
operations even more quiet.
<QUALIFIER>
/RESTORE

/RESTORE[=(KEYWORD, ...)]

Selects restoration options for some meta-data.
The optional keywords recognized are:
<LITERAL>
|  OWNER_PROT    Restore file owner and ACL protection settings.
|  NOOWNER_PROT  Do not restore file owner and ACL protection settings.
|  NODATE        Do not restore any timestamps.
|  DATE=ALL      Restore timestamps for all extracted entries, files
|                and directories.
|  DATE=FILES    Restore timestamps for extracted files.  (default)
<LARETIL>

By default, VMS UnZip restores the original date-time attributes for files,
but not for directories.  This agrees with the behavior of VMS BACKUP
(and UnZip versions before 5.52 where the capability to restore directory
timestamps was added).

For compatibility with UnZip versions before 6.0 (5.53), the following
obsolete short forms are still accepted:
<LITERAL>
| Obsolete form:        Modern form:
| /RESTORE              /RESTORE = OWNER_PROT
| /NORESTORE            /RESTORE = NOOWNER_PROT
<LARETIL>
<QUALIFIER>
/SCREEN

/SCREEN
<NEXT>
/NOSCREEN

Extracts matching files to SYS$OUTPUT (the terminal).
<QUALIFIER>
/TEST

/TEST
<NEXT>
/NOTEST

Test archive files.
<QUALIFIER>
/TEXT

/TEXT[=(KEYWORD, ...)]
<NEXT>
/NOTEXT (default)

Selects conversion to VMS standard text file format.
The optional keywords recognized are:
<LITERAL>
|  AUTO     Automatically extracts files marked as "text" (rather
|           than "binary") in standard VMS text file format. (default)
|  ALL      Extracts all files in standard VMS text file format.
|  NONE     Same as /NOTEXT.
|  STMLF    Use Stream_LF record format for text files (instead of the
|           default variable-length record format).
<LARETIL>

A similar functionality is available for binary files, see qualifier /BINARY.
<QUALIFIER>
/TIMESTAMP

/TIMESTAMP

Sets the timestamp of an archive to that of its newest file.  This qualifier
corresponds to zip's /APPEND/LATEST (-go) option, but can be applied to
wildcard zipfile specifications (e.g. "*.zip") and is much faster.
<QUALIFIER>
/TRAVERSE_DIRS

/TRAVERSE_DIRS
<NEXT>
/NOTRAVERSE_DIRS (default)

Allows to extract archive members into locations outside of the currently
active "extraction root dir".  For security reasons, UnZip normally
removes "parent dir" path components ("../") from the names of extracted
files.  This feature (new for UnZip 5.50) prevents UnZip from accidentally
writing files to "sensitive" areas outside the directory tree below the
specified "extraction root".  By specifying the /TRAVERSE_DIRS option,
this security feature can be switched off. This allows users to extract
(older) archives that made use of "../" to create multiple directory
trees at the level of the current extraction folder.
<QUALIFIER>
/UPDATE

/UPDATE
<NEXT>
/NOUPDATE

Update existing files; create new ones if needed.
<QUALIFIER>
/VERSION

/VERSION
<NEXT>
/NOVERSION (default)

Retain VMS file version numbers.

<TOPIC>
Authors

Info-ZIP; currently maintained by Christian Spieler.  VMS support maintained
by Igor Mandrichenko, Steven M. Schweda, Christian Spieler and Hunter Goatley.
Originally based on a program by Samuel H. Smith.

VMS on-line help ported from UNZIP.TXT by Hunter Goatley.

<TOPIC>
Exit_Status

On VMS, UnZip's UNIX-style exit values are mapped into VMS-style status
codes with facility code 1954 = %x7A2, and with the inhibit-message
(%x10000000) and facility-specific (%x00008000) bits set:
<LITERAL>
|   %x17A28001                        normal exit
|   %x17A28000 + 16*UnZip_error_code  warnings
|   %x17A28002 + 16*UnZip_error_code  normal errors
|   %x17A28004 + 16*UnZip_error_code  fatal errors
<LARETIL>

Note that multiplying the UNIX-style UnZip error code by 16 places it
conveniently in the hexadecimal representation of the VMS exit code,
"__" in %x17A28__s, where "s" is the severity code.  For example, a
missing archive might cause UnZip error code 9, which would be
transformed into the VMS exit status %X17A28092.

The UnZip VMS exit codes include severity values which approximate those
defined by PKWARE, as shown in the following table:
<LITERAL>
|    VMS     UnZip err
|  severity    code     Error description
| ----------+---------+----------------------------------------------
|  Success       0      Normal.  No errors or warnings detected.
|  Warning       1      One or more warnings  were  encountered, but
|                       processing  completed  successfully  anyway.
|                       This  includes  archives  where  one or more
|                       (but not all)  files were skipped because of
|                       unsupported compress or encrypt methods,  or
|                       bad passwords.
|  Error         2      Error in the archive format.  Processing may
|                       have completed  successfully  anyway.   Some
|                       defects in archives (made by other programs)
|                       can be repaired transparently.
|  Fatal         3      Severe error in the archive format. Process-
|                       ing probably failed immediately.
|  Fatal         4      Memory allocation failed in program initial-
|                       ization.
|  Fatal         5      Memory  allocation  failed  in password pro-
|                       cessing.
|  Fatal         6      Memory allocation failed while decompressing
|                       to disk.
|  Fatal         7      Memory allocation failed while decompressing
|                       in memory.
|  Fatal         8      Memory  allocation  failed    (reserved  for
|                       future use).
|  Error         9      Specified archive files were not found.
|  Error        10      Invalid command-line options or parameters.
|  Error        11      No files matched selection criteria.
|  Fatal        50      Disk full.
|  Fatal        51      Unexpected  end-of-file  while  reading  the
|                       archive.
|  Error        80      User interrupt (Ctrl/C).
|  Error        81      No files were processed,  because  of unsup-
|                       ported compress or encrypt methods.
|  Error        82      No  files  were  processed,  because  of bad
|                       password(s).
|  Fatal        83      Large-file archive could not be processed by
|                       this small-file program.
<LARETIL>

<TOPIC>
UNIX_Options

The default action of UnZip is to extract all zipfile entries.  The following
options and modifiers can be provided:

<LITERAL>
|  -Z   ZipInfo mode
|  -c   extract files to SYS$OUTPUT (terminal)
|  -f   freshen existing files (replace if newer); create none
|  -h   show brief help screen and exit quietly
|  -l   list archive files (short format)
|  -p   extract files to SYS$OUTPUT; no informational messages
|  -t   test archive files
|  -T   set zipfile timestamps to that of each archive's newest entry
|  -u   update existing files; create new ones if needed
|  -v   list archive files (verbose format)
|  -z   display only the archive comment
|
|MODIFIERS
|  -a   extract text files in standard VMS text file format
|  -aa  extract all files as text
|  -b   auto-extract only binary files in fixed 512-byte record format
|  -bb  extract all files as binary in fixed 512-byte record format
|  -j   junk paths (don't recreate archive's directory structure)
|  -n   never overwrite or make a new version of an existing file
|  -o   always make a new version (-oo: overwrite orig) existing file
|  -q   perform operations quietly (-qq => even quieter)
|  -C   match filenames case-insensitively
|  -D   do not restore any timestamps (--D restore them even for dirs)
|  -L   convert filenames to lowercase if created under DOS, VMS, etc.
|  -M   feed screen output through built-in "more" pager
|  -P<password> supply decryption password on the cmd line (insecure!)
|  -S   use Stream_LF record format to extract text files (with -a[a])
|  -V   retain (VMS) file version numbers
|  -X   restore owner/ACL protection info (may require privileges)
|  -Y   treat ".nnn" suffix as version number ("a.b.3" -> "a.b;3")
|  -:   allow "../" path components to traverse across top extract dir
|  -2   force creation of ODS2-compatible file names
<LARETIL>

Note that uppercase options such as -C, -D, -L, -M, -P, -S, -T, -V, -X, -Y,
and -Z must be specified in quotes (unless SET PROC/PARSE=EXTEND is set).
For example:

<LITERAL>
|  $ unzip "-VX" -a zipfile
<LARETIL>

<TOPIC>
UNZIP_OPTS_Default

UnZip allows to modify its default behaviour by specifying (UNIX style)
option defaults via the UNZIP_OPTS logical name.
For example, the following will cause UnZip to match filenames without regard
to case, restore owner/protection information and perform all operations at
quiet-level 1 by default:

<LITERAL>
|  $ define UNZIP_OPTS "-qCX"
<LARETIL>

Note that the quotation marks here are required to preserve lowercase options
(opposite of the command-line behavior). To negate a default option on the
command line, add one or more minus  signs before the option letter, in
addition to the leading switch character `-':

<LITERAL>
|  $ unzip --ql zipfile
<LARETIL>

or

<LITERAL>
|  $ unzip -l-q zipfile
<LARETIL>

At present it is not possible to decrement an option below zero--that is,
more than a few minuses have no effect.

UNZIP_OPTS may be defined as a symbol rather than a logical, but if both
are defined, the logical is used.