MRDFITS V2.23

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 variable length tables.

• - 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 be read either into a fixed length column (default) or into a IDL pointers (with /POINTER_VAR) for maximum efficiency

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

   str = MRDFITS(file_or_unit, exten_no_or_name, [ header] )

• ALIAS Specify translation of column names to structure tags
• /FSCALE and /DSCALE cause scaling to single and double precsion.
• COLUMNS= Only read a specified subset of table columns.
• RANGE= Retrieve only a specified range of rows.
• ROWS= Retrieve only a specified vector of rows.
• STRUCTYP= gives the structure type for the structure
• /SILENT suppresses informative messages
• /USE_COLNUM makes tag names of the form C#
• /NO_TDIM disable processing of TDIM keywords.
• /POINTER_VAR -set to use pointer arrays for variable length arrays
• ERROR_ACTION Set the ON_ERROR action to this value
• /UNSIGNED Convert to IDL unsigned integer type when possible

For calls from other programs, MRDFITS has an output STATUS keyword to indicate whether it was successful. A status of >=0 indicates a successful read. The returned status value has the following meanings:

• 0 -> successful completion
• -1 -> error
• -2 -> end of file

One known limitation of MRDFITS is that 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 uses the /COMPRESS keyword to OPENR to allow it to read gzip'ed files on any machine architecture. MRDFITS can also read files (via a pipe to SPAWN) compressed with `standard' Unix compress utility, the Linux bzip2 utility, or the FPACK compression utility. MRDFITS assumes that files ending with .fz, .Z, .gz, .GZ and .bz2 are to be decompressed, but it also has the COMPRESS keyword so that the user can specify that any file is compressed.

The variable length array facility is a mechanism to save storage space, by allowing each row of an array to have a different length.   MRDFITS has two ways of handling such variable length arrays.    In the default (or /FIXED_VAR) method, the corresponding structure tag is dimensioned using the largest record.     A new "length" column is then added, giving the  actual length of each row of the variable length column.         For example, suppose the fifth column in a binary table with 3000 rows is a variable length  array named MATRIX, with a longest length of 27.   The default structure created by MRDFITS would have a tag named MATRIX  dimensioned  27 by 3000 containing the data, along with a tag named L5_MATRIX dimensioned LONARR(3000) containing the actual length (always less than or equal to 27)  of each row of MATRIX.        If the /POINTER_VAR keyword of MRDFITS is set, then the MATRIX tag is returned as an IDL pointer, and the data values for each row can be determined by dereferencing this pointer.   For example,

IDL> help,*str(0).matrix
<PtrHeapVar18001>
                DOUBLE    = Array[14]
IDL> help,*str(1).matrix
<PtrHeapVar18014>
                DOUBLE    = Array[27]

Instead of a file name, MRDFITS() can be given the unit number of an already opened FITS file. In this case, the EXTEN_NO parameter gives the number of extensions to skip *from the current location in the FITS file*. The use of a unit number instead of a file name is more efficient when multiple extensions of a FITS file are to be read. For example, to process all extension in a FITS file starting with the third one, one might do the following:

   lun=fxposit(filename, 3)      ;Open a FITS file and move to extension 3
   repeat begin
          thisHDU = mrdfits(lun, 0, hdr, status=status)
          ... process the HDU ...
   endrep until status lt 0

• 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.

• MRD_STRUCT: Dynamic structure definition.
• FXMOVE: Skip a specified number of extensions in a FITS file.
• FXPOSIT: Find an extension in a FITS file.
• MRD_HREAD: Read a FITS header from an opened disk file or Unix pipe
• MRD_SKIP Skip a number of bytes from the current location in a file or pipe

+ NASA Privacy, Security, Notices   + Accessibility

Curator: Nick Collins NASA Official: Theodore Gull Last Updated: Sep-2022