1 TAR
VMS TAR is a utility that emulates the UNIX tar, or Tape ARchive utility,
which is used to store a set of files in a single file, usually on an
offline medium, such as 9-track tape.

VMS TAR automatically performs conversion of files to and from the UNIX
file format, and converts between UNIX and VMS file protections and
modification times.

Format:


    TAR keyword [file-spec]

2 Parameters
keyword

  One of the keywords APPEND, EXTRACT, LIST or WRITE.  Each keyword has a
  different function.  See the help for each keyword.

file-spec

  The specification of any file(s) to be APPENDed, EXTRACTed, LISTed or
  WRITten.

  On an APPEND or WRITE operation, this is a wildcarded VMS file-
  specification.  On an EXTRACT or LIST operation, the file-spec parameter
  is used to match UNIX filenames (case sensitive).  Any wildcarding in
  the latter case is performed as string wildcarding, so the '*' wildcard
  matches all characters, including '.' and '/'.

2 Examples
For all TAR operations direct to or from tape, the tape must be MOUNTed
as in the following EXTRACT example:

	$ ALLOCATE MF,MS,MT tar_archive
	%DCL-I-ALLOC, _$1$MSA0: allocated
	$ MOUNT /FOREIGN /RECORD_SIZE=512 /BLOCK_SIZE=10240 tar_archive
	%MOUNT-I-MOUNTED,  mounted on _$1$MSA0:
	$ TAR EXTRACT *.COB /CONFIRM
	Extract program-1.cob ? (Y/N) [Y]: n
	Extract deep-space.cob ? (Y/N) [Y]: <Return>
	%TAR-S-CREATED, created DISK:[USER]DEEP-SPACE.COB;1 (2573 records)
	Extract terrorpods.cob ? (Y/N) [Y]: <Return>
	%TAR-S-CREATED, created DISK:[USER]TERRORPODS.COB;1 (523 records)
	Extract foo.cob ? (Y/N) [Y]: Yes
	%TAR-S-CREATED, created DISK:[USER]FOO.COB;1 (0 records)
	%TAR-S-TOTAL, total of 3 files created, 4 files scanned
	$ DISMOUNT tar_archive
	$ DEALLOCATE tar_archive


If you wanted to create an archive that would later be copied to a tape,
the following sequence of commands might be used:

  	$ TAR WRITE *.pas /ARCHIVE=PASCAL.TAR /OUTPUT=PASCAL_TAR.LOG

and later:

	$ ALLOCATE MSA0:
	%DCL-I-ALLOC, _$1$MSA0: allocated
	$ MOUNT /FOREIGN /RECORD_SIZE=512 /BLOCK_SIZE=10240 MSA0:
	%MOUNT-I-MOUNTED, BLANK1 mounted on _$1$MSA0:
	$ COPY/LOG PASCAL.TAR MSA0:
	%COPY-S-COPIED, CS:[STAFF.FRED]PASCAL.TAR copied to _$1$MSA0:
  	 (315 records).
	$ (dismount and deallocate)

The /BLOCK_SIZE qualifier is important for mounting TAR tapes.  UNIX uses
a default blocking factor of 20, which makes the block size 10240.  A UNIX
tar archive might have been created with a different blocking factor,
though.  This may be discovered by mounting such an archive tape without
a /BLOCK_SIZE qualifier and DUMPing the tape drive (DUMP will demonstrate
the block size).

If you are going to use a tape that has previously been used for an
unusual format (like VMS BACKUP), you should initialize the tape, using
the INITIALIZE command:

	$ ALLOCATE MF,MS,MT TAR_ARCHIVE
  	%DCL-I-ALLOC, _$1$MSA0: allocated
	$ INIT TAR_ARCHIVE FREDDO
!
2 Supported_Files
Files readable by TAR include:

   Record format                       Carriage control
   -------------                       ----------------

   variable-length                     carriage-return
                                         stream-lf
   variable-fixed-control (VFC)        print-file
   fixed-length                        none

Variable-length VMS files are written to an archive with linefeeds
('newline's or '\n' to UNIX) as record terminators, which is consistent
with the UNIX text file format, whereas fixed-length VMS files are not.
Extraction of files that used to be fixed-length is extremely difficult
(see Caveats), as they are indistinguishable from text files when stored
in tar format.  A feature may be added to VMS TAR in future to counter
this.

Other file types may be supported, but a file with FORTRAN carriage
control for example, may be transmitted in a useless format.  Note that
any file EXTRACTed by tar will always be recreated with the VMS standard
text file attributes; varying-length records and carriage-return carriage
control.
!
2 Caveats
TAR_TIMEZONE

   To assist in the conversion of file modification times, TAR uses time
   zone information.  TAR gets the local time zone from the logical names
   SYS$TIME_ZONE or TAR_TIMEZONE (the latter is used if the former is
   not defined).  The format of these logicals is "[s][[h]mm]", where s is
   a sign (+ or -), h is the number of hours (1-18) and mm the number of
   minutes (00-59) to be added to GMT to give the local time.  An example
   is "+1000" for Australian Eastern Standard Time, which is 10 hours
   ahead of GMT.

   I'm not sure about the history of SYS$TIME_ZONE.  I saw it somewhere,
   but I can't remember where.  It is not defined on our systems.


The /SCAN qualifier.

   When writing a file with variable-length records to an archive, TAR's
   normal behaviour is first to copy the file into a temporary file, in
   the TAR format.  When this is done, TAR knows the size of the file in
   bytes, so it can then write a header record to the real archive, and
   quickly load the contents of the temporary file into the archive.

   The presence of the /SCAN qualifier makes TAR read through the whole of
   the input file to get its size in bytes, then load it into the archive.

   The first method should save on processing, but the second method
   should save on I/O, and could help in a situation of stretched disk
   quota.  I thought both were useful, so I coded both and made the /SCAN
   qualifier.

   Incidentally, if the input file has fixed-length records, its size is
   computed using the record size and the size in blocks of the file. This
   may not be a completely safe algorithm, as it presumes there are no
   record delimiters in fixed-length record files.


'Directory not found' when EXTRACTing files

   If you try to make TAR EXTRACT a file into a directory that does not
   exist (it may not have been put in the archive), it will say so,
   then extract it into the file '[]OUT_FILE.DAT'.  This wasn't actually
   explicitly coded into TAR by me (a side effect), but it seems a
   sensible thing to do until I implement a qualifier to tell TAR to
   create the directories it needs (like UNIX tar and BACKUP).


Internal errors

   If TAR tells you it has encountered an internal error, it means it
   has caught a Pascal run-time error that it doesn't have a way of
   handling.  Generally, this means you have done something strange with
   TAR that I haven't done myself in testing.  The code supplied in the
   INTERNERR message corresponds to a VAX Pascal status code, and I
   would like it if you notify me of how you caused the error and the
   value of that code.


Output file record wrapping

   VMS TAR has no way of knowing if a file originally had fixed-length
   records, so it always assumes a file in an archive is to be EXTRACTed
   with variable-length records, and interprets any LF's it finds
   accordingly.  But, if a record is longer than a certain number
   (currently 8192) of bytes, the superfluous bytes are used to make a new
   record in the file (they are wrapped).  The user is told of this if and
   when it happens during the extraction of a file.  Note however that the
   user will only be notified the first time it happens.


Exceeding disk quota

   When a sequential file is written to by VAX RMS, it automatically
   extends, or allocates more blocks to the file as necessary.  I have
   seen RMS be overly generous in doing this; to the point where I am
   fairly sure there are a few bugs deep down in RMS.  This generosity
   could cause a user's disk quota to be exceeded when creating a TAR
   archive or extracting files from an archive.  To combat this, you can
   enter the following DCL command before using TAR:

	$ SET RMS_DEFAULT/EXTEND=n

   Where n is a fairly low number, like 1 or 2.  The RMS default is 32,
   but I have seen files with more than 31 allocated but unused blocks
   attached to them.

   These superflous extents only exists when the file is being written to,
   they are removed when the file is closed.
!
2 APPEND
This function is the same as WRITE, except that files written to the
archive are appended (see WRITE).
!
3 Qualifiers
!
/ARCHIVE

  Specifies the archive to which files are to be APPENDed.  The default is
  'TAR_ARCHIVE', which might be a logical name pointing to a tape-drive
  (see Examples).  The archive file specified must be a valid TAR archive
  file.

/CONFIRM

  If the /CONFIRM qualifier is given on the APPEND keyword, the user is
  prompted each time TAR is about to append a file to the archive.  The
  user may then confirm or abort the archiving of the file.

/MAP_MODE
 /MAP_MODE=PREFIX (Default)

  The MAP_MODE keyword tells TAR how to map VMS file specifications to
  UNIX pathnames when writing files to an archive.  The available modes
  and their behaviours follows:

     PREFIX    File names in the archive are relative, any directories
               in the pathname of a file that are common to all files
               to be written (a common prefix) are removed.

     ABSOLUTE  The VMS device, directory, name and type fields are
               mapped to an absolute UNIX pathname (one beginning with
               '/').  A file called 'DISK:[USER.SUB]FOO.BAR' would be
               mapped to '/disk/user/sub/foo.bar'.

     ROOT      The (logical or physical) device specification is omitted
               from the UNIX pathname, but the directory, name and type
               are used to form a relative pathname.  The file
               'DISK:[USER.SUB]FOO.BAR' would be mapped to
               'user/sub/foo.bar'.

/OUTPUT

  The /OUTPUT qualifier is used to direct messages from TAR to a file, it
  works like the /OUTPUT qualifier on other VMS commands.

/SCAN

  Instructs TAR not to use a temporary archive file for the purpose of
  writing a file with variable-length records to an archive.  See TAR
  Caveats.
!
2 EXTRACT
This function reads files from an archive, and creates VMS files in your
current directory with names, protections and modification dates as
similar as possible to their UNIX names.  As each file is created, its
size in records is logged.
!
3 Qualifiers
!
/ARCHIVE

  Specifies the archive from which files are to be EXTRACTed.  The default
  is 'TAR_ARCHIVE', which might be a logical name pointing to a tape-drive
  (see Examples).

/CONFIRM

  If the /CONFIRM qualifier is given on the EXTRACT keyword, the user is
  prompted each time TAR is about to extract a file.  The user may then
  confirm or abort the creation of the file.

/OUTPUT

  The /OUTPUT qualifier is used to direct messages from TAR to a file, it
  works like the /OUTPUT qualifier on other VMS commands.
!
2 LIST
  This function lists all files, and their sizes in bytes, in an archive
  that match file-spec.  If file-spec is not supplied, LIST lists all files
  in the archive.
!
3 Qualifiers
!
/ARCHIVE

  Specifies the archive TAR is to search for files.  The default is
  'TAR_ARCHIVE', which might be a logical name pointing to a tape-drive
  (see Examples).

/FULL

  If the /FULL qualifier is specified on a LIST operation, a more detailed
  listing of the archive contents is returned; specifically, the
  protection, owner id-number, group id-number, size and name of the file.

/OUTPUT

  The /OUTPUT qualifier is used to direct messages from TAR to a file, it
  works like the /OUTPUT qualifier on other VMS commands.
!
2 WRITE
This function writes files to an archive, copying the modification
date/time and the read and write permission bits (the execute permission
is present in most places where the read permission is under VMS, and is
therefore almost meaningless).  The user and group id's are set to 0
(root).  As each file is written, its size in bytes (under UNIX) is
logged.
!
3 Qualifiers
!
/ARCHIVE

  Specifies the archive to which files are to be WRITten.  The default is
  'TAR_ARCHIVE', which might be a logical name pointing to a tape-drive
  (see Examples).

/CONFIRM

  If the /CONFIRM qualifier is given on the WRITE keyword, the user is
  prompted each time TAR is about to write a file to the archive.  The
  user may then confirm or abort the archiving of the file.

/MAP_MODE
 /MAP_MODE=PREFIX (Default)

  The MAP_MODE keyword tells TAR how to map VMS file specifications to
  UNIX pathnames when writing files to an archive.  The available modes
  and their behaviours follows:

     PREFIX    File names in the archive are relative, any directories
               in the pathname of a file that are common to all files
               to be written (a common prefix) are removed.

     ABSOLUTE  The VMS device, directory, name and type fields are
               mapped to an absolute UNIX pathname (one beginning with
               '/').  A file called 'DISK:[USER.SUB]FOO.BAR' would be
               mapped to '/disk/user/sub/foo.bar'.

     ROOT      The (logical or physical) device specification is omitted
               from the UNIX pathname, but the directory, name and type
               are used to form a relative pathname.  The file
               'DISK:[USER.SUB]FOO.BAR' would be mapped to
               'user/sub/foo.bar'.

/OUTPUT

  The /OUTPUT qualifier is used to direct messages from TAR to a file, it
  works like the /OUTPUT qualifier on other VMS commands.

/SCAN

  Instructs TAR not to use a temporary archive file for the purpose of
  writing a file with variable-length records to an archive.  See TAR
  Caveats.
