MRDFITS - A multiple format FITS reader. V2.5
Last updated: December 2001


The MRDFITS utility is intended to be a general purpose function allowing
users to quickly read FITS files in all standard formats.  MRDFITS
returns an array or structure containing the data from the specified
FITS extension.  Header information may optionally be returned as a
string array.  MRDFITS currently supports the following FITS data types:

	Primary simple images
	The IMAGE extension
	Group data in both primary images and IMAGE extensions.
	ASCII tables
	BINARY tables including the suggested convention for
	  variable length records.

MRDFITS uses the dynamic structure definition capabilities
of IDL to generate a structure matching the characteristics of the
FITS data and then reads the data into the structure.  Some tailoring
of the FITS data is possible:

	- A specified range of data may be retrieved.
	- The data may be scaled to FLOAT or DOUBLE values as controlled
	  by the BSCALE (TSCALE) and BOFFSET (TZERO) keywords.
	  Note that the default is no scaling.
	- Only a subset of the columns may be retrieved for ASCII
	  and binary tables.
        - Automatic mapping into IDL unsigned data types (/UNSIGNED) when the
          appropriate BSCALE(TSCAL) and BZERO(TZERO) keywords appear in the 
          header
        - Variable length binary tables may read either into a fixed length
          column (default) or into a IDL pointers (with /POINTER_VAR) for 
          maximum efficiency

MRDFITS has been tested to work on IDL Version V4.0 through V5.5, although not
all of its capabilities are available in earlier IDL Versions.   For example,
output of unsigned data types requires at least V5.2, and use of the
/POINTER_VAR keyword requires at least V5.0. 

MRDFITS is called as a function similar to the old READFITS utility, e.g.,

	str = mrdfits(file, exten_no, header)
	
where file is a file name, exten_no is the extension to be read (0 for the
primary data array) and header is an optional variable in which the
header information will be stored.  A number of optional keyword
parameters are available.

        ALIAS             Specify translation of column names to structure tags
	/FSCALE and /DSCALE  cause scaling to single and double precision.
	COLUMNS=  	     allows users to specify the columns desired.
	RANGE=		     allows users to retrieve only some rows.
	STRUCTYP=	     gives the structure type for the structure
	TEMPDIR=	     gives the directory for temporary files
	/SILENT		     suppresses informative messages
	/USE_COLNUM          makes tag names of the form C#
	/NO_TDIM             disable processing of TDIM keywords.
	ERROR_ACTION         Set the ON_ERROR action to this value
        /UNSIGNED            Convert to IDL unsigned integer type when possible
	
MRDFITS uses the EXECUTE function where possible but creates temporary
procedures when complex structures are needed.  The MRD_STRUCT
function is used for the dynamic definition of structures.

MRDFITS is largely a standalone utility, but does use the parameter
parsing of FXPAR to find elements in a header.  All I/O is done
within MRDFITS.  The IEEE_TO_HOST routine is used to convert
data to the local representation.

In IDL V4.0.1 and earlier, there was a limit of 127 tags to an IDL structure.
MRDFITS gets around this limit by using substructures.    For example, if
a binary table has 150 columns, then the first 64 columns will appear as
separate tags, the next 64 will appear in a substructure with a tag name
SS1, and the next 22 will appear in a substructure named SS2.    (Although
the tag number limits were removed in IDL V5.0, there appear to still be 
limits in the size of a structure definition.) 

Known limitations include:
	
	No special handling is done for NULL values.
	
	Note that MRDFITS is not a FITS checker.  It may read in
	files that are not proper FITS since only a few FITS elements
	needed by the reader are actually explicitly checked.  MRDFITS
	should read in all correct FITS files and I would appreciate
	copies of any correct FITS files that break the reader.
	
MRDFITS comprises several files.   The following procedures are included in 
the main file MRDFITS.PRO

	MRDFITS:	The main function with some utilities.
	MRD_ASCII:	Code to handle ASCII tables.
	MRD_TABLE:	Code to handle BINARY tables.
	MRD_IMAGE:	Code to handle simple images and group data.
	MRD_SCALE:	Data scaling.
	MRD_COLUMNS:	Column selection.

The following procedures are in separate files (because they are of general
use outside of MRDFITS.)

	MRD_STRUCT:	Dynamic structure definition.
	FXPOSIT:	Find an extension in a FITS file.


On Unix systems MRDFITS can handle files compressed with either
the `standard' Unix compress utility or with the Gnu gzip utility.
It assumes that files ending with .Z, .gz and .GZ are to be
decompressed.  Decompression is done using a sub-process and pipes
so that no temporary file is created.     Users with IDL V5.3 or later can use
the gzip facilty on any OS (not just Unix). 

Please send comments and bug reports to:

	Tom McGlynn
	High Energy Astrophysics Science Archive Research Center (HEASARC)
        tam@lheapop.gsfc.nasa.gov
	301-286-7743

        or Wayne Landsman   landsman@mpb.gsfc.nasa.gov