1 VMSTAR
  VMSTAR  is  a  TAR  reader/writer  for  VMS.   It  can  read  archives
  ("tarfiles")  created  by the Un*x command "tar" (VMSTAR has a similar
  syntax) and also create such archives so that they can be  read  later
  by  a  Un*x  system.   Tarfiles  can  be  located in VMS disk files or
  directly on tape.

  VMSTAR supports both VMS- and UNIX-style command lines.   To  use  the
  UNIX-style  command  line, simply do not use any VMS-style qualifiers.
  There are  a  few  caveats  with  this,  however.   If  you  encounter
  problems, simply precede the UNIX option with a hyphen ("-").

  When using  the  UNIX-style  command  line,  the  default  tarfile  is
  whatever the logical name "$TAPE" points to (either a device or a file
  specification) unless specified by the "f" modifier.

  Tapes read and written by VMSTAR  must  be  mounted  using  the  MOUNT
  qualifiers     /FOREIGN/RECORD=512/BLOCK=blocksize.     By    default,
  "blocksize" should be 10240.   The  section  about  /BLOCKFACTOR  will
  explain further.

  Format:

      (VMS):  $ VMSTAR [/qualifiers] tarfile [filespec[,...]]
      (UNIX): $ VMSTAR [-][options] [tarfile] [filespec...]
2 Defining_VMSTAR
  To define VMSTAR, enter the following command:

      $ vmstar == "$somedisk:[somedir]vmstar"

  where "somedisk:[somedir]" above  is  the  directory  path  where  the
  VMSTAR  image  resides.   You can also place the above command in your
  login command procedure.
2 Qualifiers
/AUTOMATIC

  Valid only when specified with /EXTRACT.

  Causes VMSTAR to  attempt  to  automatically  determine  if  the  file
  present  in  the  tar  archive  is  text  or  binary  and  extract  it
  accordingly (see /BINARY).  The choice is based on very  simple  rules
  such  as the proportion of characters in the range 0-31 except CR, LF,
  FF, and TAB, and the proportion of the characters  above  127  in  the
  first block of the file.

/BLOCK_FACTOR

  Valid only when specified with /CREATE.

  Tells VMSTAR how many 512 bytes records each tar block should contain.
  When VMSTAR shall write to tape, you must make sure you mount the tape
  with the correct block size.  For example, if  you  want  to  use  the
  block factor 10:

      $ MOUNT/FOREIGN/RECORD=512/BLOCK=5120 MUA0:       ! 512*10 = 5120
      $ VMSTAR /CREATE/VERBOSE/BLOCK_FACTOR=10 MUA0: *.*

  The default block factor is 20, which means the  tape  block  size  is
  10240.

/BINARY

  Valid only when specified with /EXTRACT.

  Causes VMSTAR to create VMS files in  fixed  format,  record  size=512
  bytes,  and  no  record  attributes.   Use  /BINARY  when  you extract
  compressed files, tar archives, executable VMS images, or any kind  of
  files other than ASCII files with line-feed-terminated lines.

  When this qualifier  is  *NOT*  present,  VMS  files  are  created  as
  stream-LF files with implied (CR) record attributes.

/CONFIRM

  Causes VMSTAR to prompt the user for confirmation  before  storing  or
  extracting each file.

  The following responses are valid:

      Y   -  Yes
      N   -  No
      Q   -  Quit
      A   -  All (stop prompting)

/CREATE

  Creates a new tar archive.

/DATE_POLICY[=([option[,...]])]

  Decides which daytime entries in the extracted files  header  will  be
  set to the daytime present in the tar archive:

      [NO]CREATION       - set the creation time.
      [NO]MODIFICATION   - set the modification time.
      [NO]ALL            - set both creation and modification time.
      NONE               - set none of them.


  Those fields that are not set according to  the  daytime  in  the  tar
  archive   are   set  to  the  current  daytime  instead.   Default  is
  /DATE_POLICY=ALL.

  NOTE:  there is no Unix option corresponding to this one.
/DOTS

  Valid with /CREATE and /EXTRACT.

  When specified with /CREATE, VMSTAR will keep the trailing dot (.)  in
  filenames that don't have extensions.

  When specified with /EXTRACT, VMSTAR will preserve the use of dots  in
  directory  names.   By  default,  VMSTAR will convert dots in the Un*x
  directory specifications to underscores.  For example:

      emacs-19.22/src/buffer.c -> [EMACS-19_22.SRC]BUFFER.C

  Specifying /DOTS prevents the conversion,  and  you  get  this  result
  instead:

      emacs-19.22/src/buffer.c -> [EMACS-19.22.SRC]BUFFER.C

/EXTRACT

  This option instructs VMSTAR that files are to be extracted  from  the
  tar  archive  and  created  as  VMS files.  One or more Un*x-like file
  specifications including VMS wildcard characters may be present on the
  command  line.   Only  files  matching  one  of  the  patterns will be
  extracted.  If no files are specified, all files in the  archive  will
  be extracted.

  VMSTAR will attempt to re-create the directory  hierarchy  present  in
  the tar archive.  If files are named "./foo/bar..." in the tar archive
  (a common case), the VMS directory tree will be  created  relative  to
  the  current  default.   All  illegal characters in file names will be
  replaced by "_" (underscore).

/FORCE
  /NOFORCE

  Valid only when specified with /EXTRACT.

  Causes VMSTAR to store unsupported as best it  can.   Use  with  care.
  Default is /NOFORCE.

/HELP
  Produces a short description of the VMSTAR command line syntax.

/LIST

  Produces a listing of the contents of the tar archive,  including  the
  Un*x-style filename, the size in bytes, and the modification date.

/PADDING
  /NOPADDING

  Valid only when specified with /EXTRACT.

  Causes VMSTAR to add null blocks at the end of the tar files,  so  the
  last tape block will be completelly filled.  Default is /PADDING.

/VERBOSE

  Causes VMSTAR to display filenames and sizes when archiving VMS  files
  and VMS file specifications when extracting.
2 UNIX-Style_Options
  Options are  single  letters  grouped  together  with  no  intervening
  spaces.   There  must  be at least one of "x" (extract), "t" (type) or
  "c" (create) to indicate what  kind  of  action  VMSTAR  should  take.
  Other single letters modify these basic options.  The group of options
  may optionally include a leading "-" (hyphen) and in  some  cases  may
  require it.
3 c (create)
  This option directs VMSTAR to create a tar archive and to  copy  VMS
  files as directed by file specification(s) into this archive in such
  a  way  that  they  can  be  extracted  on  a  Un*x  machine.   File
  specifications (space separated, no commas) can include standard VMS
  wildcards in file and directory name.

  If a relative specification is given (no directory or  is  specified
  or  the  directory begins with "[." and no device name is included),
  the file name given in the tar archive will be  relative,  too  (not
  beginning with "/")
3 t (type)
  This option produces a listing of the contents of the  tar  archive,
  including  file name (Un*x style), size (in bytes), and modification
  date.
3 x (extract)
  This option instructs VMSTAR that files are to be extracted from the
  tar  archive  and  copied  as VMS files.  One or more Un*x-like file
  specifications including VMS wildcard characters may be  present  on
  the  command  line.  Only files matching one of the patterns will be
  actually extracted.  Default is to extract all files.

  VMSTAR will attempt to re-create the directory hierarchy present  in
  the  tar  archive.   If  files  are  named "./foo/bar..." in the tar
  archive (a common case), the VMS  directory  tree  will  be  created
  relative  to  the  current  default.  All illegal characters in file
  names will be replaced by "_" (underscore).
3 b (binary)
  This modifier is meaningful only when VMSTAR extracts files  from  a
  tar  archive.   If  it is specified, VMSTAR will create VMS files in
  fixed format, record size=512 bytes, and no record attributes.   Use
  the  "b"  modifier  when you extract compressed files, tar archives,
  executable VMS images or any kind of files other  than  ASCII  files
  with line-feed-terminated lines.

  When this modifier is  *NOT*  present,  VMS  files  are  created  as
  stream-LF files with implied (CR) record attributes.
3 d (dots)
  This modifier is only meaningful for the "c" (create) option.   When
  it  is  specified,  VMSTAR  will keep the trailing dot in file names
  without extension in the archive.
3 f tarfile
  This modifier allows the specification of the  tarfile  (either  VMS
  file  name or VMS device name) to be read or written by VMSTAR.  The
  default is the value of the logical name $TAPE.
3 h (help)
  This option produces a short desription of the VMSTAR command line.
3 v (verbose)
  Adding this modifier to the "x" or "c" option will cause  VMSTAR  to
  display file names and sizes stored when archiving VMS files and VMS
  directory and file names created when extracting from an archive.
3 w (wait)
  VMSTAR asks for a confirmation  before  each  file  is  archived  or
  extracted when this modifier is specified.
3 z (automatic mode)
  When this modifier is present in  an  extract  operation  (it's  not
  meaningful   for  any  other  operation),  VMSTAR  will  attempt  to
  automatically determine if the file present in the  tar  archive  is
  text or binary and extract it accordingly (see the 'b' option).  The
  choice is based on very simple  rules  such  as  the  proportion  of
  characters  in  the  range  0-31 except CR, LF, FF, and TAB, and the
  proportion of the characters above 127 in the  first  block  of  the
  file.
2 Filespec
  One or more file specifications may be present on the command line
  as  last  arguments.   They  must  be  separated  by commas if the
  VMS-style command interface is used.  If the Un*x-style  interface
  is  used,  the  files  must  be separated by spaces, *NOT* commas.
  They may include VMS wildcard characters "*"  and  "%".   Case  is
  never significant.

  Upon creation, the file specifications must be valid VMS  file  or
  directory names.  If only a directory name is specified, "*.*;" is
  automatically appended.   The  resultant  specifications  are  the
  names  of the VMS file names that will be archived in the tarfile.
  Use of device names and absolute paths ("[FOO.BAR]")  is  strongly
  discouraged  unless  absolute  archives  are  to  be  created (see
  /CREATE).

  Upon extract, the file specifications must be Un*x file  names  or
  patterns for Un*x file names using VMS wildcard characters.  Files
  in the tarfile having names matching  one  of  the  specifications
  will  be  extracted.   If no specification is given, all files are
  extracted.  Matching is done using pure wildcarded string-matching
  algorithms, i.e.  "/" is a normal character.
2 Examples
      $ MOUNT/FOREIGN/RECORD=512/BLOCK=10240 MUA0:
      $ VMSTAR/LIST/VERBOSE MUA0:

          or

      $ VMSTAR -TVF MUA0:

  Will give a full listing of the tar tape loaded in MUA0:

      $ SET DEF [FOO_ROOT]
      $ VMSTAR/EXTRACT/VERBOSE MUA0:

          or

      $ VMSTAR -XVF MUA0:

          as well as

      $ VMSTAR XVF MUA0:

  Will extract files from the tar tape in [FOO_ROOT...] provided the
  files in the tar archive do not begin with "/".

      $ DEFINE $TAPE MUA0:
      $ VMSTAR -XV *SOURCES/*.C

  Will only extract C source files in the subdirectory "sources" (or
  "Sources" or "SOURCES"; case is not significant) from the tar tape
  mounted in MUA0:

      $ VMSTAR/EXTRACT/VERBOSE EMACS.TAR

          or

      $ VMSTAR -XVF EMACS.TAR

  Will extract files in tar archive file  EMACS.TAR  which  may  has
  been transmitted from a Un*x system by network.

      $ VMSTAR/EXTRACT/VERBOSE/BINARY EMACS.TAR "./EXECUTABLE/EMACS.EXE"

          or

      $ VMSTAR -XVBF EMACS.TAR ./EXECUTABLE/EMACS.EXE

  Will only extract the specified file and create it as a VMS  fixed
  format,  record size = 512 bytes, no record attributes file.  Note
  that when VMS qualifiers are used, you need double  quotes  around
  file  specification  that  contain slashes, since VMSTAR otherwise
  will try to parse them as qualifiers.

      $ VMSTAR/CREATE/CONFIRM/VERBOSE MUA0: [.GNUCC...]

          or

      $ VMSTAR -CWVF MUA0: [.GNUCC...]

  Will archive the contents of the whole "[.GNUCC...]" subtree in  a
  tape  tar  archive  on  MUA0:.  VMSTAR will prompt the user before
  archiving each file.

      $ VMSTAR/CREATE/VERBOSE TARFILE.TAR *.DOC,[.GNUCC...]

          or

      $ DEFINE $TAPE TARFILE.TAR
      $ VMSTAR -CV *.DOC [.GNUCC...]

  Will create a tar archive file TARFILE.TAR  and  write  all  files
  with type ".DOC" and all the "[.GNUCC...]" subtree in it.
2 Restrictions
  If you want to use the Un*x-style command line and want to specify
  some  Un*x-style  paths (like ./EXECUTABLE/EMACS.EXE), the options
  must be preceded by a hyphen ("-").

  Because of differences in the Un*x and VMS filesystems, some files
  may  fail  to  be correctly transferred to/from the tarfile.  This
  can be caused by:

   -  restrictions in VMS file naming scheme:  extra  dots  in  file
      names  will  be  mapped  to underscores, dummy directory names
      will be generated if the archive contains more than  8  levels
      of   subdirectories,   links  are  extracted  as  empty  files
      containing only a short message "this  file  is  only  a  link
      to...", all file names are mapped to uppercase, etc.

   -  restrictions of the Un*x filesystem:  tar will  only  get  the
      latest version of a VMS file to enter it into the archive.  No
      trace of the original file device name is kept in the archive.

   -  VMS strong file typing:  VMSTAR can  only  safely  archive  or
      extract from an archive VMS "text" files (rfm=vfc or stream_lf
      with rat=cr) or  VMS  fixed  size  record,  512  bytes/record,
      rat=none  files  (e.g.   .EXE  image files).  VMSTAR will skip
      other file types (this includes .OBJ and library files.   They
      *can't* be archived).


  Other restrictions:

  RMS file attributes are lost in the archive process.   Text  files
  are   archived   as  <record><LF><record><LF>.   Fixed  files  are
  archived as is.

  VMSTAR will always restore files  relative  to  your  current  RMS
  default  if  names  in the tarfile do not begin with `/'.  If file
  names in the tarfile begin with a `/' (bad practice),  an  attempt
  will  be made to restore the files to the absolute path.  There is
  currently no way to explicitly specify the  target  VMS  directory
  where files should be extracted.

  No attempt has been made to handle search lists  as  RMS  defaults
  (e.g.  SYS$SYSROOT).  Be very careful about that.
2 Authors
  VMSTAR is based on the TAR2VMS and VMS2TAR programs written by:

      Sid Penstone,
      VLSI Group,
      Department of Electrical Engineering,
      Queen's University,
      Kingston, Ontario, Canada, K7L3N6

  The combining was done by:

      Alain Fauconnet
      SIM/INSERM U194             EARN/Bitnet:       FAUCONNE@FRSIM51
      Faculte de Medecine         VMS PSI Mail: PSI%+208075090517::FAUCONNET
      91 Boulevard de l'Hopital   FAX:          (+33) 1-45-86-56-85
      75634 PARIS CEDEX 13 FRANCE PTT net:      (+33) 1-45-85-15-29

  VMSTAR is now enhanced and maintained by:

      Hunter Goatley                          Richard Levitte
      VMS Systems Programmer                  GNU on VMS hacker
      Western Kentucky University             Södra Långgatan 39, II
      1 Big Red Way                           S-171 49  Solna
      Bowling Green, KY 42101                 SWEDEN
      E-mail: goathunter@ALPHA.WKU.EDU        levitte@e.kth.se
      FAX: +1 502 745 6014                    N/A

  Bugs should be reported either to Hunter or Richard.

  If you wish to help testing VMSTAR, please subscribe to  the  list
  vms-tar-testers@e.kth.se,     by     sending    a    message    to
  vms-tar-testers-request@e.kth.se, with the command "SUBSCRIBE"  in
  the message body.
2 Thanks
  to all those who  have  helped  make  this  package  better.   The
  following persons have given us great feedback:

   -  Brian Tillman <tillman_brian@si.com> has made many suggestions
      and has produced VMSTAR.RNH for us.

   -  Tim Adye <adye@v2.rl.ac.uk> has helped us debug VMSTAR on AXP,
      and suggested the addition of the /DATE_POLICY qualifier.

   -  Stellan Lagerström <stellanl@e.kth.se> for giving me (Richard)
      access to his DAT players.

   -  Asad M. Ali <amali@austin.asc.slb.com> for  helping  out  with
      support of variable length record files.

   -  Numerous others who provided bug reports and helped testing.

