Retro1.org codex

VMARC                                                     CMS User Area command

Use the VMARC command to create, load, or list archive files.  An archive file
is a single compressed file that contains multiple files.  VMARC can be used
in place of the CMS TAPE command.

The PACK function reads ordinary CMS files and produces the equivalent file in
a compacted form.  The compacted version of the file is usually significantly
smaller than the original, and therefore would occupy less disk space or would
require less time to transmit through a network.  VMARC allows more than one
compacted file to be written to the same output file.  The latter is called an
archive; the individual compacted files are members of the archive.

The UNPACK function reads archives created by PACK and regenerates the original
files from the archive members.

The LIST function scans archives created by PACK and reports the names of each
of the members.

The format of the VMARC command is:
+----------+------------------------------------------------------------------+
| VMARC    | LIST   infileid [pattern]   [( Options...[)]]                    |
|          | PACK   infileid [outfileid] [( Options...[)]]                    |
|          | UNPACK infileid [pattern]   [( Options...[)]]                    |
|          |                                                                  |
|          | Common options:                                                  |
|          |    FIfo|LIfo   REPlace|NOREPlace   Tap#|Tape   TRace|NOTRace     |
|          | Pack options:                                                    |
|          |    APPend|NOAPPend  BLock nnnn  LZW|STORE|S2  PRinter|PRt|PUnch  |
|          |                                                                  |
|          | Unpack options:                                                  |
|          |    HOld   IGNore|NOIGNore   NEWDate|OLDDate   READer|RDR         |
+----------+------------------------------------------------------------------+
where:

infileid specifies the file or files of the input archive[s] or file[s] to be
         processed.  Asterisks and percent-signs may be included in the
         filename and filetype as wildcards to specify groups of CMS files.
         The asterisk may be used in place of the file mode to specify all
         accessed disks.  This operand is required when the input is from disk,
         and it is disallowed when input is from a device (tape, punch or
         printer).

outfileid
         specifies the output file[s].  Equal-signs may be used in place of the
         filename, filetype, or filemode to indicate that that part of the file
         identifier should be derived from the input file identifier.  This
         parameter, therefore, may specify a single file to hold all of the
         compacted input files, or it may specify potentially a different file
         for each.  This operand is disallowed if output is to a device
         (tape, punch or printer).  If output is to disk and the outfileid
         parameter is omitted, output file[s] replace the input file[s].

pattern  specifies the filename and filetype of members that should be listed
         or unpacked.  Asterisks and percent-signs may be used as pattern-
         matching symbols.  The pattern parameter must include a disk mode
         letter, but the letter has no significance.  If omitted, VMARC uses
         * * A for the pattern.

Common Options:

FIfo | LIfo
         specifies that trace output be added to the console stack rather than
         displayed on the terminal.

REPlace | NOREPlace
         allows or prevents output files to overwrite existing files.
         NOREPLACE is the default.

Tap# | Tape
         specifies that output from a PACK operation, or input to an UNPACK or
         LIST operation, be directed to a tape unit.  The option may be
         specified as TAP1, TAP2, TAP3, or TAP4 to indicate which virtual tape
         drive is used.  TAPE is a synonym for TAP1.

TRace | NOTRace
         specified that the name and statistics for each file processed be
         reported, or not reported.  TRACE is the default.

Pack Options:

APPend | NOAPPend
         appends output to an existing archive, or prevents output from being
         appended to an existing archive.  If the output file does not already
         exist, it is created.  If it does exist, it should be an archive
         created by VMARC.  However, VMARC does not verify that the output is a
         well-formed archive.  The only test performed is that the output file
         is of fixed-length records.  NOAPPEND is the default.

BLock nnnn
         specifies that nnnn be used for the output file record length.  For
         disk files, the default is 80; for tape, it is 4096.  The option is
         not allowed for punch or printer output.

LZW | STORE | S2
         specifies the data compaction method to be used.

         LZW specifies that the LZW data compaction method is to be used.  This
         method is used by default if neither S2 nor STORE are specified.

         STORE specifies that no data compaction is to be used.  This option
         should be used in those few cases where the LZW and S2 methods fail to
         produce a result significantly smaller than the original.  The result
         produced with the STORE option will always be slightly larger than the
         original because of the overhead needed to record structural
         information.

         S2 specifies that the S2 data compaction method is to be used.  This
         method usually produces smaller results than the LZW method, but it
         requires more processor time to produce.  (During uncompaction, the S2
         and LZW methods have comparable execution speed.)

PRinter | PRt | PUNch
         specifies that output be directed to the virtual line printer or
         virtual card punch rather than to disk.

Unpack Options:

HOld     specifies that the reader file be retained after processing.  This
         option is meaningful only if the READER option is also specified.

IGNore | NOIGNore
         specifies that the original names of files extracted from an archive
         be ignored or used.  If IGNORE is specified, VMARC assigns names of
         the form FILEnnnn VMARCOUT, where nnnn are sequentially assigned
         numbers beginning with 0001.  NOIGNORE is the default.

NEWDate | OLDDate
         specifies that that files extracted from an archive retain be givin a
         new date or retain their original date.  OLDDATE is the default.

READer | RDR
         specifies that input be taken from the virtual card reader rather than
         from disk.


Usage Notes:

1.  Two data compaction methods are available, both of which give very good
    performance for most applications.  Method LZW is a variant of the well-
    known Lempel-Ziv-Welch algorithm, while S2 is a string-pair algorithm.  The
    S2 method tends to produce a smaller result, but at the expense of about
    twice the execution time during compaction.  (However, there is no
    performance penalty when uncompacting S2 members; the speed of the two
    methods are comparable.)

    Since there are cases when neither of the two methods will produce a result
    smaller than the original, VMARC offers a compaction option of STORE.  No
    compaction is actually done in this case; the original file data is written
    as-is to the output file with only some structural information added.

2.  Usage examples:

    All FORTRAN source is to be placed into individual archives.  These
    archives are to serve as on-line backups of the original.
       VMARC PACK  * FORTRAN A  = VMARC A

    All modules and EXEC files from the B-disk are to be placed into a single
    archive.  This archive may be a distribution package from some product.
       VMARC PACK  * MODULE B  PACKAGE VMARC A  (REPLACE
       VMARC PACK  * EXEC   B  PACKAGE VMARC A  (APPEND

    Development on some project has been completed, so all assembler source
    files on the C-disk are to be replaced by their individual archives.  This
    will reduce the amount of disk space used by the source, but keep it
    on-line in a form where the original source can be recovered if needed.
       VMARC PACK  * ASSEMBLE C  = = = (REPLACE

    All files on the D-disk are backed up to tape.
       VMARC PACK  * * D  (TAP1 BLOCK 8196
       TAPE WTM 2

3.  When appending to an existing archive, any value specified with the BLOCK
    option is ignored.  The record length of the existing archive is used
    instead.

4.  Separate archives (with identical BLOCK specifications) can be combined
    into a single archive by simple  concatenation.  For example, ARC2 VMARC A
    could be added to the end of ARC1 VMARC A by the COPYFILE command:
       COPYFILE  ARC2 VMARC A  ARC1 VMARC A  ( APPEND

5.  Since the output file name and type may be derived from the corresponding
    parts of the input file names, it is possible for multiple input files
    (specified by a pattern) to map into the same output file.  For example,
       VMARC  PACK  * * A  = VMARC A
    could map the files TEST EXEC and TEST FORTRAN both to the output file TEST
    VMARC.  When this type of situation occurs VMARC handles it in what would
    seem to be the most natural fashion.  The first time a given output file is
    used VMARC obeys the APPEND or REPLACE option if specified.  For the second
    and all subsequent uses of the output file, VMARC unconditionally appends.

6.  Similar to the behavior of the TAPE command, after the last archive member
    is written to tape, VMARC writes a tape mark then backspaces over the tape
    mark. The tape file has end-of-file properly marked, and the tape is
    positioned such that a second use of VMARC can append to the tape file.  If
    the user wishes to create separate tape files, it is recommended that the
    TAPE WTM command be used between applications of VMARC.  That is,
       VMARC PACK ... ( TAP1
       TAPE WTM 1
       VMARC PACK ... ( TAP1
    Whether one or many files are written, it is also recommended that two tape
    marks be written after the last file.


7.  VMARC was written by John S. Fisher of the Rensselaer Polytechnic Institute
    in 1989 and 1990.

Responses:

nnnnnnnn tttttttt mm. Bytes in=xxxxxxxx, bytes out=yyyyyyyy (zzzzzz%)

After each archive member is processed VMARC generates a trace message.  The
message reports the member's original fileid and the number of bytes read, the
number of bytes written, and the ratio of the two.  The message can be
suppressed with the NOTRACE option.  When packing, the ratio displayed in the
message is the compaction factor; the smaller the number, the higher the degree
of compaction achieved.  When unpacking, the ratio is the expansion factor.

When listing the membership of an archive, the number of bytes written and the
ratio display as zero.