1 TAPES

  This program operates in two modes:

    In "Scan" mode, it scans a tape and prints out information about its
    contents. 

    In "Copy" mode it copies all or part of the tape to a disk or second
    tape. In this mode it can also perform translation between ascii and
    ebcdic, or give a hex dump of the input.

  Syntax:  $ TAPES  tape[/qual]  

  where "tape" is the drive on which the tape has been mounted (/FOREIGN)
  and "qual" denotes one or more optional Qualifiers. If no qualifiers are
  specified, the program operates in "scan" mode.

  The program starts at the current position of the input tape, so repeated 
  executions can be performed to do combinations of operations that cannot
  be specified by the parameters, e.g., copying two files with different
  attributes.

2 HISTORY

  Source Language: Fortran
  Written at the Multimission Image Processing Laboratory
                 Jet Propulsion Laboratory
                 Mail Stop 168-427
                 4800 Oak Grove Drive
                 Pasadena, California 91109

2 QUALIFIERS

  The following qualifiers may be specified after the tape-drive parameter
  (square brackets [] denote optional elements, and embedded blanks are 
  legal):

  /OUT[=x] - specifies the destination of output other than to terminal.

  /COPY - requests "Copy" mode.

  /DUMP - requests hex dump of the input.

  /FILES [= n1[:m1] [,n2[:m2] [,...,n10[:m10]]]] - files to be copied.

  /BLOCKS=n[:m] - blocks to be copied.

  /BYTES=n - number of bytes to be copied from each block.

  /ALL - output all bytes of each block.

  /IGNORE - ignore read errors on input tape.

  /SKIP - skip input records with read errors when copying.

  /TOASC - perform EBCDIC-to-ASCII translation.

  /029 - correct for 029 IBM keypunch characters.

  /TOEBC - perform ASCII-to-EBCDIC translation.

  /FIXED - specifies that output disk file is to be of record-type 'FIXED'.

  /RECLEN=r - specifies record length of output file.

  /REBLOCK=n - specified reblocking on output tape by factor n.

  /AFTER[=n] - specifies position on output tape.

  /REWIND - causes input tape to be rewound before any other processing.

  /EOT - read data past the end of tape mark. 

  /SPLIT - split input file if end of output tape encountered during copy.

 All qualifiers may be abbreviated down to 3 characters.

3 /OUT

  /OUT[=x]

 This specifies the destination of output other than to terminal.

 If "x" is a tape drive (or a logical name pointing to one), then the
 data specified by the other qualifiers are copied to that tape. (Must
 be mounted FOREIGN.)

 If a copy is being made to a tape, and the end of the output tape is
 reached before the copy is completed, then the output tape will be rewound
 and the user prompted to mount another or abort the job.  How the file
 that was being copied at that point is treated depends on the /SPLIT
 qualifier.

 If "x" is not a tape, then all output goes to disk file "x" (.DAT, by
 default). If /OUT is specified without a filename "x", the filename
 is TDUMP.DAT. This disk file will be of unformatted type if none of the
 qualifiers /RECLEN, /FIXED, /DUMP, /TOASCI, or /TOEBC are specified.
 Otherwise, the file will be formatted. Recordtype is 'FIXED' if /FIXED
 is specified, 'VARIABLE' if /TOASCI or /TOEBC is specified, or if /RECL
 has been specified without /FIXED, or 'SEGMENTED' if none of these
 qualifiers have been specified. Carriage-control is 'LIST' when type is
 'VARIABLE' and 'NONE' otherwise.

 If /OUT is not specified, all output goes to the terminal (as a hex
 dump).

3 /COPY

 This forces the program to operate in COPY mode.

 COPY mode is automatically invoked when any qualifier other than /OUT
 or /REWIND is specified.

3 /DUMP

 This requests that the output be in hex format, suitable for visual
 inspection.  The output will be organized in 8 words of 4 bytes each
 per line.  All qualifiers (except /TOASC & /TOEBC) that are valid in
 COPY mode apply.

 Note that hex output is the only choice available when the output is
 to the terminal.

3 /FILES

  /FILES [= n1[:m1] [,n2[:m2] [,...,n10[:m10]]]] 

 The contents of file n1 (or files n1 thru m1) are output; also n2 (or n2
 through m2), etc. Up to 10 files or file ranges may be specified. If 
 /FILES is specified without any numbers or is omitted, all files are
 output. 

 If /BLOCKS is not specified, then all blocks are output. If the output is
 not to the terminal, then all bytes in the blocks are output, unless
 /BYTES has been specified.  If the output is to the terminal, then only
 the first 80 bytes of each block are output unless /BYTES or /ALL is
 specified.

 Note that the file specification is relative to the current position of
 the tape. Thus, running TAPES twice in a row with /FILES=1 in both case
 will process two consecutive files, unless /REWIND has been specified.

3 /BLOCKS

  /BLOCKS=n[:m]

 Block n (or blocks n thru m) of the files specified are output. If /FILES
 was not specified, then only the first file is output.

 If the output is to the terminal, then only the first 80 bytes of each
 block are output unless /BYTES or /ALL is specified.  

 Note that the blocks specification is relative to the current position of
 the tape. Thus, running TAPES twice in a row with /BLOCKS=1:10 in both case
 will process twenty consecutive blocks, ten at a time (unless /REWIND is
 specified).

3 /BYTES=n

 This specifies that only the first n bytes of each block will be copied 
 to the output file.

 If /BYTES is specified together with /REBLOCK or /RECLEN for tape
 output, it is ignored.

3 /ALL 

 All bytes of the blocks specified are output. This is the default except
 when the output is to the terminal, in which case only the first 80 bytes
 are output by default.

3 /IGNORE 

 Read errors on the input tape are ignored and whatever was read is
 written to the output unit (if any). This is the default for SCAN mode
 (and should not be specified if SCAN is desired, as it invokes COPY.)

3 /SKIP

 This qualifier has the same effect as /IGNORE, except that input records
 with read errors are not written to the output unit (if there is one).

3 /TOASC_/TOEBC

  /TOASC - perform EBCDIC-to-ASCII character translation on the copied
           data. If the output is to a disk file, this file will be
           formatted with a default record length of 80 (can be changed
           using /RECLEN).

  /TOEBC - perform ASCII-to-EBCDIC character translation on the copied
           data.

3 /029

  This only has meaning when /TOASC is specified.  (It is ignored
  otherwise.)  It implies that the EBCDIC characters in the input data
  were entered using an 029 keypunch, which deviates from the standard
  026 in the (, ), +, and = characters.  These characters are then
  corrected by the program.

3 /RECLEN 

  /RECLEN=r

 This specifies the record length of the output file. 

 For disk output, /RECLEN specifies that the file will be formatted,
 with records of this (maximum) length. (If /RECLEN is not specified
 for disk output, then the file will be unformatted unless /TOASC or
 /TOEBC were specified, in which case the a record length of 80 is
 default.)

 For tape output, this specifies that each record read in will be
 truncated or padded with zeroes to the length specified (r) before
 being written out.  (For normal re-blocking of tapes, use the
 /REBLOCK qualifier.)

3 /REBLOCK

  /REBLOCK=n 
 
 This causes the output tape to be reblocked by a factor n. I.e., the
 output blocksize = n * (input blocksize).
 This is only valid for tape output (it is ignored otherwise).

 If n*(input blocksize) > 65535, then the largest value of n below this
 limit is used.

 Note that if the number of blocks on the input tape is not an integer
 multiple of n, then the last block of the output tape will contain fewer
 than n input blocks.

 /REBLOCK should not be specified together with /BYTES or /RECLEN for 
 tape output; if it is, then /BYTES or /RECLEN is ignored.

3 /FIXED 
 This specifies that the output disk file will have fixed-length
 records. The record length used will be that of the first block read
 from the input tape file, unless /RECLEN is specified.

3 /REWIND 

 This causes the input tape to be rewound before any other processing
 takes place.

3 /AFTER

  /AFTER[=n]

 (This is only valid if an output tape was specified, otherwise it is
 ignored).

 This specifies that output data are to be written after file n on the
 output tape, skipping existing files on that tape. The output tape is
 rewound before searching for file n.

 /AFTER=0 causes the output tape to be rewound only, so the first file
 copied will be file 1 on the output tape.

 If /AFTER alone is specified (without =n), then the data will be
 written after all files on the tape.  (However, the maximum number of
 files that this specification will skip is 32767.)

 The default (if /AFTER is omitted) is to write data beginning at the
 current tape position, overwriting any existing files beyond that
 point.

3 /EOT 

 This qualifier causes the program to ignore the end of tape mark
 if any data exist after that point.  This allows the program to read
 data past the end of tape mark.  It should be used with caution, as
 it may cause the tape to run off the reel.  (It applies to the input
 tape only.)

3 /SPLIT

 This qualifier causes an input file that is being copied to an output
 tape to be split into 2 output files if an end-of-tape on the output
 unit is encountered during the copy: the portion that has already been
 copied will be terminated with a double end-of-file mark, and the
 remainder will be copied to the next output tape.

 The default in this case is to back up to the last file, write a double
 end-of-file after it, and then copy the entire next file to the next
 output tape.

3 SCAN_MODE

 In SCAN mode, only bytes-per-block and blocks-per-file are listed for
 all files on the input tape.  The only qualifiers permitted in SCAN
 mode are /OUT and /REWIND; any other will automatically invoke COPY
 mode.

 Note that a block with the same number of bytes as the preceding block
 is not listed separately. Thus a fixed-length file with 100 blocks of
 7280 bytes each will produce the following output:

   *  7280 bytes in block     1
   EOF>  100 blocks in file   1

   ** EOF>

 (The last line denotes a double end-of-file mark, i.e., end of tape.)

2 EXAMPLES

 Example 1:
                    $ mount/foreign mt
                    $ tapes mta0

     This example includes the required MOUNT command, which is hereafter
     omitted. This TAPES command will scan the tape on drive MTA0: and
     send a list of bytes-per-block and blocks-per-file to the terminal.

 Example 2:
                    $ tapes mta0/out

     This example generates the same output as example 1, but sends it to
     a disk file called TDUMP.DAT.

 Example 3:
                    $ tapes mta0/out/files

     This example copies all files from the tape on mta0: to the disk file
     TDUMP.DAT. All files on the tape are concatenated.

 Example 4:
                    $ tapes mta0/out=mtb1/files=1:5,10:20/ignore

     This example copies files 1 thru 5 and 10 thru 20 to the tape on 
     drive MTB1:, ignoring any read errors on tape MTA0:.

 Example 5:
                    $ tapes mta0/out/files=1:5,10:20/ignore

     This example makes the same copy as the previous one but writes it
     to the disk file TDUMP.DAT.

 Example 6:
                    $ tapes mta0/out=gen.for/fil=3/toasc
                    $ tapes mta0/out=gen.lis/fil=1/recl=132/toasc

     This example first translates the contents of file 3 from EBCDIC to 
     ASCII and writes it to the disk file GEN.FOR, with a record lenth of 
     80. Then the next file (i.e., file 4 on the tape) is translated to
     ASCII and copied to the disk file GEN.LIS, with a record length of
     132.

 Example 7:
                    $ tapes mta0/out=mtb1/files=2/blocks=1:1024
                    $ tapes mta0/out=mtb1/files=1/blocks=1:1024

     This example copies the first 1024 blocks of file 2 on tape MTA0
     to a file on MTB1, and then copies the next 1024 blocks of the 
     same file (2) on MTA0 to the next file on MTA0. Note that if the
     tape had been rewound between the two runs, the qualifiers on the
     second run would have had to be /FILES=2/BLOCKS=1025:2048.

 Example 8:
                $ tapes mta0/out=mtb1/files=2/blocks=1:1024
                $ tapes mta0/out=mtb1/rewind/files=2/blocks=1025:2048

      This example performs the same operation as does example 7, but
      rewinds the tape before the second step.

2 DISCLAIMER

      No warranties express or implied as to the suitability of 
      this program for any particular application are made by MIPL,
      JPL or NASA.

      This program may be freely distributed as long as this help
      file is distributed with the program.

2 PROBLEMS

      Please direct any inquiries for bug fixes, enhancements or 
      complaints to:

                Mipl3::VICAR             (on Span)
                VICAR@Mipl3.Jpl.Nasa.Gov (on the ARPA Internet)

      or any other way that you can send mail to the VICAR account
      at Mipl3.  We will try to help but can't guarantee anything.

