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 VMS disk files or directly on tape.
 Default tarfile is  whatever  the  logical  name  "$TAPE"  points  to
 (either device or file name) unless specified by  the  "f"  modifier.

 Tapes read/written by VMSTAR must be mounted /FOREIGN/RECORD=512/BLOCK=10240

 Usage:    $ VMSTAR [options] [filespec [filespec...]]
2 Options
 Options are single letters grouped together (no space). There must be
 at  list one of "x" (extract), "t" (type) or "c" (create) to indicate
 what  kind  of  action  VMSTAR  should have. Other single letters are
 modifiers.  The group of options may optionally include a leading "-"
 (dash).
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
 (common case) the VMS directory tree  will  be  created  relative  to
 current default.  All  illegal  characters  in  file  names  will  be
 replaced by "_" (underscore).
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 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  it  can  be  further  extracted  on  an  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  directory
 beginning with "[." and no device name), the file name given  is  the
 tar  archive  will  be  relative  too  (not   beginning   with   "/")
3 v (verbose)
 Adding this modifier to a "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 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 to specify the tarfile (either VMS file name of
 VMS  device  name) read or written by VMSTAR. Default is whatever the
 logical    name   $TAPE   points   to,   either   file   or   device.
2 Filespec
 One or more file specifications may be present on the command line as
 last arguments. They must be separated by spaces, *NOT*  commas  like
 in most VMS commands. They may include VMS  wildcard  characters  "*"
 and "%". Case is never significant.

 Upon create, 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  "c"  option).

 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 strings matching algorithms,
 i.e. "/" is a normal character.
2 Examples
 $ MOUNT/FOREIGN/RECORD=512/BLOCK=10240
 $ VMSTAR TVF MUA0:

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

 $ SET DEF [FOO_ROOT]
 $ TAR 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:
 $ TAR 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:

 $ TAR XVF EMACS.TAR

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

 $ TAR 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.

 $ TAR CWVF MUA0: [.GNUCC...]

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

 $ DEFINE $TAPE TARFILE.TAR
 $ TAR 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
 Because of diffrences 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 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
 orginal file device name is kept in the archive.

 - VMS strong file typing: VMSTAR can only  safely  tranfer  back  and
 forth 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 tarfile do not begin by `/'. If  file  names  in  tarfile
 begin with a `/' (bad practice), an attempt will be made  to  restore
 files to the absolute path. There is currently no way to  explicitely
 specify the target VMS directory where  files  should  be  extracted.

 No  attempt has been made to handle search list as RMS defaults (e.g.
 SYSTEM account). Be very careful about that.
