From:	CSBVAX::MRGATE!@KL.SRI.Com:kka059@Mipl3.JPL.Nasa.Gov@SMTP  8-AUG-1987 09:26
To:	EVERHART
Subj:	TAPES Program Part 6 of 6

Received: from Mipl3.JPL.Nasa.Gov by KL.SRI.COM with TCP; Thu 6 Aug 87 21:22:58-PDT
Date:    Thu, 6 Aug 87 09:41:45 PDT
From:     kka059@Mipl3.JPL.Nasa.Gov
Message-Id: <870806094145.00l@Mipl3.JPL.Nasa.Gov>
Subject: TAPES Program Part 6 of 6
To:       info-vax@kl.sri.com
X-ST-Vmsmail-To: ST%"info-vax@kl.sri.com",KKA059      

$Part6:
$ File_is="TAPES.HLP"
$ Check_Sum_is=1679752736
$ Copy SYS$Input VMS_SHAR_DUMMY.DUMMY
X1 TAPES
X
X  This program operates in two modes:
X
X    In "Scan" mode, it scans a tape and prints out information about its
X    contents. 
X
X    In "Copy" mode it copies all or part of the tape to a disk or second
X    tape. In this mode it can also perform translation between ascii and
X    ebcdic, or give a hex dump of the input.
X
X  Syntax:  $ TAPES  tape[/qual]  
X
X  where "tape" is the drive on which the tape has been mounted (/FOREIGN)
X  and "qual" denotes one or more optional Qualifiers. If no qualifiers are
X  specified, the program operates in "scan" mode.
X
X  The program starts at the current position of the input tape, so repeated 
X  executions can be performed to do combinations of operations that cannot
X  be specified by the parameters, e.g., copying two files with different
X  attributes.
X
X2 HISTORY
X
X  Source Language: Fortran
X  Written at the Multimission Image Processing Laboratory
X                 Jet Propulsion Laboratory
X                 Mail Stop 168-427
X                 4800 Oak Grove Drive
X                 Pasadena, California 91109
X
X2 QUALIFIERS
X
X  The following qualifiers may be specified after the tape-drive parameter
X  (square brackets [] denote optional elements, and embedded blanks are 
X  legal):
X
X  /OUT[=x] - specifies the destination of output other than to terminal.
X
X  /COPY - requests "Copy" mode.
X
X  /DUMP - requests hex dump of the input.
X
X  /FILES [= n1[:m1] [,n2[:m2] [,...,n10[:m10]]]] - files to be copied.
X
X  /BLOCKS=n[:m] - blocks to be copied.
X
X  /BYTES=n - number of bytes to be copied from each block.
X
X  /ALL - output all bytes of each block.
X
X  /IGNORE - ignore read errors on input tape.
X
X  /SKIP - skip input records with read errors when copying.
X
X  /TOASC - perform EBCDIC-to-ASCII translation.
X
X  /029 - correct for 029 IBM keypunch characters.
X
X  /TOEBC - perform ASCII-to-EBCDIC translation.
X
X  /FIXED - specifies that output disk file is to be of record-type 'FIXED'.
X
X  /RECLEN=r - specifies record length of output file.
X
X  /REBLOCK=n - specified reblocking on output tape by factor n.
X
X  /AFTER[=n] - specifies position on output tape.
X
X  /REWIND - causes input tape to be rewound before any other processing.
X
X  /EOT - read data past the end of tape mark. 
X
X  /SPLIT - split input file if end of output tape encountered during copy.
X
X All qualifiers may be abbreviated down to 3 characters.
X
X3 /OUT
X
X  /OUT[=x]
X
X This specifies the destination of output other than to terminal.
X
X If "x" is a tape drive (or a logical name pointing to one), then the
X data specified by the other qualifiers are copied to that tape. (Must
X be mounted FOREIGN.)
X
X If a copy is being made to a tape, and the end of the output tape is
X reached before the copy is completed, then the output tape will be rewound
X and the user prompted to mount another or abort the job.  How the file
X that was being copied at that point is treated depends on the /SPLIT
X qualifier.
X
X If "x" is not a tape, then all output goes to disk file "x" (.DAT, by
X default). If /OUT is specified without a filename "x", the filename
X is TDUMP.DAT. This disk file will be of unformatted type if none of the
X qualifiers /RECLEN, /FIXED, /DUMP, /TOASCI, or /TOEBC are specified.
X Otherwise, the file will be formatted. Recordtype is 'FIXED' if /FIXED
X is specified, 'VARIABLE' if /TOASCI or /TOEBC is specified, or if /RECL
X has been specified without /FIXED, or 'SEGMENTED' if none of these
X qualifiers have been specified. Carriage-control is 'LIST' when type is
X 'VARIABLE' and 'NONE' otherwise.
X
X If /OUT is not specified, all output goes to the terminal (as a hex
X dump).
X
X3 /COPY
X
X This forces the program to operate in COPY mode.
X
X COPY mode is automatically invoked when any qualifier other than /OUT
X or /REWIND is specified.
X
X3 /DUMP
X
X This requests that the output be in hex format, suitable for visual
X inspection.  The output will be organized in 8 words of 4 bytes each
X per line.  All qualifiers (except /TOASC & /TOEBC) that are valid in
X COPY mode apply.
X
X Note that hex output is the only choice available when the output is
X to the terminal.
X
X3 /FILES
X
X  /FILES [= n1[:m1] [,n2[:m2] [,...,n10[:m10]]]] 
X
X The contents of file n1 (or files n1 thru m1) are output; also n2 (or n2
X through m2), etc. Up to 10 files or file ranges may be specified. If 
X /FILES is specified without any numbers or is omitted, all files are
X output. 
X
X If /BLOCKS is not specified, then all blocks are output. If the output is
X not to the terminal, then all bytes in the blocks are output, unless
X /BYTES has been specified.  If the output is to the terminal, then only
X the first 80 bytes of each block are output unless /BYTES or /ALL is
X specified.
X
X Note that the file specification is relative to the current position of
X the tape. Thus, running TAPES twice in a row with /FILES=1 in both case
X will process two consecutive files, unless /REWIND has been specified.
X
X3 /BLOCKS
X
X  /BLOCKS=n[:m]
X
X Block n (or blocks n thru m) of the files specified are output. If /FILES
X was not specified, then only the first file is output.
X
X If the output is to the terminal, then only the first 80 bytes of each
X block are output unless /BYTES or /ALL is specified.  
X
X Note that the blocks specification is relative to the current position of
X the tape. Thus, running TAPES twice in a row with /BLOCKS=1:10 in both case
X will process twenty consecutive blocks, ten at a time (unless /REWIND is
X specified).
X
X3 /BYTES=n
X
X This specifies that only the first n bytes of each block will be copied 
X to the output file.
X
X If /BYTES is specified together with /REBLOCK or /RECLEN for tape
X output, it is ignored.
X
X3 /ALL 
X
X All bytes of the blocks specified are output. This is the default except
X when the output is to the terminal, in which case only the first 80 bytes
X are output by default.
X
X3 /IGNORE 
X
X Read errors on the input tape are ignored and whatever was read is
X written to the output unit (if any). This is the default for SCAN mode
X (and should not be specified if SCAN is desired, as it invokes COPY.)
X
X3 /SKIP
X
X This qualifier has the same effect as /IGNORE, except that input records
X with read errors are not written to the output unit (if there is one).
X
X3 /TOASC_/TOEBC
X
X  /TOASC - perform EBCDIC-to-ASCII character translation on the copied
X           data. If the output is to a disk file, this file will be
X           formatted with a default record length of 80 (can be changed
X           using /RECLEN).
X
X  /TOEBC - perform ASCII-to-EBCDIC character translation on the copied
X           data.
X
X3 /029
X
X  This only has meaning when /TOASC is specified.  (It is ignored
X  otherwise.)  It implies that the EBCDIC characters in the input data
X  were entered using an 029 keypunch, which deviates from the standard
X  026 in the (, ), +, and = characters.  These characters are then
X  corrected by the program.
X
X3 /RECLEN 
X
X  /RECLEN=r
X
X This specifies the record length of the output file. 
X
X For disk output, /RECLEN specifies that the file will be formatted,
X with records of this (maximum) length. (If /RECLEN is not specified
X for disk output, then the file will be unformatted unless /TOASC or
X /TOEBC were specified, in which case the a record length of 80 is
X default.)
X
X For tape output, this specifies that each record read in will be
X truncated or padded with zeroes to the length specified (r) before
X being written out.  (For normal re-blocking of tapes, use the
X /REBLOCK qualifier.)
X
X3 /REBLOCK
X
X  /REBLOCK=n 
X 
X This causes the output tape to be reblocked by a factor n. I.e., the
X output blocksize = n * (input blocksize).
X This is only valid for tape output (it is ignored otherwise).
X
X If n*(input blocksize) > 65535, then the largest value of n below this
X limit is used.
X
X Note that if the number of blocks on the input tape is not an integer
X multiple of n, then the last block of the output tape will contain fewer
X than n input blocks.
X
X /REBLOCK should not be specified together with /BYTES or /RECLEN for 
X tape output; if it is, then /BYTES or /RECLEN is ignored.
X
X3 /FIXED 
X This specifies that the output disk file will have fixed-length
X records. The record length used will be that of the first block read
X from the input tape file, unless /RECLEN is specified.
X
X3 /REWIND 
X
X This causes the input tape to be rewound before any other processing
X takes place.
X
X3 /AFTER
X
X  /AFTER[=n]
X
X (This is only valid if an output tape was specified, otherwise it is
X ignored).
X
X This specifies that output data are to be written after file n on the
X output tape, skipping existing files on that tape. The output tape is
X rewound before searching for file n.
X
X /AFTER=0 causes the output tape to be rewound only, so the first file
X copied will be file 1 on the output tape.
X
X If /AFTER alone is specified (without =n), then the data will be
X written after all files on the tape.  (However, the maximum number of
X files that this specification will skip is 32767.)
X
X The default (if /AFTER is omitted) is to write data beginning at the
X current tape position, overwriting any existing files beyond that
X point.
X
X3 /EOT 
X
X This qualifier causes the program to ignore the end of tape mark
X if any data exist after that point.  This allows the program to read
X data past the end of tape mark.  It should be used with caution, as
X it may cause the tape to run off the reel.  (It applies to the input
X tape only.)
X
X3 /SPLIT
X
X This qualifier causes an input file that is being copied to an output
X tape to be split into 2 output files if an end-of-tape on the output
X unit is encountered during the copy: the portion that has already been
X copied will be terminated with a double end-of-file mark, and the
X remainder will be copied to the next output tape.
X
X The default in this case is to back up to the last file, write a double
X end-of-file after it, and then copy the entire next file to the next
X output tape.
X
X3 SCAN_MODE
X
X In SCAN mode, only bytes-per-block and blocks-per-file are listed for
X all files on the input tape.  The only qualifiers permitted in SCAN
X mode are /OUT and /REWIND; any other will automatically invoke COPY
X mode.
X
X Note that a block with the same number of bytes as the preceding block
X is not listed separately. Thus a fixed-length file with 100 blocks of
X 7280 bytes each will produce the following output:
X
X   *  7280 bytes in block     1
X   EOF>  100 blocks in file   1
X
X   ** EOF>
X
X (The last line denotes a double end-of-file mark, i.e., end of tape.)
X
X2 EXAMPLES
X
X Example 1:
X                    $ mount/foreign mt
X                    $ tapes mta0
X
X     This example includes the required MOUNT command, which is hereafter
X     omitted. This TAPES command will scan the tape on drive MTA0: and
X     send a list of bytes-per-block and blocks-per-file to the terminal.
X
X Example 2:
X                    $ tapes mta0/out
X
X     This example generates the same output as example 1, but sends it to
X     a disk file called TDUMP.DAT.
X
X Example 3:
X                    $ tapes mta0/out/files
X
X     This example copies all files from the tape on mta0: to the disk file
X     TDUMP.DAT. All files on the tape are concatenated.
X
X Example 4:
X                    $ tapes mta0/out=mtb1/files=1:5,10:20/ignore
X
X     This example copies files 1 thru 5 and 10 thru 20 to the tape on 
X     drive MTB1:, ignoring any read errors on tape MTA0:.
X
X Example 5:
X                    $ tapes mta0/out/files=1:5,10:20/ignore
X
X     This example makes the same copy as the previous one but writes it
X     to the disk file TDUMP.DAT.
X
X Example 6:
X                    $ tapes mta0/out=gen.for/fil=3/toasc
X                    $ tapes mta0/out=gen.lis/fil=1/recl=132/toasc
X
X     This example first translates the contents of file 3 from EBCDIC to 
X     ASCII and writes it to the disk file GEN.FOR, with a record lenth of 
X     80. Then the next file (i.e., file 4 on the tape) is translated to
X     ASCII and copied to the disk file GEN.LIS, with a record length of
X     132.
X
X Example 7:
X                    $ tapes mta0/out=mtb1/files=2/blocks=1:1024
X                    $ tapes mta0/out=mtb1/files=1/blocks=1:1024
X
X     This example copies the first 1024 blocks of file 2 on tape MTA0
X     to a file on MTB1, and then copies the next 1024 blocks of the 
X     same file (2) on MTA0 to the next file on MTA0. Note that if the
X     tape had been rewound between the two runs, the qualifiers on the
X     second run would have had to be /FILES=2/BLOCKS=1025:2048.
X
X Example 8:
X                $ tapes mta0/out=mtb1/files=2/blocks=1:1024
X                $ tapes mta0/out=mtb1/rewind/files=2/blocks=1025:2048
X
X      This example performs the same operation as does example 7, but
X      rewinds the tape before the second step.
X
X2 DISCLAIMER
X
X      No warranties express or implied as to the suitability of 
X      this program for any particular application are made by MIPL,
X      JPL or NASA.
X
X      This program may be freely distributed as long as this help
X      file is distributed with the program.
X
X2 PROBLEMS
X
X      Please direct any inquiries for bug fixes, enhancements or 
X      complaints to:
X
X                Mipl3::VICAR             (on Span)
X                VICAR@Mipl3.Jpl.Nasa.Gov (on the ARPA Internet)
X
X      or any other way that you can send mail to the VICAR account
X      at Mipl3.  We will try to help but can't guarantee anything.
X
$ GoSub Convert_File
$ Exit
