Name

---

      TBGET

Purpose

---

      Return value(s) from specified column in a FITS binary table

Calling Sequence

---

      values = TBGET( h, tab, field, [ rows, nulls, /NOSCALE] )
              or
      values = TBGET( tb_str, tab, field, [ rows, nulls, /NOSCALE] )

Inputs

---

      h - FITS binary table header, e.g. as returned by FITS_READ
                      or
      tb_str - IDL structure extracted from FITS header by TBINFO.
              Use of the IDL structure will improve processing speed
      tab - FITS binary table array, e.g. as returned by FITS_READ
      field - field name or number, scalar

Optional Inputs

---

      rows - scalar or vector giving row number(s)
              Row numbers start at 0. If not supplied or set to
              -1 then values for all rows are returned

Optional Keyword Input

---

      /NOSCALE - If this keyword is set and nonzero, then the TSCALn and
              TZEROn keywords will *not* be used to scale to physical values
              Default is to perform scaling
      CONTINUE - This keyword does nothing, it is kept for consistency with
              with earlier versions of TBGET().

Outputs

---

      the values for the row are returned as the function value.
      Null values are set to 0 or blanks for strings.

Optional Output

---

      nulls - null value flag of same length as the returned data.
              Only used for integer data types, B, I, and J
              It is set to 1 at null value positions and 0 elsewhere.
              If supplied then the optional input, rows, must also
              be supplied.

Example

---

      Read the columns labeled 'WAVELENGTH' and 'FLUX' from the second
      extension of a FITS file 'spectra.fits' into IDL vectors w and f
      IDL> fits_read,'spectra.fits',tab,htab,exten=2 ;Read 2nd extension
      IDL> w = tbget(htab,tab,'wavelength')
      IDL> f = tbget(htab,tab,'flux')

Notes

---

      (1) If the column is variable length ('P') format, then TBGET() will
      return the longword array of pointers into the heap area. TBGET()
      currently lacks the ability to actually extract the data from the
      heap area.
      (2) Use the higher-level procedure FTAB_EXT (which calls TBGET()) to
      extract vectors directly from the FITS file.
      (3) Use the procedure FITS_HELP to determine which extensions are
      binary tables, and FTAB_HELP or TBHELP to determine the columns of the
      table

Procedure Calls

---

      TBINFO, TBSIZE

History

---

      Written W. Landsman February, 1991
      Work for string and complex W. Landsman April, 1993
      Default scaling by TSCALn, TZEROn, Added /NOSCALE keyword,
      Fixed nulls output, return longword pointers for variable length
              binary tables, W. Landsman December 1996
      Added a check for zero width column W. Landsman April, 1997
      Add TEMPORARY() and REFORM() for speed W. Landsman May, 1997
      Use new structure returned by TBINFO W. Landsman August 1997
      Add IS_IEEE_BIG(), No subscripting when all rows requested
                              W. Landsman March 2000
      Use SIZE(/TNAME) instead of DATATYPE() W. Landsman October 2001
      Bypass IEEE_TO_HOST call for improved speed W. Landsman November 2002
      Cosmetic changes to SIZE() calls W. Landsman December 2002
      Added unofficial support for 64bit integers W. Landsman February 2003
      Support unsigned integers, new pointer types of TSCAL and TZERO
      returned by TBINFO W. Landsman April 2003
      Add an i = i[0] for V6.0 compatibility W. Landsman August 2003
      Use faster BYTEORDER byteswapping W. Landsman April 2006
      Free pointers if FITS header supplied W. Landsman March 2007