.help mscrfits Aug97 mscred
.ih
NAME
mscrfits -- read Mosaic data from a FITS tape
.ih
SYNOPSIS
FITS files from tape are copied to disk with a possible renaming
to restore the filename the file had when written by \fBmscwfits\fR.
One may also just list the contents of the tape.
.ih
USAGE	
mscrfits input [output]
.ih
PARAMETERS
.ls input
The input IRAF tape specification with no position; e.g. mta.
.le
.ls output
The output root name for the files.  Multiple files will be written with a
four digit numeric extension based on the \fIoffset\fR parameter and the
tape position.  Once the file is written to disk the file name may be
changed to the name specified by the FILENAME keyword (provided a file
doesn't already exist with that name) if the \fIoriginal\fR parameter is
set.  If only listing the contents of the tape this parameter need not
be specified.
.le
.ls tapefiles = "1-"
A range list of tape file numbers to read or list.  See the help topic
"ranges" for information about the range list syntax.
.le
.ls listonly = no
List the specified tape files only?  If "yes" then no output files will
be created and a short or long listing of each selected tape file will
be printed to the standard output.  If both \fIshortlist\fR and
\fIlonglist\fR are "no" then the short listing will be produced.
Note that a short listing is considerable faster than the long listing
because only the first header needs to be read.
.le
.ls shortlist = yes
List one line of information for each tape file?  This includes the the
tape specification with position, the output file name if reading files,
the stored original filename if present, the value of the NEXTEND keyword
if present, and the value of the OBJECT keyword if present.
.le
.ls longlist = no
List the short listing information plus additional information about each
FITS header?  The information includes the extension index, extension type,
extension name, BITPIX, and NAXIS values.
.le
.ls offset = 0
Offset for numbering of output disk filenames.  The output file name
is the output rootname with four appended digits made from adding
the offset and the tape position (which starts with 1).  The offset
parameter is useful when not restoring the original filenames and when
reading data from multiple tapes. 
.le
.ls original = yes
Restore the original filename?  If a FILENAME or IRAFNAME keyword is
found in the FITS file then when the file has been written to disk
using the specified output name the output file is renamed to the
original filename with a ".fits" extension.
.le
.ih
DESCRIPTION
The specified tape files are either copied from tape to disk or just a
summary listing is printed to the standard output.  The tape files are
checked to make sure they appear to be FITS format (they must begin with a
SIMPLE card) and then directly copied to disk without change if not simply
listing.  Any FITS tape file can be read including multiextension files
with any extension types.

When reading the files to disk (\fIlistonly\fR=no) the tape file is
copied to a disk file with filename given by the output file root name,
followed by a four digit number composed of the \fIoffset\fR value plus
the tape file position, and then with a ".fits" extension.  If
the \fIoriginal\fR parameter is set and a FILENAME or IRAFNAME keyword
is found the disk file is ultimately renamed to filename specified
by those keywords.  If the desired original filename is already in use
then a warning is given and the output file is not renamed.

Summary information for the selected tape files may be written to
the standard output whether or not a disk file is created.  A short
listing includes the tape identification and the output filename
(if creating an output file), the original file name if the FILENAME
or IRAFNAME keyword is present, the value of the NEXTEND keyword if
present, and the value of the OBJECT keyword if present.  The long
list includes the short listing plus information from each FITS
header unit.  This information consists of the extension index
(0 for the primary header), and the values of the following keywords
if present: XTENSION, EXTNAME, EXTVER, BITPIX, and NAXIS#.

One common use of MSCRFITS is to list the contents of the tape.  This
is done by setting the \fIlistonly\fR parameter.  This turns off creating
a disk file and forces at least the short listing.  Note that if
just the short listing is selected the listing is most efficient since
only the first header unit needs to be read.  The long listing
requires the entire file to be read.
.ih
EXAMPLES
1. Read a set of files with the default short listing.

.nf
    cl> mscrfits mta data
    mta[1]  ->  data0001.fits: abc     nextend=8 NGC ABC
        Rename data0001.fits -> abc.fits
    mta[2]  ->  data0002.fits: def     nextend=8 NGC DEF
        Rename data0002.fits -> def.fits
    ...
.fi

2. List a tape with the default short listing.

.nf
    cl> mscrfits mta list+
    mta[1]: abc     nextend=8 NGC ABC
    mta[2]: def     nextend=8 NGC DEF
    ...
.fi

4. List a tape with the default short listing and save the listing in a file.

.nf
    cl> mscrfits mta list+ >> fitslog
.fi

4. Read a set of Mosaic files with a long listing without restoring the
original names.

.nf
    cl> mscrfits mta data tape=4,9,12 long+ original-
    mta[4]  ->  data0004.fits: abc     nextend=8 NGC ABC
       0 PRIMARY
       1   IMAGE im1  16 2044x4096
       2   IMAGE im2  16 2044x4096
       3   IMAGE im3  16 2044x4096
       4   IMAGE im4  16 2044x4096
       5   IMAGE im5  16 2044x4096
       6   IMAGE im6  16 2044x4096
       7   IMAGE im7  16 2044x4096
       8   IMAGE im8  16 2044x4096
    mta[9]  ->  data0009.fits: def     nextend=8 NGC DEF
       0 PRIMARY
       1   IMAGE im1  16 2044x4096
    ...
.fi

.ih
REVISIONS
.ls MSCRFITS - V2.11 external package
First release.
.le
.ih
SEE ALSO
mscwfits
.endhelp
