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]: %TAR-S-CREATED, created DISK:[USER]DEEP-SPACE.COB;1 (2573 records) Extract terrorpods.cob ? (Y/N) [Y]: %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.