FXBREAD

       Read a data array from a disk FITS binary table file.

       Each call to FXBREAD will read the data from one column and one row
       from the FITS data file, which should already have been opened by
       FXBOPEN.  One needs to call this routine for every column and every row
       in the binary table.  FXBCLOSE will then close the FITS data file.

       FXBREAD, UNIT, DATA, COL  [, ROW ]

       UNIT    = Logical unit number corresponding to the file containing the
                 binary table.
       COL     = Column in the binary table to read data from, either as a
                 character string containing a column label (TTYPE), or as a
                 numerical column index starting from column one.

       ROW     = Either row number in the binary table to read data from,
                 starting from row one, or a two element array containing a
                 range of row numbers to read.  If not passed, then the entire
                 column is read in.
                 Row must be passed for variable length arrays.

       DATA    = IDL data array to be read from the file.

       None.

       NOSCALE = If set, then the output data will not be scaled using the
                 optional TSCAL and TZERO keywords in the FITS header.
                 Default is to scale.
       NOIEEE  = If set, then the output data is not byte-swapped to
                 machine order.  NOIEEE implies NOSCALE.
                 Default is to perform the byte-swap.
       VIRTUAL = If set, and COL is passed as a name rather than a number,
                 then if the program can't find a column with that name, it
                 will then look for a keyword with that name in the header.
                 Such a keyword would then act as a "virtual column", with the
                 same value for every row.
       DIMENSIONS = Vector array containing the dimensions to be used to read
                 in the data.  Bypasses any dimensioning information stored in
                 the header.  Ignored for bit arrays.  If the data type is
                 double-precision complex, then an extra dimension of 2 is
                 prepended to the dimensions passed by the user.
       NANVALUE= Value signalling data dropout.  All points corresponding to
                 IEEE NaN (not-a-number) are converted to this number.
                 Ignored unless DATA is of type float, double-precision or
                 complex.
       ERRMSG  = If defined and passed, then any error messages will be
                 returned to the user in this parameter rather than
                 depending on the MESSAGE routine in IDL.  If no errors are
                 encountered, then a null string is returned.  In order to
                 use this feature, ERRMSG must be defined first, e.g.
                       ERRMSG = ''
                       FXBREAD, ERRMSG=ERRMSG, ...
                       IF ERRMSG NE '' THEN ...

       IEEE_TO_HOST, FXPAR, WHERE_NEGZERO, WHERENAN

       Uses common block FXBINTABLE--see "fxbintable.pro" for more
       information.

       The binary table file must have been opened with FXBOPEN.
       The data must be consistent with the column definition in the binary
       table header.
       The row number must be consistent with the number of rows stored in the
       binary table header.
       The number of elements implied by the dimensions keyword must not
       exceed the number of elements stored in the file.

       If the DIMENSIONS keyword is used, then the number of data points read
       in may be less than the number of points stored in the table.
       If there are no elements to read in (the number of elements is zero),
       then the program sets !ERR to -1, and DATA is unmodified.

       Data Handling, I/O, FITS, Generic.

       W. Thompson, Jan 1992.
       W. Thompson, Feb 1992, modified to support variable length arrays.
       W. Thompson, Jun 1992, modified way that row ranges are read in.  No
                              longer works reiteratively.
       W. Thompson, Jun 1992, fixed bug where NANVALUE would be modified by
                              TSCAL and TZERO keywords.
       W. Thompson, Jun 1992, fixed bug when reading character strings.
                              Treats dimensions better when reading multiple
                              rows.

       William Thompson, GSFC, January 1992.

       Version 1, William Thompson, GSFC, 12 April 1993.
               Incorporated into CDS library.
       Version 2, William Thompson, GSFC, 30 June 1993.
               Added overwrite keyword to REFORM call to speed up.
       Version 3, William Thompson, GSFC, 21 July 1993.
               Fixed bug with variable length arrays.
       Version 4, William Thompson, GSFC, 29 October 1993.
               Added error message for not finding column by name.
       Version 5, William Thompson, GSFC, 31 May 1994
               Added ERRMSG keyword.
       Version 6, William Thompson, GSFC, 23 June 1994
               Modified so that ERRMSG is not touched if not defined.
       Version 7, William Thompson, GSFC, 29 December 1994
               Fixed bug where single element dimensions were lost.
       Version 8, William Thompson, GSFC, 20 March 1995
               Fixed bug introduced in version 7.
       Version 9, Wayne Landsman, GSFC, 3 July 1996
               Fixed bug involving use of virtual keyword.
       Version 10, William Thompson, GSFC, 31-Jan-1997
               Added call to WHERE_NEGZERO.
       Version 11, Wayne Landsman, GSFC, 12 Aug, 1997
               Use IDL dcomplex datatype if needed
       Version 12, Wayne Landmsan, GSFC, 20 Feb, 1998
               Remove call to WHERE_NEGZERO (now part of IEEE_TO_HOST)
       Version 13, 18 Nov 1999, CM, Add NOIEEE keyword
       Version 14, 21 Aug 2000, William Thompson, GSFC
               Catch I/O errors

       Version 14, 21 Aug 2000

[Home Page] [Software, Documentation] [IDL Documentation] [Quick Reference] [Feedback]