This page was created by the IDL library routine `mk_html_help2`.

Last modified: Mon Aug 25 17:13:29 2025.

# Directory Listing of Routines

# external/astron/fits_table

- FTAB_DELROW
  Delete rows of data from a FITS ASCII or binary table extension
- FTAB_EXT
  Routine to extract columns from a FITS (binary or ASCII) table.
- FTAB_HELP
  Describe the columns of a FITS binary or ASCII table extension(s).
- FTAB_PRINT
  Print the contents of a FITS (binary or ASCII) table extension.
- FTADDCOL
  Routine to add a field to a FITS ASCII table
- FTCREATE
  Create a new (blank) FITS ASCII table and header with specified size.
- FTDELCOL
  Delete a column of data from a FITS table
- FTDELROW
  Delete a row of data from a FITS table
- FTGET
  Function to return value(s) from specified column in a FITS ASCII table
- FTHELP
  Routine to print a description of a FITS ASCII table extension
- FTHMOD
  Procedure to modify header information for a specified field
- FTINFO
  Return an informational structure from a FITS ASCII table header.
- FTKEEPROW
  Subscripts (and reorders) a FITS table. A companion piece to FTDELROW.
- FTPRINT
  Procedure to print specified columns and rows of a FITS table
- FTPUT
  Procedure to add or update a field in an FITS ASCII table
- FTSIZE
  Procedure to return the size of a FITS ASCII table.
- FTSORT
  Sort a FITS ASCII table according to a specified field
- TBDELCOL
  Delete a column of data from a FITS binary table
- TBDELROW
  Delete specified row or rows of data from a FITS binary table
- TBGET
  Return value(s) from specified column in a FITS binary table
- TBHELP
  Routine to print a description of a FITS binary table header
- TBINFO
  Return an informational IDL structure from a FITS binary table header.
- TBPRINT
  Procedure to print specified columns & rows of a FITS binary table
- TBSIZE
  Procedure to return the size of a FITS binary table.

# Routine Descriptions

## FTAB_DELROW

[Next Routine] [List of Routines]

     NAME:
           FTAB_DELROW
     PURPOSE:
           Delete rows of data from a FITS ASCII or binary table extension

     CALLING SEQUENCE:
           ftab_delrow, filename, rows, EXTEN_NO =, NEWFILE = ]

     INPUTS-OUPUTS
           filename - scalar string giving name of the FITS file containing an
                   ASCII or binary table extension.

           rows  -  scalar or vector, specifying the row numbers to delete
                   First row has index 0.   If a vector, it will be sorted and
                   duplicates will be removed

     OPTIONAL KEYWORD INPUTS:
           EXTEN_NO - scalar integer specifying which extension number to process
                   Default is to process the first extension
           NEWFILE - scalar string specifying the name of the new output FITS file
                   FTAB_DELROW will prompt for this parameter if not supplied

     EXAMPLE:
           Compress the first extension of a FITS file 'test.fits' to include
           only non-negative values in the 'FLUX' column

           ftab_ext,'test.fits','flux',flux       ;Obtain original flux vector
           bad = where(flux lt 0)                 ;Find negative fluxes
           ftab_delrow,'test.fits',bad,new='test1.fits'  ;Delete specified rows

     RESTRICTIONS:
           Does not work for variable length binary tables

     PROCEDURES USED:
           FITS_CLOSE, FITS_OPEN, FITS_READ, FITS_WRITE, FTDELROW, TBDELROW

     REVISION HISTORY:
           Written   W. Landsman        STX Co.     August, 1997
           Converted to IDL V5.0   W. Landsman   September 1997
           Use COPY_LUN if V5.6 or later     W. Landsman   February 2003
           Assume since V5.6, COPY_LUN available   W. Landsman   Sep 2006

(See external/astron/fits_table/ftab_delrow.pro)

## FTAB_EXT

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           FTAB_EXT
     PURPOSE:
           Routine to extract columns from a FITS (binary or ASCII) table.

     CALLING SEQUENCE:
           FTAB_EXT, name_or_fcb, columns, v1, [v2,..,v50, ROWS=, EXTEN_NO= ]
     INPUTS:
           name_or_fcb - either a scalar string giving the name of a FITS file
                   containing a (binary or ASCII) table, or an IDL structure
                   containing as file control block (FCB) returned by FITS_OPEN
                   If FTAB_EXT is to be called repeatedly on the same file, then
                   it is quicker to first open the file with FITS_OPEN, and then
                   pass the FCB structure to FTAB_EXT
           columns - table columns to extract.  Can be either
                   (1) String with names separated by commas
                   (2) Scalar or vector of column numbers

     OUTPUTS:
           v1,...,v50 - values for the columns.   Up to 50 columns can be extracted

     OPTIONAL INPUT KEYWORDS:
           ROWS -  scalar or vector giving row number(s) to extract
                   Row numbers start at 0.  If not supplied or set to
                   -1 then values for all rows are returned.    This keyword
                   works for ASCII tables and binary tables where every column has
                   the same number of elements, but not for variable length
                   binary tables.
           EXTEN_NO - Extension number to process.   If not set, then data is
                   extracted from the first extension in the file (EXTEN_NO=1)

     EXAMPLES:
           Read wavelength and flux vectors from the first extension of a
           FITS file, 'spec.fit'.   Using FTAB_HELP,'spec.fit' we find that this
           information is in columns named 'WAVELENGTH' and 'FLUX' (in columns 1
           and 2).   To read the data

           IDL> ftab_ext,'spec.fit','wavelength,flux',w,f
                   or
           IDL> ftab_ext,'spec.fit',[1,2],w,f

     PROCEDURES CALLED:
           FITS_READ, FITS_CLOSE, FTINFO, FTGET(), TBINFO, TBGET()
     HISTORY:
           version 1        W.   Landsman         August 1997
           Improve speed processing binary tables  W. Landsman   March 2000
           Use new FTINFO calling sequence  W. Landsman   May 2000
           Don't call fits_close if fcb supplied W. Landsman May 2001
           Use STRSPLIT to parse column string  W. Landsman July 2002
           Cleanup pointers in TBINFO structure  W. Landsman November 2003
           Avoid EXECUTE() if V6.1 or later  W. Landsamn   December 2006
           Assume since V6.1  W. Landsman   June 2009
           Read up to 30 columns  W.L. Aug 2009
           Setting ROWS = -1 should work as documented, accept up to 50
                   columns  W.L.  Oct 2013

(See external/astron/fits_table/ftab_ext.pro)

## FTAB_HELP

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           FTAB_HELP
     PURPOSE:
           Describe the columns of a FITS binary or ASCII table extension(s).

     CALLING SEQUENCE:
           FTAB_HELP, filename, [ EXTEN_No = , TEXTOUT= ]
                   or
           FTAB_HELP, fcb, [EXTEN_No=, TEXTOUT= ]

     INPUTS:
           filename - scalar string giving name of the FITS file.
           fcb - FITS control block returned by a previous call to FITS_OPEN

     OPTIONAL KEYWORD INPUTS:
           EXTEN_NO - integer scalar or vector specifying which FITS extensions
                   to display.    Default is to display all FITS extension.
           TEXTOUT - scalar number (0-7) or string (file name) determining
                   output device (see TEXTOPEN).  Default is TEXTOUT=1, output
                   to the user's terminal

     EXAMPLE:
           Describe the columns in the second and fourth extensions of a FITS
           file spec.fits and write the results to a file 'spec24.lis'

           IDL> ftab_help,'spec.fits',exten=[2,4],t='spec24.lis'

     SYSTEM VARIABLES:
            Uses the non-standard system variables !TEXTOUT and !TEXTUNIT
           which must be defined (e.g. with ASTROLIB) before compilation
     NOTES:
           The behavior of FTAB_HELP was changed in August 2005 to display
           all extensions by default, rather than just the first extension
     PROCEDURES USED:
           FITS_READ, FITS_CLOSE, FITS_OPEN, FTHELP, TBHELP, TEXTOPEN, TEXTCLOSE
     HISTORY:
           version 1  W. Landsman    August 1997
           Corrected documentation W. Landsman   September 1997
           Don't call fits_close if fcb supplied W. Landsman May 2001
           Default now is to display all extensions, EXTEN keyword can now
            be a vector   W. Landsman Aug 2005

(See external/astron/fits_table/ftab_help.pro)

## FTAB_PRINT

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           FTAB_PRINT
     PURPOSE:
           Print the contents of a FITS (binary or ASCII) table extension.
     EXPLANATION:
           User can specify which rows or columns to print

     CALLING SEQUENCE:
           FTAB_PRINT, filename, columns, rows,
                       [ TEXTOUT=, FMT=, EXTEN_NO= NUM_HEADER_LINES ]

     INPUTS:
           filename - scalar string giving name of a FITS file containing a
                   binary or ASCII table
           columns - string giving column names, or vector giving
                   column numbers (beginning with 1).  If a string
                   supplied then column names should be separated by comma's.
                   if not supplied, then all columns are printed.
                   If set to '*' then all columns are printed in table format
                   (1 row per line, binary tables only).
           rows - (optional) vector of row numbers to print (beginning with 0).
                   If not supplied or set to scalar, -1, then all rows
                   are printed.
     OPTIONAL KEYWORD INPUT:
           EXTEN_NO - Extension number to read.   If not set, then the first
                   extension is printed (EXTEN_NO=1)
           FMT = Format string for print display (binary tables only).   If not
                   supplied, then any formats in the TDISP keyword fields will be
                   used, otherwise IDL default formats.    For ASCII tables, the
                   format used is always as stored in the FITS table.
           NUM_HEADER_LINES - Number of lines to display the column headers (default
                   = 1).  By setting NUM_HEADER_LINES to an integer larger than 1,
                   one can avoid truncation of the headers.   In addition, setting
                   NUM_HEADER_LINES will display commented lines indicating
                   a FORMAT for reading the data, and a suggested call to
                  readfmt.pro.    Works for binary tables only
           NVAL_PER_LINE - The maximum number of values displayed from a
                   multivalued column when printing in table format.   Default = 6
           TEXTOUT - scalar number (0-7) or string (file name) determining
                   output device (see TEXTOPEN).  Default is TEXTOUT=1, output
                   to the user's terminal
     EXAMPLE:
           (1) Print all rows of the first 5 columns of the first extension of the
           file 'wfpc.fits'
                   IDL> ftab_print,'vizier.fits',indgen(5)+1

           (2) Print all columns of the first row to a file 'vizier.dat' in
           'table' format
                   IDL> ftab_print,'vizier.fits',t='vizier.dat','*',0
     SYSTEM VARIABLES:
           Uses the non-standard system variables !TEXTOUT and !TEXTUNIT
           which must be defined (e.g. with ASTROLIB) prior to compilation.
     PROCEDURES USED:
           FITS_CLOSE, FITS_OPEN, FITS_READ, FTPRINT, TBPRINT
     HISTORY:
           version 1  W. Landsman    August 1997
           Check whether data exists   W. Landsman    Feb 2007
           Check whether extension exists  W. Landsman  Mar 2010
           Added NUM_HEADER_LINES, NVAL_PER_LINE keywords for binary tables
                      W. Landsman Apr 2010

(See external/astron/fits_table/ftab_print.pro)

## FTADDCOL

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
          FTADDCOL
     PURPOSE:
          Routine to add a field to a FITS ASCII table

     CALLING SEQUENCE:
          ftaddcol, h, tab, name, idltype, [ tform, tunit, tscal, tzero, tnull ]

     INPUTS:
          h - FITS table header.  It will be updated as appropriate
          tab - FITS table array.  Number of columns will be increased if
                   neccessary.
          name - field name, scalar string
          idltype - idl data type (as returned by SIZE function) for field,
                   For string data (type=7) use minus the string length.

     OPTIONAL INPUTS:
           tform - format specification 'qww.dd' where q = A, I, E, or D
           tunit - string giving physical units for the column.
           tscal - scale factor
           tzero - zero point for field
           tnull - null value for field

           Use '' as the value of tform,tunit,tscal,tzero,tnull if you want
           the default or no specification of them in the table header.

     OUTPUTS:
           h,tab - updated to allow new column of data

     PROCEDURES USED:
           FTINFO, FTSIZE, GETTOK(), SXADDPAR
     HISTORY:
           version 1  D. Lindler   July, 1987
           Converted to IDL V5.0   W. Landsman   September 1997
           Updated call to new FTINFO   W. Landsman   April 2000

(See external/astron/fits_table/ftaddcol.pro)

## FTCREATE

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           FTCREATE
     PURPOSE:
           Create a new (blank) FITS ASCII table and header with specified size.

     CALLING SEQUENCE:
           ftcreate, maxcols, maxrows, h, tab

     INPUTS:
           maxcols - number of character columns allocated, integer scalar
           maxrows - maximum number of rows allocated, integer scalar

     OUTPUTS:
           h - minimal FITS Table extension header, string array
     OPTIONAL OUTPUT:
           tab - empty table, byte array
     HISTORY:
           version 1  D. Lindler   July. 87
           Converted to IDL V5.0   W. Landsman   September 1997
           Make table creation optional, allow 1 row table, add comments to
           required FITS keywords    W. Landsman    October 2001

(See external/astron/fits_table/ftcreate.pro)

## FTDELCOL

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
    	FTDELCOL
     PURPOSE:
    	Delete a column of data from a FITS table

     CALLING SEQUENCE:
    	ftdelcol, h, tab, name

     INPUTS-OUPUTS
    	h,tab - FITS table header and data array.  H and TAB will
    		be updated with the specified column deleted

     INPUTS:
    	name - Either (1) a string giving the name of the column to delete
    		or (2) a scalar giving the column number to delete (starting with 1)
           Only 1 column can be deleted at a time

     EXAMPLE:
    	Suppose it has been determined that the F7.2 format used for a field
    	FLUX in a FITS table is insufficient.  The old column must first be
    	deleted before a new column can be written with a new format.

    	flux = FTGET(h,tab,'FLUX')       ;Save the existing values
    	FTDELCOL,h,tab,'FLUX'            ;Delete the existing column
    	FTADDCOL,h,tab,'FLUX',8,'F9.2'   ;Create a new column with larger format
    	FTPUT,h,tab,'FLUX',0,flux        ;Put back the original values

     REVISION HISTORY:
    	Written   W. Landsman        STX Co.     August, 1988
    	Adapted for IDL Version 2, J. Isensee, July, 1990
       Updated call to new FTINFO   W. Landsman  May 2000
       Allow specification of column number in addition to field name
           M. Nolan/W. Landsman  Sep 2015

(See external/astron/fits_table/ftdelcol.pro)

## FTDELROW

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           FTDELROW
     PURPOSE:
           Delete a row of data from a FITS table

     CALLING SEQUENCE:
           ftdelrow, h, tab, rows

     INPUTS-OUPUTS
           h,tab - FITS table header and data array.  H and TAB will
                   be updated on output with the specified row(s) deleted.
           rows  -  scalar or vector, specifying the row numbers to delete
                   This vector will be sorted and duplicates removed by FTDELROW

     EXAMPLE:
           Compress a table to include only non-negative flux values

           flux = FTGET(h,tab,'FLUX')       ;Obtain original flux vector
           bad = where(flux lt 0)           ;Find negative fluxes
           FTDELROW,h,tab,bad               ;Delete rows with negative fluxes

     PROCEDURE:
           Specified rows are deleted from the data array, TAB.  The NAXIS2
           keyword in the header is updated.

     PROCEDURES USED:
           sxaddpar

     REVISION HISTORY:
           Written   W. Landsman        STX Co.     August, 1988
           Checked for IDL Version 2, J. Isensee, July, 1990
           Converted to IDL V5.0   W. Landsman   September 1997
           Assume since V5.4, use BREAK instead of GOTO  W. Landsman April 2006

(See external/astron/fits_table/ftdelrow.pro)

## FTGET

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
          FTGET
     PURPOSE:
          Function to return value(s) from specified column in a FITS ASCII table

     CALLING SEQUENCE
          values = FTGET( h, tab, field, [ rows, nulls ] )
                        or
          values = FTGET( ft_str, tab, field. [rows, nulls]
     INPUTS:
          h - FITS ASCII extension header (e.g. as returned by FITS_READ)
                                or
          ft_str - FITS table structure extracted from FITS header by FTINFO
                    Use of the IDL structure will improve processing speed
          tab - FITS ASCII table array (e.g. as returned by FITS_READ)
          field - field name or number

     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

     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.
                   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
           (ASCII table) extension of a FITS file 'spectra.fit'

           IDL> fits_read,'spectra.fit',tab,htab,exten=2     ;Read 2nd extension
           IDL> w = ftget( htab, tab,'wavelength')      ;Wavelength vector
           IDL> f = ftget( htab, tab,'flux')            ;Flux vector

           Slightly more efficient would be to first call FTINFO
           IDL> ftinfo, htab, ft_str                     ;Extract structure
           IDL> w = ftget(ft_str, tab,'wavelength')      ;Wavelength vector
           IDL> f = ftget(ft_str, tab,'flux')            ;Flux vector

     NOTES:
           (1) Use the higher-level procedure FTAB_EXT to extract vectors
                   directly from the FITS file.
           (2) Use FTAB_HELP or FTHELP to determine the columns in a particular
                   ASCII table.
     HISTORY:
           coded by D. Lindler  July, 1987
           Always check for null values    W. Landsman          August 1990
           More informative error message  W. Landsman          Feb. 1996
           Converted to IDL V5.0   W. Landsman   September 1997
           Allow structure rather than FITS header  W. Landsman   May 2000
           No case sensitivity in TTYPE name      W. Landsman   February 2002

(See external/astron/fits_table/ftget.pro)

## FTHELP

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           FTHELP
     PURPOSE:
           Routine to print a description of a FITS ASCII table extension

     CALLING SEQUENCE:
           FTHELP, H, [ TEXTOUT = ]

     INPUTS:
           H - FITS header for ASCII table extension, string array

     OPTIONAL INPUT KEYWORD
           TEXTOUT - scalar number (0-7) or string (file name) determining
                   output device (see TEXTOPEN).  Default is TEXTOUT=1, output
                   to the user's terminal

     NOTES:
           FTHELP checks that the keyword XTENSION  equals 'TABLE' in the FITS
                   header.

     SYSTEM VARIABLES:
           Uses the non-standard system variables !TEXTOUT and !TEXTUNIT
           which must be defined (e.g. with ASTROLIB) prior to compilation.
     PROCEDURES USED:
           REMCHAR, SXPAR(), TEXTOPEN, TEXTCLOSE, ZPARCHECK

     HISTORY:
           version 1  W. Landsman  Jan. 1988
           Add TEXTOUT option, cleaner format  W. Landsman   September 1991
           TTYPE value can be longer than 8 chars,  W. Landsman  August 1995
           Remove calls to !ERR, some vectorization  W. Landsman  February 2000
           Slightly more compact display  W. Landsman  August 2005

(See external/astron/fits_table/fthelp.pro)

## FTHMOD

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           FTHMOD
     PURPOSE:
           Procedure to modify header information for a specified field
           in a FITS table.

     CALLING SEQUENCE:
           fthmod, h, field, parameter, value

     INPUT:
           h - FITS header for the table
           field - field name or number
           parameter - string name of the parameter to modify.  Choices
                   include:
                           TTYPE - field name
                           TUNIT - physical units for field (eg. 'ANGSTROMS')
                           TNULL - null value (string) for field, (eg. '***')
                           TFORM - format specification for the field
                           TSCAL - scale factor
                           TZERO - zero offset
                   User should be aware that the validity of the change is
                   not checked.  Unless you really know what you are doing,
                   this routine should only be used to change field names,
                   units, or another user specified parameter.
           value - new value for the parameter.  Refer to the FITS table
                   standards documentation for valid values.

     EXAMPLE:
          Change the units for a field name "FLUX" to "Janskys" in a FITS table
            header,h

          IDL> FTHMOD, h, 'FLUX', 'TUNIT','Janskys'
     METHOD:
           The header keyword <parameter><field number> is modified
           with the new value.
     HISTORY:
           version 1, D. Lindler  July 1987
           Converted to IDL V5.0   W. Landsman   September 1997
           Major rewrite to use new FTINFO call   W. Landsman   May 2000

(See external/astron/fits_table/fthmod.pro)

## FTINFO

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           FTINFO
     PURPOSE:
           Return an informational structure from a FITS ASCII table header.
     CALLING SEQUENCE:
           ftinfo,h,ft_str, [Count = ]

     INPUTS:
           h - FITS ASCII table header, string array

     OUTPUTS:
           ft_str - IDL structure with extracted info from the FITS ASCII table
                    header.   Tags include
            .tbcol - starting column position in bytes
            .width - width of the field in bytes
            .idltype - idltype of field.
                           7 - string, 4- real*4, 3-integer, 5-real*8
            .tunit - string unit numbers
            .tscal - scale factor
            .tzero - zero point for field
            .tnull - null value for the field
            .tform - format for the field
            .ttype - field name

     OPTIONAL OUTPUT KEYWORD:
           Count - Integer scalar giving number of fields in the table
     PROCEDURES USED:
           GETTOK(), SXPAR()
     NOTES:
           This procedure underwent a major revision in May 2000, and **THE
           NEW CALLING SEQUENCE IS INCOMPATIBLE WITH THE OLD ONE **
     HISTORY:
           D. Lindler  July, 1987
           Converted to IDL V5.0   W. Landsman   September 1997
           Major rewrite, return structure   W. Landsman   April 2000

(See external/astron/fits_table/ftinfo.pro)

## FTKEEPROW

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
    	FTKEEPROW
     PURPOSE:
    	Subscripts (and reorders) a FITS table.  A companion piece to FTDELROW.

     CALLING SEQUENCE:
    	ftkeeprow, h, tab, subs

     INPUT PARAMETERS:
    	h    = FITS table header array
    	tab  = FITS table data array
    	subs = subscript array of FITS table rows.  Works like any other IDL
    		subscript array (0 based, of course).

     OUTPUT PARAMETERS:
    	h and tab are modified

     MODIFICATION HISTORY:
    	Written by R. S. Hill, ST Sys. Corp., 2 May 1991.
    	Converted to IDL V5.0   W. Landsman   September 1997

(See external/astron/fits_table/ftkeeprow.pro)

## FTPRINT

[Previous Routine] [Next Routine] [List of Routines]

      NAME:
          FTPRINT
      PURPOSE:
           Procedure to print specified columns and rows of a FITS table

     CALLING SEQUENCE:
           FTPRINT, h, tab, columns, [ rows, TEXTOUT = ]

     INPUTS:
           h - Fits header for table, string array
           tab - table array
           columns - string giving column names, or vector giving
                   column numbers (beginning with 1).  If string
                   supplied then column names should be separated by comma's.
           rows - (optional) vector of row numbers to print.  If
                   not supplied or set to scalar, -1, then all rows
                   are printed.

     OUTPUTS:
           None

     OPTIONAL INPUT KEYWORDS:
           TEXTOUT controls the output device; see the procedure TEXTOPEN

     SYSTEM VARIABLES:
           Uses nonstandard system variables !TEXTOUT and !TEXTOPEN
           These will be defined (using ASTROLIB) if not already present.
           Set !TEXTOUT = 3 to direct output to a disk file.   The system
           variable is overriden by the value of the keyword TEXTOUT

     EXAMPLES:

           ftprint,h,tab,'STAR ID,RA,DEC'    ;print id,ra,dec for all stars
           ftprint,h,tab,[2,3,4],indgen(100) ;print columns 2-4 for
                                             ;first 100 stars
           ftprint,h,tab,text="stars.dat"    ;Convert entire FITS table to
                                             ;an ASCII file named STARS.DAT

     PROCEDURES USED:
           FTSIZE, FTINFO, TEXTOPEN, TEXTCLOSE

     RESTRICTIONS:
           (1) Program does not check whether output length exceeds output
                   device capacity (e.g. 80 or 132).
           (2) Column heading may be truncated to fit in space defined by
                   the FORMAT specified for the column
           (3) Program does not check for null values

     HISTORY:
           version 1  D. Lindler Feb. 1987
           Accept undefined values of rows, columns   W. Landsman August 1997
           New FTINFO calling sequence    W. Landsman   May 2000
           Parse scalar string with STRSPLIT   W. Landsman  July 2002
           Fix format display of row number  W. Landsman March 2003
           Fix format display of row number again  W. Landsman May 2003

(See external/astron/fits_table/ftprint.pro)

## FTPUT

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           FTPUT
     PURPOSE:
           Procedure to add or update a field in an FITS ASCII table
     CALLING SEQUENCE:
           FTPUT, htab, tab, field, row, values, [ nulls ]

     INPUTS:
           htab - FITS ASCII table header string array
           tab - FITS ASCII table array (e.g. as read by READFITS)
           field - string field name or integer field number
           row -  either a non-negative integer scalar giving starting row to
                   update, or a non-negative integer vector specifying rows to
                   update.   FTPUT will append a new row to a table if the value
                   of 'row' exceeds the number of rows in the tab array
           values - value(s) to add or update.   If row is a vector
                   then values must contain the same number of elements.

     OPTIONAL INPUT:
           nulls - null value flag of same length as values.
                   It should be set to 1 at null value positions
                   and 0 elsewhere.

     OUTPUTS:
           htab,tab will be updated as specified.

     EXAMPLE:
           One has a NAME and RA  and Dec vectors for 500 stars with formats A6,
           F9.5 and F9.5 respectively.   Write this information to an ASCII table
           named 'star.fits'.

           IDL> FTCREATE,24,500,h,tab       ;Create table header and (empty) data
           IDL> FTADDCOL,h,tab,'RA',8,'F9.5','DEGREES'   ;Explicity define the
           IDL> FTADDCOL,h,tab,'DEC',8,'F9.5','DEGREES'  ;RA and Dec columns
           IDL> FTPUT,h,tab,'RA',0,ra       ;Insert RA vector into table
           IDL> FTPUT,h,tab,'DEC',0,dec       ;Insert DEC vector into table
           IDL> FTPUT, h,tab, 'NAME',0,name   ;Insert NAME vector with default
           IDL> WRITEFITS,'stars.fits',tab,h ;Write to a file

          Note that (1) explicit formatting has been supplied for the (numeric)
          RA and Dec vectors, but was not needed for the NAME vector, (2) A width
          of 24 was supplied in FTCREATE based on the expected formats (6+9+9),
          though the FT* will adjust this value as necessary, and (3) WRITEFITS
          will create a minimal primary header
     NOTES:
           (1) If the specified field is not already in the table, then FTPUT will
           create a new column for that field using default formatting.   However,
            FTADDCOL should be called prior to FTPUT for explicit formatting.

     PROCEDURES CALLED
           FTADDCOL, FTINFO, FTSIZE, SXADDPAR, SXPAR()
     HISTORY:
           version 1  D. Lindler July, 1987
           Allow E format         W. Landsman          March 1992
           Write in F format if E format will overflow    April 1994
           Update documentation W. Landsman   January 1996
           Allow 1 element vector  W. Landsman   March 1996
           Adjust string length to maximum of input string array   June 1997
           Work for more than 32767 elements August 1997
           Converted to IDL V5.0   W. Landsman   September 1997
           Updated call to the new FTINFO   W. Landsman   May 2000
           Fix case where header does not have any columns yet W.Landsman Sep 2002
           Assume since V5.2, omit fstring() call  W. Landsman April 2006

(See external/astron/fits_table/ftput.pro)

## FTSIZE

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           FTSIZE
     PURPOSE:
           Procedure to return the size of a FITS ASCII table.

     CALLING SEQUENCE:
           ftsize,h,tab,ncols,rows,tfields,ncols_all,nrows_all, [ERRMSG = ]

     INPUTS:
           h - FITS ASCII table header, string array
           tab - FITS table array, 2-d byte array

     OUTPUTS:
           ncols - number of characters per row in table
           nrows - number of rows in table
           tfields - number of fields per row
           ncols_all - number of characters/row allocated (size of tab)
           nrows_all - number of rows allocated

     OPTIONAL OUTPUT KEYWORD:
           ERRMSG  = If this keyword is present, 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.
     HISTORY
           D. Lindler  July, 1987
           Fix for 1-row table,  W. Landsman    HSTX,     June 1994
           Converted to IDL V5.0   W. Landsman   September 1997
           Added ERRMSG keyword   W. Landsman   May 2000

(See external/astron/fits_table/ftsize.pro)

## FTSORT

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
          FTSORT
     PURPOSE:
          Sort a FITS ASCII table according to a specified field

     CALLING SEQUENCE:
          FTSORT,h,tab,[field, REVERSE = ]               ;Sort original table header and array
                   or
          FTSORT,h,tab,hnew,tabnew,[field, REVERSE =]   ;Create new sorted header

     INPUTS:
          H - FITS header (string array)
          TAB - FITS table (byte array) associated with H.  If less than 4
                   parameters are supplied, then H and TAB will be updated to
                   contain the sorted table

     OPTIONAL INPUTS:
          FIELD - Field name(s) or number(s) used to sort the entire table.
                  If FIELD is a vector then the first element is used for the
                  primary sort, the second element is used for the secondary
                  sort, and so forth.   (A secondary sort only takes effect when
                  values in the primary sort  field are equal.)  Character fields
                  are sorted using the ASCII collating sequence.  If omitted,
                  the user will be prompted for the field name.

     OPTIONAL OUTPUTS:
          HNEW,TABNEW - Header and table containing the sorted tables

     EXAMPLE:
          Sort a FITS ASCII table by the 'DECLINATION' field in descending order
          Assume that the table header htab, and array, tab, have already been
          read (e.g. with READFITS or FITS_READ):

          IDL> FTSORT, htab, tab,'DECLINATION',/REVERSE
     OPTIONAL INPUT KEYWORD:
           REVERSE - If set then the table is sorted in reverse order (maximum
                  to minimum.    If FIELD is a vector, then REVERSE can also be
                  a vector.   For example, REVERSE = [1,0] indicates that the
                  primary sort should be in descending order, and the secondary
                  sort should be in ascending order.

     EXAMPLE:
     SIDE EFFECTS:
           A HISTORY record is added to the table header.
     REVISION HISTORY:
          Written W. Landsman                         June, 1988
          Converted to IDL V5.0   W. Landsman   September 1997
          New FTINFO calling sequence, added REVERSE keyword, allow secondary sorts
                      W. Landsman   May 2000

(See external/astron/fits_table/ftsort.pro)

## TBDELCOL

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           TBDELCOL
     PURPOSE:
           Delete a column of data from a FITS binary table

     CALLING SEQUENCE:
           TBDELCOL, h, tab, name

     INPUTS-OUPUTS
           h,tab - FITS binary table header and data array.  H and TAB will
                   be updated with the specified column deleted

     INPUTS:
           name - Either (1) a string giving the name of the column to delete
                           or (2) a scalar giving the column number to delete

     EXAMPLE:
           Delete the column "FLUX" from FITS binary table test.fits

           IDL> tab = readfits('test.fits',h,/ext)    ;Read table
           IDL> tbdelcol, h, tab, 'FLUX'              ;Delete Flux column
           IDL> modfits,'test.fits',tab,h,/ext        ;Write back table

     PROCEDURES USED:
           SXADDPAR, TBINFO, TBSIZE
     REVISION HISTORY:
           Written   W. Landsman        STX Co.     August, 1988
           Use new structure returned by TBINFO,  August, 1997
           Use SIZE(/TNAME) instead of DATATYPE()   October 2001
           Use /NOSCALE in call to TBINFO, update TDISP   W. Landsman   March 2007

(See external/astron/fits_table/tbdelcol.pro)

## TBDELROW

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
    	TBDELROW
     PURPOSE:
    	Delete specified row or rows of data from a FITS binary table

     CALLING SEQUENCE:
    	TBDELROW, h, tab, rows

     INPUTS-OUPUTS
    	h,tab - FITS binary table header and data array.  H and TAB will
    		be updated on output with the specified row(s) deleted.

    	rows  -  scalar or vector, specifying the row numbers to delete
    		First row has index 0.   If a vector it will be sorted and
    		duplicates removed by TBDELROW

     EXAMPLE:
    	Compress a table to include only non-negative flux values

    	flux = TBGET(h,tab,'FLUX')       ;Obtain original flux vector
    	bad = where(flux lt 0)           ;Find negative fluxes
    	TBDELROW,h,tab,bad               ;Delete rows with negative fluxes

     PROCEDURE:
    	Specified rows are deleted from the data array, TAB.  The NAXIS2
    	keyword in the header is updated.

     REVISION HISTORY:
    	Written   W. Landsman        STX Co.     August, 1988
    	Checked for IDL Version 2, J. Isensee, July, 1990
    	Converted to IDL V5.0   W. Landsman   September 1997

(See external/astron/fits_table/tbdelrow.pro)

## TBGET

[Previous Routine] [Next Routine] [List of Routines]

     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
     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
           Use V6.0 notation W. Landsman  April 2014
           Remove nonfunctional CONTINUE keyword W. Landsman  May 2017

(See external/astron/fits_table/tbget.pro)

## TBHELP

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           TBHELP
     PURPOSE:
           Routine to print a description of a FITS binary table header

     CALLING SEQUENCE:
           TBHELP, h, [TEXTOUT = ]

     INPUTS:
           h - FITS header for a binary table, string array

     OPTIONAL INPUT KEYWORD:
           TEXTOUT - scalar number (0-7) or string (file name) controling
                   output device (see TEXTOPEN).  Default is TEXTOUT=1, output
                   to the user's terminal

     METHOD:
           FITS Binary Table keywords NAXIS*,EXTNAME,TFIELDS,TTYPE*,TFORM*,TUNIT*,
           are read from the header and displayed at the terminal

           A FITS header is recognized as bein for a binary table if the keyword
           XTENSION has the value 'BINTABLE' or 'A3DTABLE'

     NOTES:
           Certain fields may be truncated in the display
     SYSTEM VARIABLES:
           Uses the non-standard system variables !TEXTOUT and !TEXTUNIT.   These
           are automatically defined by TBHELP if they have not been defined
           previously.
     PROCEDURES USED:
           REMCHAR, SXPAR(), TEXTCLOSE, TEXTOPEN, ZPARCHECK
     HISTORY:
           W. Landsman       February, 1991
           Parsing of a FITS binary header made more robust    May, 1992
           Added TEXTOUT keyword      August 1997
           Define !TEXTOUT if not already present   W. Landsman  November 2002
           Slightly more compact display   W. Landsman August 2005
           Fix Aug 2005 error omitting TFORM display W. Landsman Sep 2005

(See external/astron/fits_table/tbhelp.pro)

## TBINFO

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           TBINFO
     PURPOSE:
           Return an informational IDL structure from a FITS binary table header.

     CALLING SEQUENCE:
           tbinfo, h, tb_str, [ERRMSG = ]
     INPUTS:
           h - FITS binary table header, e.g. as returned by READFITS()

     OUTPUTS:
           tb_str - IDL structure with extracted info from the FITS binary table
                   header.   Tags include
           .tbcol - starting column position in bytes, integer vector
           .width - width of the field in bytes, integer vector
           .idltype - idltype of field, byte vector
                   7 - string, 4- real*4, 3-integer*4, 5-real*8
           .numval - repeat count, 64 bit longword vector
           .tunit - string unit numbers, string vector
           .tnull - integer null value for the field, stored as a string vector
                     so that an empty string indicates that TNULL is not present
           .tform - format for the field, string vector
           .ttype - field name, string vector
           .maxval- maximum number of elements in a variable length array, long
                   vector
           .tscal - pointer array giving the scale factor for converting to
                    physical values, default 1.0
           .tzero - pointer array giving the additive offset for converting to
                    physical values, default 0.0
           .tdisp - recommended output display format

           All of the output vectors will have same number of elements, equal
           to the number of columns in the binary table.

           The .tscal and .tzero values are stored as pointers so as to preserve
           the individual data types (e.g. float or double) which may differ
           in different columns.   For example, to obtain the value of TSCAL for
           the third column use *tab_str.tscal[2]
     OPTIONAL INPUT KEYWORD:
           /NOSCALE - if set, then the TSCAL* and TZERO* keywords are not extracted
                from the FITS header, and the .tscal and .tzero pointers do not
                appear in the output structure.
     OPTIONAL OUTPUT KEYWORD:
            ERRMSG = if present, then error messages are returned in this keyword
                rather than displayed using the MESSAGE facility
     PROCEDURES USED:
           SXPAR()
     NOTES:
           For variable length ('P' format) column, TBINFO returns values for
           reading the 2 element longward array of pointers (numval=2,
           idltype = 3, width=4)
     HISTORY:
           Major rewrite to return a structure      W. Landsman   August 1997
           Added "unofficial" 64 bit integer "K" format W. Landsamn Feb. 2003
           Store .tscal and .tzero tags as pointers, so as to preserve
           type information   W. Landsman          April 2003
           Treat repeat count for string as specifying string length, not number
              of elements, added ERRMSG    W. Landsman        July 2006
           Treat logical as character string 'T' or 'F' W. Landsman  October 2006
           Added NOSCALE keyword  W. Landsman   March 2007
           Make .numval 64 bit for very large tables  W. Landsman   April 2014
           Make sure XTENSION is for a FITS binary table W. Landsman  May 2017

(See external/astron/fits_table/tbinfo.pro)

## TBPRINT

[Previous Routine] [Next Routine] [List of Routines]

     NAME:
           TBPRINT
      PURPOSE:
           Procedure to print specified columns & rows of a FITS binary table

     CALLING SEQUENCE:
           TBPRINT, h, tab, columns, [ rows, TEXTOUT =, FMT=, NUM_HEADER= ]
                   or
           TBPRINT,tb_str, tab, columns, [ rows, TEXTOUT =, FMT=, NUM_HEADER =  ]

     INPUTS:
           h - FITS header for table, string array
                           or
           tb_str - IDL structure extracted from FITS header by TBINFO, useful
               when TBPRINT is called many times with the same header
           tab - table array
           columns - string giving column names, or vector giving
                   column numbers (beginning with 1).  If string
                   supplied then column names should be separated by comma's.
                   If set to '*' then all columns are printed in table format
                   (1 row per line, binary tables only).
           rows - (optional) vector of row numbers to print.  If
                   not supplied or set to scalar, -1, then all rows
                   are printed.

     OUTPUTS:
           None
     OPTIONAL INPUT KEYWORDS:
           FMT = Format string for print display.   If not supplied, then any
                   formats in the TDISP keyword fields of the table will be
                   used, otherwise IDL default formats.
           NUM_HEADER_LINES - Number of lines to display the column headers
                   default = 1).  By setting NUM_HEADER_LINES to an integer larger
                   than 1, one can avoid truncation of the column header labels.
                   In addition, setting NUM_HEADER_LINES will display commented
                   lines indicating a FORMAT for reading the data, and a
                   suggested call to  readfmt.pro.
           NVAL_PER_LINE - The maximum number of values displayed from a multivalued
                   column when printing in table format.   Default = 6
           TEXTOUT - scalar number (0-7) or string (file name) determining
                   output device (see TEXTOPEN).  Default is TEXTOUT=1, output
                   to the user's terminal
     SYSTEM VARIABLES:
           Uses nonstandard system variables !TEXTOUT and !TEXTOPEN
           Set !TEXTOUT = 3 to direct output to a disk file.   The system
           variable is overriden by the value of the keyword TEXTOUT

     EXAMPLES:
           tab = readfits('test.fits',htab,/ext) ;Read first extension into vars
           tbprint,h,tab,'STAR ID,RA,DEC'    ;print id,ra,dec for all stars
           tbprint,h,tab,[2,3,4],indgen(100) ;print columns 2-4 for
                                              first 100 stars
           tbprint,h,tab,text="stars.dat"    ;Convert entire FITS table to
                                             ;an ASCII file named 'stars.dat'

     PROCEDURES USED:
           GETTOK(), STRNUMBER(), TEXTOPEN, TEXTCLOSE, TBINFO

     RESTRICTIONS:
           (1) Program does not check whether output length exceeds output
                   device capacity (e.g. 80 or 132).
           (2) Column heading may be truncated to fit in space defined by
                   the FORMAT specified for the column.    Use NUM_HEADER_LINES
                   to avoid truncation.
           (3) Program does not check for null values
           (4) Does not work with variable length columns
           (5) Will only the display the first value of fields with multiple values
            (unless there is one row each with the same number of mulitple values)
            If printing in table format (column='*') then up to 6 values
            can be printed per line.

     HISTORY:
           version 1  D. Lindler Feb. 1987
           Accept undefined values of rows,columns W. Landsman  August 1997
           Use new structure returned by TBINFO    W. Landsman  August 1997
           Made formatting more robust    W. Landsman   March 2000
           Use STRSPLIT to parse string column listing W. Landsman July 2002
           Wasn't always printing last row   W. Landsman  Feb. 2003
           Better formatting (space between columns) W. Landsman Oct. 2005
           Use case-insensitive match with TTYPE, use STRJOIN W.L. June 2006
           Fixed check for multiple values W.L. August 2006
           Fixed bad index value in August 2006 fix  W.L Aug 15 2006
           Free-up pointers after calling TBINFO  W.L. Mar 2007
           Add table format capability  W.L. Mar 2010
           Add NUM_HEADER_LINE keyword  P. Broos Apr 2010

(See external/astron/fits_table/tbprint.pro)

## TBSIZE

[Previous Routine] [List of Routines]

     NAME:
           TBSIZE

     PURPOSE:
           Procedure to return the size of a FITS binary table.

     CALLING SEQUENCE:
           tbsize, h, tab, ncols, nrows, tfields, ncols_all, nrows_all

     INPUTS:
           h - FITS table header
           tab - FITS table array

     OUTPUTS:
           ncols - number of characters per row in table
           nrows - number of rows in table
           tfields - number of fields per row
           ncols_all - number of characters/row allocated (size of tab)
           nrows_all - number of rows allocated
     PROCEDURES USED:
           SXPAR()
     HISTORY
           D. Lindler  July, 1987
           Converted to IDL V5.0   W. Landsman   September 1997
           Remove obsolete !ERR call   W. Landsman   May 2000

(See external/astron/fits_table/tbsize.pro)