Initial commit

1 files changed, 177 insertions, 0 deletions

diff --git a/pkg/dataio/doc/reblock.hlp b/pkg/dataio/doc/reblock.hlp
new file mode 100644
index 00000000..dd3a506a
--- /dev/null
+++ b/pkg/dataio/doc/reblock.hlp
@@ -0,0 +1,177 @@
+.help reblock Jan93 dataio
+.ih
+NAME
+reblock -- copy a file to tape or disk with optional reblocking
+.ih
+USAGE
+reblock infiles outfiles file_list
+.ih
+PARAMETERS
+.ls infiles  
+The input file list or device name, e.g. "mta1600[2]" or "mta800", "file1",
+"file1,file2", or "@infiles".
+.le
+.ls outfiles  
+The list of output files or device name, e.g. "gemini!mtb", "out1",
+"out1,out2", or "@outfiles".
+If multiple file output to disk is requested,  and the specified number
+of output files is 1, the output file names will be generated
+by concatenating the tape file number (the input files are on tape) or
+a sequence number (the input files are on disk) onto the output file
+name.
+.le
+.ls file_list
+List of tape file numbers or ranges delimited by commas,
+e.g. "1-3,5_8".
+File_list is requested only if the magtape input device is specified.
+Files will be read in ascending order regardless of the ordering of the list.
+Reading will terminate silently if EOT is reached, thus a list such as
+"1-999" may be used to read all files on the tape.
+.le
+.ls newtape  
+If the output device is magtape, newtape specifies whether the tape is
+blank or contains data.
+Newtape is requested only if no tape file number is specified, e.g. "mta1600".
+.le
+.ls outblock = INDEF
+Size of the output block  bytes.
+In the  default case and for disk output, the output block size is set to the
+file i/o disk default buffer size.
+.le
+.ls inrecord = INDEF, outrecord = INDEF
+The sizes of the input and output logical records in bytes.
+The default input and output record sizes are set equal to
+the input and output block sizes respectively. If inrecord > outrecord,
+records are trimmed; if inrecord < outrecord, records are padded; if
+inrecord = outrecord, records are simply counted. If only one of inrecord or
+outrecord is set, the undefined parameter defaults to the value of the
+other.
+.le
+.ls skipn = 0    
+The number of input blocks (tape input) or records (disk input, size inrecord)
+to be skipped.
+.le
+.ls copyn = INDEF
+The number of input blocks (tape input) or records
+(disk input, size inrecord) to be copied. Copyn defaults to a very large number.
+.le
+.ls byteswap = no
+Swap every other byte. For example if byteswap is enabled, bytes 1 2 3 4 5 6
+would become bytes 2 1 4 3 6 5 on output.
+.le
+.ls wordswap = no
+Swap every 4 bytes. For example if byteswap is enabled, bytes 1 2 3 4 5 6 7 8
+would become 4 3 2 1 8 7 6 5 on output.
+.le
+.ls pad_block = no
+If pad_block is set, reblock pads trailing blocks until they are outblock
+bytes long, otherwise trailing blocks may be short.
+.le
+.ls padchar  = 0
+Single character used to pad blocks or records.
+Padchar is only requested if pad_record or pad_block
+is set. If padchar equals one of the digits 0 through nine, records and
+blocks are padded with the face value of the character, otherwise the
+ASCII value is used.
+.le
+.ls offset = 0
+The number which added to the tape file number is appended to \fIoutfiles\fR
+to produce the output file name. For example if file_list = "1-3", outfiles =
+"out" and offset = 100, the three files out101, out102, out103 would
+be produced rather than out001, out002 and out003.
+.le
+.ls verbose = yes  
+Print messages about files, blocks copied etc.
+.le
+.ih
+DESCRIPTION
+REBLOCK is a procedure to copy disk or tape resident files to
+disk or tape. Multiple input tape or disk files may be specified.
+If multiple files are output to disk, and only one output file name is
+specified, the output file names will be
+generated by concatenating the tape file number (the input files are on tape)
+or a sequence number (the input files are on disk) onto the output file name.
+The user may request magnetic tape output to begin at a specific file on
+tape, e.g. mta1600[5] in which case file five will be overwritten if it
+exists, or at BOT or EOT. If no file number is specified REBLOCK asks
+whether the tape is new or old and begin writing at BOT or EOT as
+appropriate.
+
+Before beginning the copy, the user may request reblock to skip
+n (default 0) blocks (tape input) or logical records (disk input).
+The user can also specify that
+only n (default all) blocks (tape input) or records (disk input)
+are to be copied. Before the copy the data may be optionally word-swapped
+(default no) and/or byte-swapped (default no). If verbose is specified
+(default yes) reblock prints the input and output file names,
+the number of blocks read and written and the number of records read and
+written.
+
+Reblock
+uses the default buffer sizes supplied by mtio and file i/o to determine the 
+maximum number of bytes which can be read in a single read call. For tapes
+this corresponds to the maximum number of bytes per block permitted by the
+device. Mtio will not read more than one block per read call. Therefore the
+actual number of bytes read will be less than or equal to the mtio buffer size.
+For disk files the default buffer size set by IRAF is a multiple of the
+disk block size. If the disk file is smaller than one block
+or the last block is partially full, the number of bytes read
+will be less than the default buffer size. All magtape and disk reads are
+done with the file i/o read procedure and a call to fstati determines the number
+of bytes actually read.
+
+If all the defaults are set, a binary copy is performed.
+In tape to tape copies the block and record sizes are preserved,
+but the density may
+be changed by specifying the appropriate output file name e.g. mta800 or
+mta1600.
+Reblocking occurs in tape to disk transfers, if records, are trimmed,
+padded or counted, or if blocks are padded.
+If a disk to tape transfer is requested
+the output block size will be the default file i/o  buffer size.
+The last block in a file may be short. If uniform sized blocks are
+desired, pad_block must be set, in which case trailing partially filled
+blocks will be padded with padchar.
+
+Logical records are distinguished from blocks (physical records).
+The input and output record sizes default to
+the size of the input and output blocks respectively.
+Logical records may be shorter or longer than the  block sizes.
+
+.ih
+EXAMPLES
+1. Copy a magnetic tape preserving the record sizes but changing
+the density from 800 bpi to 1600 bpi.
+
+.nf
+	cl> reblock mtb800 mta1600[1] 1-999
+.fi
+
+2. Reblock a magnetic tape changing the block size from 4000 bytes to 8000
+bytes and padding the last block.
+
+.nf
+	cl> reblock mtb1600 mta1600[1] 1-999 outb=8000 padb+
+.fi
+
+3. Copy a series of disk fits files to tape
+
+.nf
+	cl> reblock @fitsfiles mta[1] outb=28800
+.fi
+
+4. Trim the records of a disk file.
+
+.nf
+	cl> reblock infile outfile inrec=80 outrec=72
+.fi
+
+5. Pad the records of a disk file with blanks.
+
+.nf
+	cl> reblock input output inrec=81 outrec=82 padchar=" "
+.fi
+.ih
+SEE ALSO
+t2d
+.endhelp