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 . 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 has made many suggestions and has produced VMSTAR.RNH for us. - Tim Adye has helped us debug VMSTAR on AXP, and suggested the addition of the /DATE_POLICY qualifier. - Stellan Lagerström for giving me (Richard) access to his DAT players. - Asad M. Ali for helping out with support of variable length record files. - Numerous others who provided bug reports and helped testing.