.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
