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

Last modified: Wed Oct 15 03:17:40 2025.

# Directory Listing of Routines

# external/astron/fits_bintable

- FXADDPAR
- FXBADDCOL
- FXBCLOSE
- FXBCOLNUM()
- FXBCREATE
- FXBDIMEN()
  Returns the dimensions for a column in a FITS binary table.
- FXBFIND
- FXBFINDLUN()
- FXBFINISH
- FXBGROW
- FXBHEADER()
  Returns the header of an open FITS binary table.
- FXBHELP
- FXBHMAKE
- FXBINTABLE
- FXBISOPEN()
  Returns true if UNIT points to an open FITS binary table.
- FXBOPEN
- FXBPARSE
- FXBREAD
- FXBREADM
  Read multiple columns/rows from a disk FITS binary table file.
- FXBSTATE()
  Returns the state of a FITS binary table.
- FXBTDIM()
- FXBTFORM
- FXBWRITE
- FXBWRITM
  Write multiple columns/rows to a disk FITS binary table file.
- FXFINDEND
- FXHCLEAN
- FXHMAKE
- FXHMODIFY
- FXHREAD
- FXPAR()
  Obtain the value of a parameter in a FITS header.
- FXPARPOS()
- FXREAD
- FXWRITE

# Routine Descriptions

## FXADDPAR

[Next Routine] [List of Routines]

     NAME:
           FXADDPAR
     Purpose     :
           Add or modify a parameter in a FITS header array.
     Explanation :
           This version of FXADDPAR will write string values longer than 68
           characters using the FITS continuation convention described at
           http://fits.gsfc.nasa.gov/registry/continue_keyword.html
     Use         :
           FXADDPAR, HEADER, NAME, VALUE, COMMENT
     Inputs      :
           HEADER  = String array containing FITS header.  The maximum string
                     length must be equal to 80.  If not defined, then FXADDPAR
                     will create an empty FITS header array.

           NAME    = Name of parameter.  If NAME is already in the header the
                     value and possibly comment fields are modified. Otherwise a
                     new record is added to the header.  If NAME is equal to
                     either "COMMENT" or "HISTORY" then the value will be added to
                     the record without replacement.  In this case the comment
                     parameter is ignored.

           VALUE   = Value for parameter.  The value expression must be of the
                     correct type, e.g. integer, floating or string.
                     String values of 'T' or 'F' are considered logical
                     values unless the /NOLOGICAL keyword is set.  If the value is
                     a string and is "long" (more than 69 characters), then it
                     may be continued over more than one line using the OGIP
                     CONTINUE standard.

                     The special BOOLEAN datatype introduced in IDL 8.4 is also
                     recognized, and recorded as either 'T' or 'F' in the header.

     Opt. Inputs :
           COMMENT = String field.  The '/' is added by this routine.  Added
                     starting in position 31.  If not supplied, or set equal to ''
                     (the null string), then any previous comment field in the
                     header for that keyword is retained (when found).
     Outputs     :
           HEADER  = Updated header array.
     Opt. Outputs:
           None.
     Keywords    :
           BEFORE  = Keyword string name.  The parameter will be placed before the
                     location of this keyword.  For example, if BEFORE='HISTORY'
                     then the parameter will be placed before the first history
                     location.  This applies only when adding a new keyword;
                     keywords already in the header are kept in the same position.

           AFTER   = Same as BEFORE, but the parameter will be placed after the
                     location of this keyword.  This keyword takes precedence over
                     BEFORE.

           FORMAT  = Specifies FORTRAN-like format for parameter, e.g. "F7.3".  A
                     scalar string should be used.  For complex numbers the format
                     should be defined so that it can be applied separately to the
                     real and imaginary parts.  If not supplied, then the IDL
                     default formatting is used, except that double precision is
                     given a format of G19.12.

           /NOCONTINUE = By default, FXADDPAR will break strings longer than 68
                    characters into multiple lines using the continuation
                    convention.    If this keyword is set, then the line will
                    instead be truncated to 68 characters.    This was the default
                    behaviour of FXADDPAR prior to December 1999.

          /NOLOGICAL = If set, then the values 'T' and 'F' are not interpreted as
                    logical values, and are simply added without interpretation.

           /NULL   = If set, then keywords with values which are undefined, or
                     which have non-finite values (such as NaN, Not-a-Number) are
                     stored in the header without a value, such as

                           MYKEYWD =                      /My comment

           MISSING = A value which signals that data with this value should be
                     considered missing.  For example, the statement

                           FXADDPAR, HEADER, 'MYKEYWD', -999, MISSING=-999

                     would result in the valueless line described above for the
                     /NULL keyword.  Setting MISSING to a value implies /NULL.
                     Cannot be used with string or complex values.

           MULTIVALUE = Allow multivalue keywords.  This option was added to
                        support the DPj, DQi keywords introduced in the WCS
                        distortions paper.  With the /MULTIVALUE keyword, each new
                        instance of a keyword is added immediately after the
                        previous instance, for example:

                        FOR I=0,N_ELEMENTS(DQ1) DO FXADDPAR,HEADER,'DQ1',DQ1[I]

    	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, e.g.

    			ERRMSG = ''
    			FXADDPAR, ERRMSG=ERRMSG, ...
    			IF ERRMSG NE '' THEN ...

     Calls       :
           DETABIFY(), FXPAR(), FXPARPOS()
     Common      :
           None.
     Restrictions:
           Warning -- Parameters and names are not checked against valid FITS
           parameter names, values and types.

           The required FITS keywords SIMPLE (or XTENSION), BITPIX, NAXIS, NAXIS1,
           NAXIS2, etc., must be entered in order.  The actual values of these
           keywords are not checked for legality and consistency, however.

     Side effects:
           All HISTORY records are inserted in order at the end of the header.

           All COMMENT records are also inserted in order at the end of the
           header, but before the HISTORY records.  The BEFORE and AFTER keywords
           can override this.

           All records with no keyword (blank) are inserted in order at the end of
           the header, but before the COMMENT and HISTORY records.  The BEFORE and
           AFTER keywords can override this.

           All other records are inserted before any of the HISTORY, COMMENT, or
           "blank" records.  The BEFORE and AFTER keywords can override this.

           String values longer than 68 characters will be split into multiple
           lines using the OGIP CONTINUE convention, unless the /NOCONTINUE keyword
           is set.    For a description of the CONTINUE convention see
           http://fits.gsfc.nasa.gov/registry/continue_keyword.html
     Category    :
           Data Handling, I/O, FITS, Generic.
     Prev. Hist. :
           William Thompson, Jan 1992, from SXADDPAR by D. Lindler and J. Isensee.
           Differences include:

                   * LOCATION parameter replaced with keywords BEFORE and AFTER.
                   * Support for COMMENT and "blank" FITS keywords.
                   * Better support for standard FITS formatting of string and
                     complex values.
                   * Built-in knowledge of the proper position of required
                     keywords in FITS (although not necessarily SDAS/Geis) primary
                     headers, and in TABLE and BINTABLE extension headers.

           William Thompson, May 1992, fixed bug when extending length of header,
           and new record is COMMENT, HISTORY, or blank.
     Written     :
           William Thompson, GSFC, January 1992.
     Modified    :
           Version 1, William Thompson, GSFC, 12 April 1993.
                   Incorporated into CDS library.
           Version 2, William Thompson, GSFC, 5 September 1997
                   Fixed bug replacing strings that contain "/" character--it
                   interpreted the following characters as a comment.
           Version 3, Craig Markwardt, GSFC,  December 1997
                   Allow long values to extend over multiple lines
    	Version 4, D. Lindler, March 2000, modified to use capital E instead
    		of a lower case e for exponential format.
           Version 4.1 W. Landsman April 2000, make user-supplied format uppercase
           Version 4.2 W. Landsman July 2002, positioning of EXTEND keyword
           Version 5, 23-April-2007, William Thompson, GSFC
           Version 6, 02-Aug-2007, WTT, bug fix for OGIP long lines
           Version 6.1, 10-Feb-2009, W. Landsman, increase default format precision
           Version 6.2  30-Sep-2009, W. Landsman, added /NOLOGICAL keyword
           Version 7, 13-Aug-2015, William Thompson, allow null values
                   Add keywords /NULL, MISSING.  Catch non-finite values (e.g. NaN)
           Version 7.1, 22-Sep-2015, W. Thompson, No slash if null & no comment
           Version 8, 15-Sep-2016, W. Thompson, treat byte and boolean values
           Version 8.1, 28-Sep-2016, W. Thompson, use EXECUTE() for pre 8.4
           Version 8.2, 28-Sep-2016, W. Thompson, instead use COMPILE_OPT IDL2
           Version 9, 16-Mar-2017, W. Thompson, include comments in long strings
                   Use FXPARPOS, /LAST option.  Put space between slash and
                   comment
           Version 10, 21-Jun-2018, W. Thompson, for backward compatibility, save
                   non-finite values (e.g. NaN) as strings if /NULL not set
           Version 11, 03-Jun-2019, W. Thompson, added /MULTIVALUE
           Version 12, 13-Sep-2019, M Löfdahl, make /MULTIVALUE work for
                   CONTINUEd keywords.
           Version 13, 29-Oct-2019, W. Thompson, M Löfdahl, ensure floating point
                   uses E instead of e for exponentials.
     Version     :
           Version 13, 29-Oct-2019

(See external/astron/fits_bintable/fxaddpar.pro)

## FXBADDCOL

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

     NAME:
    	FXBADDCOL
     PURPOSE     :
    	Adds a column to a binary table extension.
     EXPLANATION :
    	Modify a basic FITS binary table extension (BINTABLE) header array to
    	define a column.
     USE         :
    	FXBADDCOL, INDEX, HEADER, ARRAY  [, TTYPE [, COMMENT ]]
     INPUTS      :
    	HEADER	= String array containing FITS extension header.
    	ARRAY	= IDL variable used to determine the data size and type
    		  associated with the column.  If the column is defined as
    		  containing variable length arrays, then ARRAY must be of the
    		  maximum size to be stored in the column.
     Opt. Inputs :
    	TTYPE	= Column label.
    	COMMENT = Comment for TTYPE
     Outputs     :
    	INDEX	= Index (1-999) of the created column.
    	HEADER	= The header is modified to reflect the added column.
     Opt. Outputs:
    	None.
     Keywords    :
    	VARIABLE= If set, then the column is defined to contain pointers to
    		  variable length arrays in the heap area.
    	DCOMPLEX= If set, and ARRAY is complex, with the first dimension being
    		  two (real and imaginary parts), then the column is defined as
    		  double-precision complex (type "M").     This keyword is
    		  only needed prior to IDL Version 4.0, when the double
    		  double complex datatype was unavailable in IDL
    	BIT	= If passed, and ARRAY is of type byte, then the column is
    		  defined as containing bit mask arrays (type "X"), with the
    		  value of BIT being equal to the number of mask bits.
    	LOGICAL	= If set, and array is of type byte, then the column is defined
    		  as containing logical arrays (type "L").
    	NO_TDIM	= If set, then the TDIMn keyword is not written out to the
    		  header.  No TDIMn keywords are written for columns containing
    		  variable length arrays.
    	TUNIT	= If passed, then corresponding keyword is added to header.
    	TSCAL	= Same.
    	TZERO	= Same.
    	TNULL	= Same.
    	TDISP	= Same.
    	TDMIN	= Same.
    	TDMAX	= Same.
    	TDESC	= Same.
    	TCUNI	= Same.
    	TROTA	= Same.
    	TRPIX	= Same.
    	TRVAL	= Same.
    	TDELT	= Same.
    	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 = ''
    			FXBADDCOL, ERRMSG=ERRMSG, ...
    			IF ERRMSG NE '' THEN ...

     Calls       :
    	FXADDPAR, FXPAR
     Common      :
    	None.
     Restrictions:
    	Warning: No checking is done of any of the parameters defining the
    	values of optional FITS keywords.

    	FXBHMAKE must first be called to initialize the header.

    	If ARRAY is of type character, then it must be of the maximum length
    	expected for this column.  If a character string array, then the
    	largest string in the array is used to determine the maximum length.

    	The DCOMPLEX keyword is ignored if ARRAY is not double-precision.
    	ARRAY must also have a first dimension of two representing the real and
    	imaginary parts.

    	The BIT and LOGICAL keywords are ignored if ARRAY is not of type byte.
    	BIT takes precedence over LOGICAL.

     Side effects:
    	If the data array is multidimensional, then a TDIM keyword is added to
    	the header, unless either NO_TDIM or VARIABLE is set.

    	No TDIMn keywords are written out for bit arrays (format 'X'), since
    	the dimensions would refer to bits, not bytes.

     Category    :
    	Data Handling, I/O, FITS, Generic.
     Prev. Hist. :
    	William Thompson, Jan 1992.
    	W. Thompson, Feb 1992, changed from function to procedure.
    	W. Thompson, Feb 1992, modified to support variable length arrays.
     Written     :
    	William Thompson, GSFC, January 1992.
     Modified    :
    	Version 1, William Thompson, GSFC, 12 April 1993.
    		Incorporated into CDS library.
    	Version 2, William Thompson, GSFC, 31 May 1994
    		Added ERRMSG keyword.
           Version 3, William Thompson, GSFC, 23 June 1994
                   Modified so that ERRMSG is not touched if not defined.
    	Version 4, William Thompson, GSFC, 30 December 1994
    		Added keyword TCUNI.
    	Version 5, Wayne Landsman, GSFC, 12 Aug 1997
    		Recognize double complex IDL datatype
           Version 6, Wayne Landsman, GSFC. C. Yamauchi (ISAS) 23 Feb 2006
                   Support 64bit integers
           Version 7, C. Markwardt, GSFC, Allow unsigned integers, which
                   have special TSCAL/TZERO values.  Feb 2009
           Version 8,  P.Broos (PSU), Wayne Landsman (GSFC) Mar 2010
                   Do *not* force TTYPE* keyword to uppercase
     Version     :
           Version 8, Mar 2010

(See external/astron/fits_bintable/fxbaddcol.pro)

## FXBCLOSE

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

     NAME:
    	FXBCLOSE
     Purpose     :
    	Close a FITS binary table extension opened for read.
     Explanation :
    	Closes a FITS binary table extension that had been opened for read by
    	FXBOPEN.
     Use         :
    	FXBCLOSE, UNIT
     Inputs      :
    	UNIT	= Logical unit number of the file.
     Opt. Inputs :
    	None.
     Outputs     :
    	None.
     Opt. Outputs:
    	None.
     Keywords    :
    	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 = ''
    			FXBCLOSE, ERRMSG=ERRMSG, ...
    			IF ERRMSG NE '' THEN ...

     Calls       :
    	None.
     Common      :
    	Uses common block FXBINTABLE--see "fxbintable.pro" for more
    	information.
     Restrictions:
    	The file must have been opened with FXBOPEN.
     Side effects:
    	None.
     Category    :
    	Data Handling, I/O, FITS, Generic.
     Prev. Hist. :
    	W. Thompson, Feb. 1992.
     Written     :
    	William Thompson, GSFC, February 1992.
     Modified    :
    	Version 1, William Thompson, GSFC, 12 April 1993.
    		Incorporated into CDS library.
    	Version 2, William Thompson, GSFC, 21 June 1994
    		Added ERRMSG keyword.
           Version 3, William Thompson, GSFC, 23 June 1994
                   Modified so that ERRMSG is not touched if not defined.
     Version     :
           Version 3, 23 June 1994
    	Converted to IDL V5.0   W. Landsman   September 1997

(See external/astron/fits_bintable/fxbclose.pro)

## FXBCOLNUM()

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

     NAME:
    	FXBCOLNUM()
     Purpose     :
    	Returns a binary table column number.
     Explanation :
    	Given a column specified either by number or name, this routine will
    	return the appropriate column number.
     Use         :
    	Result = FXBCOLNUM( UNIT, COL )
     Inputs      :
    	UNIT	= Logical unit number corresponding to the file containing the
    		  binary table.
    	COL	= Column in the binary table, given either as a character
    		  string containing a column label (TTYPE), or as a numerical
    		  column index starting from column one.
     Opt. Inputs :
    	None.
     Outputs     :
    	The result of the function is the number of the column specified, or
    	zero if no column is found (when passed by name).
     Opt. Outputs:
    	None.
     Keywords    :
    	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 = ''
    			Result = FXBCOLNUM( ERRMSG=ERRMSG, ... )
    			IF ERRMSG NE '' THEN ...

     Calls       :
    	None.
     Common      :
    	Uses common block FXBINTABLE--see "fxbintable.pro" for more
    	information.
     Restrictions:
    	The binary table file must have been opened with FXBOPEN.

    	If COL is passed as a number, rather than as a name, then it must be
    	consistent with the number of columns in the table.

     Side effects:
    	None.
     Category    :
    	Data Handling, I/O, FITS, Generic.
     Prev. Hist. :
    	None.
     Written     :
    	William Thompson, GSFC, 2 July 1993.
     Modified    :
    	Version 1, William Thompson, GSFC, 2 July 1993.
    	Version 2, William Thompson, GSFC, 29 October 1993.
    		Added error message for not finding column by name.
    	Version 3, William Thompson, GSFC, 21 June 1994
    		Added ERRMSG keyword.
           Version 4, William Thompson, GSFC, 23 June 1994
                   Modified so that ERRMSG is not touched if not defined.
     Version     :
           Version 4, 23 June 1994
    	Converted to IDL V5.0   W. Landsman   September 1997

(See external/astron/fits_bintable/fxbcolnum.pro)

## FXBCREATE

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

     NAME:
    	FXBCREATE
     Purpose     :
    	Open a new binary table at the end of a FITS file.
     Explanation :
    	Write a binary table extension header to the end of a disk FITS file,
    	and leave it open to receive the data.

    	The FITS file is opened, and the pointer is positioned just after the
    	last 2880 byte record.  Then the binary header is appended.  Calls to
    	FXBWRITE will append the binary data to this file, and then FXBFINISH
    	will close the file.

     Use         :
    	FXBCREATE, UNIT, FILENAME, HEADER
     Inputs      :
    	FILENAME = Name of FITS file to be opened.
    	HEADER	 = String array containing the FITS binary table extension
    		   header.
     Opt. Inputs :
    	None.
     Outputs     :
    	UNIT	 = Logical unit number of the opened file.
           EXTENSION= Extension number of newly created extension.
     Opt. Outputs:
    	None.
     Keywords    :
    	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 = ''
    			FXBCREATE, ERRMSG=ERRMSG, ...
    			IF ERRMSG NE '' THEN ...

     Calls       :
    	FXADDPAR, FXBFINDLUN, FXBPARSE, FXFINDEND
     Common      :
    	Uses common block FXBINTABLE--see "fxbintable.pro" for more
    	information.
     Restrictions:
    	The primary FITS data unit must already be written to a file.  The
    	binary table extension header must already be defined (FXBHMAKE), and
    	must match the data that will be written to the file.
     Side effects:
    	None.
     Category    :
    	Data Handling, I/O, FITS, Generic.
     Prev. Hist. :
    	W. Thompson, Jan 1992, based on WRITEFITS by J. Woffard and W. Landsman.
    	W. Thompson, Feb 1992, changed from function to procedure.
    	W. Thompson, Feb 1992, removed all references to temporary files.
     Written     :
    	William Thompson, GSFC, January 1992.
     Modified    :
    	Version 1, William Thompson, GSFC, 12 April 1993.
    		Incorporated into CDS library.
    	Version 2, William Thompson, GSFC, 21 July 1993.
    		Fixed bug with variable length arrays.
    	Version 3, William Thompson, GSFC, 21 June 1994
    		Added ERRMSG keyword.
    	Version 4, William Thompson, GSFC, 23 June 1994
                   Modified so that ERRMSG is not touched if not defined.
    	Version 5, Antony Bird, Southampton, 25 June 1997
    		Modified to allow very long tables
     Version     :
    	Version 5, 25 June 1997
    	Converted to IDL V5.0   W. Landsman   September 1997
           Added EXTENSION parameter, C. Markwardt 1999 Jul 15
           More efficient zeroing of file, C. Markwardt, 26 Feb 2001
           Recompute header size if updating THEAP keyword B. Roukema April 2010

(See external/astron/fits_bintable/fxbcreate.pro)

## FXBDIMEN()

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

     NAME:
         FXBDIMEN()

     PURPOSE:
          Returns the dimensions for a column in a FITS binary table.

     Explanation : This procedure returns the dimensions associated with a column
                   in a binary table opened for read with the command FXBOPEN.

     Use         : Result = FXBDIMEN(UNIT,COL)

     Inputs      : UNIT    = Logical unit number returned by FXBOPEN routine.
                             Must be a scalar integer.

                   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.

     Opt. Inputs : None.

     Outputs     : The result of the function is an array containing the
                   dimensions for the specified column in the FITS binary table
                   that UNIT points to.

     Opt. Outputs: None.

     Keywords :    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 = ''
                                   Result = FXBDIMEN( ERRMSG=ERRMSG, ... )
                                   IF ERRMSG NE '' THEN ...

     Calls       : FXBCOLNUM, FXBFINDLUN

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

     Restrictions: None.

     Side effects: The dimensions will be returned whether or not the table is
                   still open or not.

                   If UNIT does not point to a binary table, then 0 is returned.

                   If UNIT is an undefined variable, then 0 is returned.

     Category    : Data Handling, I/O, FITS, Generic.

     Prev. Hist. : None.

     Written     : William Thompson, GSFC, 4 March 1994.

     Modified    : Version 1, William Thompson, GSFC, 4 March 1994.
                   Version 2, William Thompson, GSFC, 21 June 1994
                           Added ERRMSG keyword.
                   Version 3, William Thompson, GSFC, 23 June 1994
                           Modified so that ERRMSG is not touched if not defined.

     Version     : Version 3, 23 June 1994
           Converted to IDL V5.0   W. Landsman   September 1997

(See external/astron/fits_bintable/fxbdimen.pro)

## FXBFIND

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

     NAME:
    	FXBFIND
     Purpose     :
    	Find column keywords in a FITS binary table header.
     Explanation :
    	Finds the value of a column keyword for all the columns in the binary
    	table for which it is set.  For example,

    		FXBFIND, UNIT, 'TTYPE', COLUMNS, VALUES, N_FOUND

    	Would find all instances of the keywords TTYPE1, TTYPE2, etc.  The
    	array COLUMNS would contain the column numbers for which a TTYPEn
    	keyword was found, and VALUES would contain the values.  N_FOUND would
    	contain the total number of instances found.

     Use         :
    	FXBFIND, [UNIT or HEADER], KEYWORD, COLUMNS, VALUES, N_FOUND
    		[, DEFAULT ]
     Inputs      :
    	Either UNIT or HEADER must be passed.

    	UNIT	= Logical unit number of file opened by FXBOPEN.
    	HEADER	= FITS binary table header.
    	KEYWORD	= Prefix to a series of FITS binary table column keywords.  The
    		  keywords to be searched for are formed by combining this
    		  prefix with the numbers 1 through the value of TFIELDS in the
    		  header.
     Opt. Inputs :
    	DEFAULT	= Default value to use for any column keywords that aren't
    		  found.  If passed, then COLUMNS and VALUES will contain
    		  entries for every column.  Otherwise, COLUMNS and VALUES only
    		  contain entries for columns where values were found.
     Outputs     :
    	COLUMNS	= Array containing the column numbers for which values of the
    		  requested keyword series were found.
    	VALUES	= Array containing the found values.
    	N_FOUND	= Number of values found.  The value of this parameter is
    		  unaffected by whether or not DEFAULT is passed.
     Opt. Outputs:
    	None.
     Output Keywords    :
          COMMENTS = Comments associated with each keyword, if any
     Calls       :
    	FXBFINDLUN, FXPAR
     Common      :
    	Uses common block FXBINTABLE--see "fxbintable.pro" for more
    	information.
     Restrictions:
    	If UNIT is passed, then the file must have been opened with FXBOPEN.
    	If HEADER is passed, then it must be a legal FITS binary table header.

    	The type of DEFAULT must be consistent with the values of the requested
    	keywords, i.e. both most be either of string or numerical type.

    	The KEYWORD prefix must not have more than five characters to leave
    	room for the three digits allowed for the column numbers.

     Side effects:
    	None.
     Category    :
    	Data Handling, I/O, FITS, Generic.
     Prev. Hist. :
    	William Thompson, Feb. 1992.
     Written     :
    	William Thompson, GSFC, February 1992.
     Modified    :
    	Version 1, William Thompson, GSFC, 12 April 1993.
    		Incorporated into CDS library.
           Vectorized implementation improves performance, CM 18 Nov 1999
           Added COMMENTS keyword CM Nov 2003
           Remove use of obsolete !ERR system variable W. Landsman April 2010
           Fix error introduced April 2010  W. Landsman
     Version     :
    	Version 3, April 2010.

(See external/astron/fits_bintable/fxbfind.pro)

## FXBFINDLUN()

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

     NAME:
    	FXBFINDLUN()
     Purpose     :
    	Find logical unit number UNIT in FXBINTABLE common block.
     Explanation :
    	Finds the proper index to use for getting information about the logical
    	unit number UNIT in the arrays stored in the FXBINTABLE common block.
    	Called from FXBCREATE and FXBOPEN.
     Use         :
    	Result = FXBFINDLUN( UNIT )
     Inputs      :
    	UNIT	= Logical unit number.
     Opt. Inputs :
    	None.
     Outputs     :
    	The result of the function is an index into the FXBINTABLE common
    	block.
     Opt. Outputs:
    	None.
     Keywords    :
    	None.
     Calls       :
    	None.
     Common      :
    	Uses common block FXBINTABLE--see "fxbintable.pro" for more
    	information.
     Restrictions:
    	None.
     Side effects:
    	If UNIT is not found in the common block, then it is added to the
    	common block.
     Category    :
    	Data Handling, I/O, FITS, Generic.
     Prev. Hist. :
    	William Thompson, Feb. 1992.
     Written     :
    	William Thompson, GSFC, February 1992.
     Modified    :
    	Version 1, William Thompson, GSFC, 12 April 1993.
    		Incorporated into CDS library.
    	Version 2, William Thompson, GSFC, 21 July 1993.
    		Added DHEAP variable to fix bug with variable length arrays.
    	Version 3, Michael Schubnell, University of Michigan, 22 May 1996
    		Change N_DIMS from short to long integer.
     Version     :
    	Version 3, 22 May 1996
       Make NAXIS1, NAXIS2, HEAP, DHEAP, BYTOFF 64-bit integers to deal with large files,
             E. Hivon Mar 2008
       Also make NHEADER a 64 bit integer   W. Landsman  May 2016

(See external/astron/fits_bintable/fxbfindlun.pro)

## FXBFINISH

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

     NAME:
    	FXBFINISH
     Purpose     :
    	Close a FITS binary table extension file opened for write.
     Explanation :
    	Closes a FITS binary table extension file that had been opened for
    	write by FXBCREATE.
     Use         :
    	FXBFINISH, UNIT
     Inputs      :
    	UNIT	= Logical unit number of the file.
     Opt. Inputs :
    	None.
     Outputs     :
    	None.
     Opt. Outputs:
    	None.
     Keywords    :
    	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 = ''
    			FXBFINISH, ERRMSG=ERRMSG, ...
    			IF ERRMSG NE '' THEN ...

     Calls       :
    	None.
     Common      :
    	Uses common block FXBINTABLE--see "fxbintable.pro" for more
    	information.
     Restrictions:
    	The file must have been opened with FXBCREATE, and written with
    	FXBWRITE.
     Side effects:
    	Any bytes needed to pad the file out to an integral multiple of 2880
    	bytes are written out to the file.  Then, the file is closed.
     Category    :
    	Data Handling, I/O, FITS, Generic.
     Prev. Hist. :
    	W. Thompson, Jan 1992.
    	W. Thompson, Feb 1992, modified to support variable length arrays.
    	W. Thompson, Feb 1992, removed all references to temporary files.
     Written     :
    	William Thompson, GSFC, January 1992.
     Modified    :
    	Version 1, William Thompson, GSFC, 12 April 1993.
    		Incorporated into CDS library.
    	Version 2, William Thompson, GSFC, 21 July 1993.
    		Fixed bug with variable length arrays.
    	Version 3, William Thompson, GSFC, 31 May 1994
    		Added ERRMSG keyword.
           Version 4, William Thompson, GSFC, 23 June 1994
                   Modified so that ERRMSG is not touched if not defined.
     Version     :
           Version 4, 23 June 1994
    	Converted to IDL V5.0   W. Landsman   September 1997

(See external/astron/fits_bintable/fxbfinish.pro)

## FXBGROW

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

     NAME:
            FXBGROW
     PURPOSE     :
           Increase the number of rows in a binary table.
     EXPLANATION :
           Call FXBGROW to increase the size of an already-existing FITS
           binary table.  The number of rows increases to NROWS; however
           the table cannot shrink by this operation.  This procedure is
           useful when a table with an unknown number of rows must be
           created.  The caller would then call FXBCREATE to construct a
           table of some base size, and follow with calls to FXBGROW to
           lengthen the table as needed.  The extension being enlarged
           need not be the last extension in the file.  If subsequent
           extensions exist in the file, they will be shifted properly.

     CALLING SEQUENCE :
           FXBGROW, UNIT, HEADER, NROWS[, ERRMSG= , NOZERO= , BUFFERSIZE= ]

     INPUT PARAMETERS :
           UNIT     = Logical unit number of an already-opened file.
           HEADER   = String array containing the FITS binary table extension
                      header.  The header is modified in place.
           NROWS    = New number of rows, always more than the previous
                      number.

     OPTIONAL INPUT KEYWORDS:
           NOZERO   = when set, FXBGROW will not zero-pad the new data if
                      it doesn't have to.
           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 = ''
                           FXBGROW, ERRMSG=ERRMSG, ...
                           IF ERRMSG NE '' THEN ...
           BUFFERSIZE = Size in bytes for intermediate data transfers
                        (default 32768)

     Calls       :
           FXADDPAR, FXHREAD, BLKSHIFT
     Common      :
           Uses common block FXBINTABLE--see "fxbintable.pro" for more
           information.
     Restrictions:
           The file must be open with write permission.

           The binary table extension in question must already by written
           to the file (using FXBCREATE).

           A table can never shrink via this operation.

     SIDE EFFECTS:
           The FITS file will grow in size, and heap areas are
           preserved by moving them to the end of the file.

           The header is modified to reflect the new number of rows.
     CATEGORY    :
           Data Handling, I/O, FITS, Generic.
           Initially written, C. Markwardt, GSFC, Nov 1998
           Added ability to enlarge arbitrary extensions and tables with
             variable sized rows, not just the last extension in a file,
             CM, April 2000
           Fix bug in the zeroing of the output file, C. Markwardt, April 2005

(See external/astron/fits_bintable/fxbgrow.pro)

## FXBHEADER()

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

     NAME:
           FXBHEADER()

     PURPOSE:
           Returns the header of an open FITS binary table.

     EXPLANATION:
          This procedure returns the FITS extension header of a FITS
             binary table opened for read with the command FXBOPEN.

     Use         : Result = FXBHEADER(UNIT)

     Inputs      : UNIT    = Logical unit number returned by FXBOPEN routine.
                             Must be a scalar integer.

     Opt. Inputs : None.

     Outputs     : The result of the function is a string array containing the
                   header for the FITS binary table that UNIT points to.

     Opt. Outputs: None.

     Keywords    : None.

     Calls       : FXBFINDLUN

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

     Restrictions: None.

     Side effects: The string array returned always has as many elements as the
                   largest header read by FXBOPEN.  Any extra elements beyond the
                   true header are blank or null strings.

                   The header will be returned whether or not the table is still
                   open or not.

                   If UNIT does not point to a binary table, then a string array
                   of nulls is returned.

                   If UNIT is an undefined variable, then the null string is
                   returned.

     Category    : Data Handling, I/O, FITS, Generic.

     Prev. Hist. : None.

     Written     : William Thompson, GSFC, 1 July 1993.

     Modified    : Version 1, William Thompson, GSFC, 1 July 1993.

     Version     : Version 1, 1 July 1993.
           Converted to IDL V5.0   W. Landsman   September 1997

(See external/astron/fits_bintable/fxbheader.pro)

## FXBHELP

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

     NAME:
    	FXBHELP
     Purpose     :
    	Prints short description of columns in a FITS binary table.
     Explanation :
    	Prints a short description of the columns in a FITS binary table to the
    	terminal screen.
     Use         :
    	FXBHELP, UNIT
     Inputs      :
    	UNIT	= Logical unit number of file opened by FXBOPEN.
     Opt. Inputs :
    	None.
     Outputs     :
    	None.
     Opt. Outputs:
    	None.
     Keywords    :
    	None.
     Calls       :
    	FXBFIND, FXBFINDLUN, FXPAR
     Common      :
    	Uses common block FXBINTABLE--see "fxbintable.pro" for more
    	information.
     Restrictions:
    	The file must have been opened with FXBOPEN.
     Side effects:
    	Certain fields may be truncated in the display.
     Category    :
    	Data Handling, I/O, FITS, Generic.
     Prev. Hist. :
    	William Thompson, Feb. 1992, from TBHELP by W. Landsman.
     Written     :
    	William Thompson, GSFC, February 1992.
     Modified    :
    	Version 1, William Thompson, GSFC, 12 April 1993.
    		Incorporated into CDS library.
    	Version 2, William Thompson, GSFC, 12 May 1993.
    		Modified to not write to a logical unit number assigned to the
    		terminal.  This makes it compatible with IDL for Windows.
           Version 3, Wayne Landsman GSFC April 2010
                    Remove use of obsolete !ERR system variable
     Version     :
    	Version 3, April 2010.

(See external/astron/fits_bintable/fxbhelp.pro)

## FXBHMAKE

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

     NAME:
    	FXBHMAKE
     Purpose     :
    	Create basic FITS binary table extension (BINTABLE) header.
     Explanation :
    	Creates a basic header array with all the required keywords, but with
    	none of the table columns defined.  This defines a basic structure
    	which can then be added to or modified by other routines.
     Use         :
    	FXBHMAKE, HEADER, NROWS  [, EXTNAME  [, COMMENT ]]
     Inputs      :
    	NROWS	= Number of rows in the binary table.
     Opt. Inputs :
    	EXTNAME	= If passed, then the EXTNAME record is added with this value.
    	COMMENT = Comment to go along with EXTNAME.
     Outputs     :
    	HEADER = String array containing FITS extension header.
     Opt. Outputs:
    	None.
     Keywords    :
    	INITIALIZE = If set, then the header is completely initialized, and any
    		     previous entries are lost.
    	DATE	   = If set, then the DATE keyword is added to the header.
    	EXTVER	   = Extension version number (integer).
    	EXTLEVEL   = Extension level number (integer).
    	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 = ''
    			FXBHMAKE, ERRMSG=ERRMSG, ...
    			IF ERRMSG NE '' THEN ...

     Calls       :
    	GET_DATE, FXADDPAR, FXHCLEAN
     Common      :
    	None.
     Restrictions:
    	Warning:  No checking is done of any of the parameters.
     Side effects:
    	None.
     Category    :
    	Data Handling, I/O, FITS, Generic.
     Prev. Hist. :
    	William Thompson, Jan 1992.
    	William Thompson, Sep 1992, added EXTVER and EXTLEVEL keywords.
     Written     :
    	William Thompson, GSFC, January 1992.
     Modified    :
    	Version 1, William Thompson, GSFC, 12 April 1993.
    		Incorporated into CDS library.
    	Version 2, William Thompson, GSFC, 21 June 1994
    		Added ERRMSG keyword.
           Version 3, William Thompson, GSFC, 23 June 1994
                   Modified so that ERRMSG is not touched if not defined.
     Version     :
           Version 3, 23 June 1994
    	Converted to IDL V5.0   W. Landsman   September 1997

(See external/astron/fits_bintable/fxbhmake.pro)

## FXBINTABLE

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

     NAME:
    	FXBINTABLE
     Purpose     :
    	Common block FXBINTABLE used by "FXB" routines.
     Explanation :
    	This is not an IDL routine as such, but contains the definition of the
    	common block FXBINTABLE for inclusion into other routines.  By defining
    	the common block in one place, the problem of conflicting definitions
    	is avoided.

    	This file is included into routines that need this common block with
    	the single line (left justified)

    				  @fxbintable

    	FXBINTABLE contains the following arrays:

    		LUN	= An array of logical unit numbers of currently (or
    			  previously) opened binary table files.
    		STATE	= Array containing the state of the FITS files
    			  associated with the logical unit numbers, where
    			  0=closed, 1=open for read, and 2=open for write.
    		HEAD	= FITS binary table headers.
    		MHEADER	= Array containing the positions of the first data byte
    			  of the header for each file referenced by array LUN.
    		NHEADER	= Array containing the positions of the first data byte
    			  after the header for each file referenced by array
    			  LUN.
    		NAXIS1	= Values of NAXIS1 from the binary table headers.
    		NAXIS2	= Values of NAXIS2 from the binary table headers.
    		TFIELDS	= Values of TFIELDS from the binary table headers.
    		HEAP	= The start of the first byte of the heap area
    			  for variable length arrays.
    		DHEAP	= The start of the first byte of the next variable
    			  length array, if writing.
    		BYTOFF	= Byte offset from the beginning of the row for each
    			  column in the binary table headers.
    		TTYPE	= Values of TTYPE for each column in the binary table
    			  headers.
    		FORMAT	= Character code formats of the various columns.
    		IDLTYPE	= IDL type code for each column in the binary table
    			  headers.
    		N_ELEM	= Number of elements for each column in the binary
    			  table headers.
    		TSCAL	= Scale factors for the individual columns.
    		TZERO	= Zero offsets for the individual columns.
    		MAXVAL	= For variable length arrays, contains the maximum
    			  number of elements for each column in the binary
    			  table headers.
    		N_DIMS	= Number of dimensions, and array of dimensions for
    			  each column of type string in the binary table
    			  headers.
     Category    :
    	Data Handling, I/O, FITS, Generic.
     Prev. Hist. :
    	William Thompson, Feb 1992.
     Written     :
    	William Thompson, GSFC, February 1992.
     Modified    :
    	Version 1, William Thompson, GSFC, 12 April 1993.
    		Incorporated into CDS library.
    	Version 2, William Thompson, GSFC, 21 July 1993.
    		Added DHEAP variable to fix bug with variable length arrays.
     Version     :
    	Version 2, 21 July 1993.

(See external/astron/fits_bintable/fxbintable.pro)

## FXBISOPEN()

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

     NAME:
           FXBISOPEN()

     PURPOSE:
           Returns true if UNIT points to an open FITS binary table.

     Explanation : This procedure checks to see if the logical unit number given
                   by the variable UNIT corresponds to a FITS binary table opened
                   for read with the command FXBOPEN, and which has not yet been
                   closed with FXBCLOSE.

     Use         : Result = FXBISOPEN(UNIT)

                   If FXBISOPEN(UNIT) THEN ...

     Inputs      : UNIT    = Logical unit number returned by FXBOPEN routine.
                             Must be a scalar integer.

     Opt. Inputs : None.

     Outputs     : The result of the function is either True (1) or False (0),
                   depending on whether UNIT points to an open binary table or
                   not.

     Opt. Outputs: None.

     Keywords    : None.

     Calls       : FXBFINDLUN

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

     Restrictions: None.

     Side effects: If UNIT is an undefined variable, then False (0) is returned.

                   If UNIT points to a FITS binary table file that is opened for
                   write, then False (0) is returned.

     Category    : Data Handling, I/O, FITS, Generic.

     Prev. Hist. : None.

     Written     : William Thompson, GSFC, 1 July 1993.

     Modified    : Version 1, William Thompson, GSFC, 1 July 1993.

     Version     : Version 1, 1 July 1993.
           Converted to IDL V5.0   W. Landsman   September 1997

(See external/astron/fits_bintable/fxbisopen.pro)

## FXBOPEN

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

     NAME:
    	FXBOPEN
     Purpose     :
    	Open binary table extension in a disk FITS file for reading or updating
     Explanation :
    	Opens a binary table extension in a disk FITS file for reading.  The
    	columns are then read using FXBREAD, and the file is closed when done
    	with FXBCLOSE.
     Use         :
    	FXBOPEN, UNIT, FILENAME, EXTENSION  [, HEADER ]
     Inputs      :
           FILENAME  = Name of FITS file to be opened.  Optional
                       extension *number* may be specified, in either of
                       the following formats (using the FTOOLS
                       convention): FILENAME[EXT] or FILENAME+EXT, where
                       EXT is 1 or higher.  Such an extension
                       specification takes priority over EXTENSION.

    	EXTENSION = Either the number of the FITS extension, starting with the
    		    first extension after the primary data unit being one; or a
    		    character string containing the value of EXTNAME to search
    		    for.
     Opt. Inputs :
    	None.
     Outputs     :
    	UNIT	  = Logical unit number of the opened file.
     Opt. Outputs:
    	HEADER	  = String array containing the FITS binary table extension
    		    header.
     Keywords    :
    	NO_TDIM	  = If set, then any TDIMn keywords found in the header are
    		    ignored.

           ACCESS    = A scalar string describing access privileges as
                       one of READ ('R') or UPDATE ('RW').
                       DEFAULT: 'R'

           REOPEN    = If set, UNIT must be an already-opened file unit.
                       FXBOPEN will treat the file as a FITS file.

    	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 = ''
    			FXBOPEN, ERRMSG=ERRMSG, ...
    			IF ERRMSG NE '' THEN ...

     Calls       :
    	FXBFINDLUN, FXBPARSE, FXHREAD, FXPAR
     Common      :
    	Uses common block FXBINTABLE--see "fxbintable.pro" for more
    	information.
     Restrictions:
    	The file must be a valid FITS file.
     Side effects:
    	None.
     Category    :
    	Data Handling, I/O, FITS, Generic.
     Prev. Hist. :
    	W. Thompson, Feb 1992, based on READFITS by J. Woffard and W. Landsman.
    	W. Thompson, Feb 1992, changed from function to procedure.
    	W. Thompson, June 1992, fixed up error handling.
     Written     :
    	William Thompson, GSFC, February 1992.
     Modified    :
    	Version 1, William Thompson, GSFC, 12 April 1993.
    		Incorporated into CDS library.
    	Version 2, William Thompson, GSFC, 27 May 1994
    		Added ERRMSG keyword.
    	Version 3, William Thompson, GSFC, 21 June 1994
    		Extended ERRMSG to call to FXBPARSE
           Version 4, William Thompson, GSFC, 23 June 1994
                   Modified so that ERRMSG is not touched if not defined.
           Version 4, 23 June 1994

     Added ACCESS, REOPEN keywords, and FXFILTER package, CM 1999 Feb 03
     Added FILENAME[EXT] and FILENAME+EXT extension parsing, CM 1999 Jun 28
     Some general tidying, CM 1999 Nov 18
           Allow for possible 64bit integer number of bytes W. Landsman Nov 2007
           Make Ndata a 64bit integer to deal with larger files, E. Hivon, Mar 2008

(See external/astron/fits_bintable/fxbopen.pro)

## FXBPARSE

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

     NAME:
    	FXBPARSE
     Purpose     :
    	Parse the binary table extension header.
     Explanation :
    	Parses the binary table extension header, and store the information
    	about the format of the binary table in the FXBINTABLE common
    	block--called from FXBCREATE and FXBOPEN.
     Use         :
    	FXBPARSE, ILUN, UNIT, HEADER
     Inputs      :
    	ILUN	= Index into the arrays in the FXBINTABLE common block.
    	HEADER	= FITS binary table extension header.
     Opt. Inputs :
    	None.
     Outputs     :
    	None.
     Opt. Outputs:
    	None.
     Keywords    :
    	NO_TDIM	  = If set, then any TDIMn keywords found in the header are
    		    ignored.
    	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 = ''
    			FXBPARSE, ERRMSG=ERRMSG, ...
    			IF ERRMSG NE '' THEN ...

     Calls       :
    	FXBFIND, FXBTDIM, FXBTFORM, FXPAR
     Common      :
    	Uses common block FXBINTABLE--see "fxbintable.pro" for more
    	information.
     Restrictions:
    	None.
     Side effects:
    	Any TDIMn keywords found for bit arrays (format 'X') are ignored, since
    	the dimensions would refer to bits, not bytes.
     Category    :
    	Data Handling, I/O, FITS, Generic.
     Prev. Hist. :
    	William Thompson, Feb. 1992.
    	William Thompson, Jan. 1993, modified for renamed FXBTFORM and FXBTDIM.
     Written     :
    	William Thompson, GSFC, February 1992.
     Modified    :
    	Version 1, William Thompson, GSFC, 12 April 1993.
    		Incorporated into CDS library.
    	Version 2, William Thompson, GSFC, 21 June 1994
    		Added ERRMSG keyword.
           Version 3, William Thompson, GSFC, 23 June 1994
                   Modified so that ERRMSG is not touched if not defined.
    	Version 4, Michael Schubnell, University of Michigan, 22 May 1996
    		Change N_DIMS from short to long integer.
    	Version 5, W. Landsman, GSFC, 12 Aug 1997
    		Use double complex datatype, if needed
    	Version 6, W. Landsman GSFC 30 Aug 1997
           Optimized FXPAR; call FXBFIND for speed, CM 1999 Nov 18
           Modify DHEAP(ILUN) when opening table now, CM 2000 Feb 22
           Default the TZERO/TSCAL tables to double instead of single
             precision floating point, CM 2003 Nov 23
           Make NAXIS1 and NAXIS2 64-bit integers to deal with large files,
             E. Hivon Mar 2008
           Remove use of Obsolete !ERR system variable
      Version
           Version 8   April 2010

(See external/astron/fits_bintable/fxbparse.pro)

## FXBREAD

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

     NAME:
    	FXBREAD
     Purpose     :
    	Read a data array from a disk FITS binary table file.
     Explanation :
    	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.
     Use         :
    	FXBREAD, UNIT, DATA, COL  [, ROW ]
     Inputs      :
    	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.
     Opt. Inputs :
    	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.

     Outputs     :
    	DATA	= IDL data array to be read from the file.
     Opt. Outputs:
    	None.
     Keywords    :
    	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 ...

     Calls       :
    	FXPAR, WHERE_NEGZERO, WHERENAN
     Common      :
    	Uses common block FXBINTABLE--see "fxbintable.pro" for more
    	information.
     Restrictions:
    	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.

     Side effects:
    	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.

     Category    :
    	Data Handling, I/O, FITS, Generic.
     Prev. Hist. :
    	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.
     Written     :
    	William Thompson, GSFC, January 1992.
     Modified    :
    	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 15, W. Landsman GSFC 10 Dec 2009
                    Fix Dimension keyword, remove  IEEE_TO_HOST
           Version 16, William Thompson, 18-May-2016, change POINTER to ULONG
           Version 17, William Thompson/Terje Fredvik, 30-Aug-2018, preserve
                   original dimensionality
           Version 18, William Thompson, 31-Aug-2018, correction to v17
     Version     :
           Version 18, 31-Aug-2018

(See external/astron/fits_bintable/fxbread.pro)

## FXBREADM

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

     NAME:
           FXBREADM
     PURPOSE:
           Read multiple columns/rows from a disk FITS binary table file.
     EXPLANATION :
           A call to FXBREADM will read data from multiple rows and
           multiple columns in a single procedure call.  Up to forty-nine
           columns may be read in a single pass; the number of rows is
           limited essentially by available memory.  The file should have
           already been opened with FXBOPEN.  FXBREADM optimizes reading
           multiple columns by first reading a large chunk of data from
           the FITS file directly, and then slicing the data into columns
           within memory.  FXBREADM can read variable-length arrays (see
           below).

           The number of columns is limited to 49 if data are passed by
           positional argument.  However, this limitation can be overcome
           by having FXBREADM return the data in an array of pointers.
           The user should set the PASS_METHOD keyword to 'POINTER', and an
           array of pointers to the data will be returned in the POINTERS keyword.
           The  user is responsible for freeing the pointers; however,
           FXBREADM will reuse any pointers  passed into the procedure, and
           hence any pointed-to data will be destroyed.

           FXBREADM can also read variable-length columns from FITS
           binary tables.  Since such data is not of a fixed size, it is
           returned as a structure.  The structure has the following
           elements:

                  VARICOL:    ;; Flag: variable length column (= 1)
                  N_ELEMENTS: ;; Total number of elements returned
                  TYPE:       ;; IDL data type code (integer)
                  N_ROWS:     ;; Number of rows read from table (integer)
                  INDICES:    ;; Indices of each row's data (integer array)
                  DATA:       ;; Raw data elements (variable type array)

           In order to gain access to the Ith row's data, one should
           examine DATA(INDICES(I):INDICES(I+1)-1), which is similar in
           construct to the REVERSE_INDICES keyword of the HISTOGRAM
           function.

     CALLING SEQUENCE:
           FXBREADM, UNIT, COL, DATA1, [ DATA2, ... DATA48, ROW=, BUFFERSIZE = ]
               /NOIEEE, /NOSCALE, /VIRTUAL, NANVALUE=, PASS_METHOD = POINTERS=,
               ERRMSG = , WARNMSG = , STATUS = , /DEFAULT_FLOAT]

     INPUT PARAMETERS :
           UNIT    = Logical unit number corresponding to the file containing the
                     binary table.
           COL     = An array of columns in the binary table to read data
                     from, either as character strings containing column
                     labels (TTYPE), or as numerical column indices
                     starting from column one.
     Outputs     :
           DATA1, DATA2...DATA48 = A named variable to accept the data values, one
                     for each column.  The columns are stored in order of the
                     list in COL.  If the read operation fails for a
                     particular column, then the corresponding output Dn
                     variable is not altered.  See the STATUS keyword.
                     Ignored if PASS_METHOD is 'POINTER'.

     OPTIONAL INPUT KEYWORDS:
           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.
           /DEFAULT_FLOAT = If set, then scaling with TSCAL/TZERO is done with
                     floating point rather than double precision.
           /NOIEEE = If set, then then IEEE floating point data will not
                    be converted to the host floating point format (and
                    this by definition implies NOSCALE).  The user is
                    responsible for their own floating point conversion.
           /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.
           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 = FXBREADM ignores this keyword.  It is here for
    	          compatibility only.
           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.
           PASS_METHOD = A scalar string indicating method of passing
                     data from FXBREADM.  Either 'ARGUMENT' (indicating
                     pass by positional argument), or 'POINTER' (indicating
                     passing an array of pointers by the POINTERS
                     keyword).
                     Default: 'ARGUMENT'
           POINTERS = If PASS_METHOD is 'POINTER' then an array of IDL
                     pointers is returned in this keyword, one for each
                     requested column.    Any pointers passed into FXBREADM will
                     have their pointed-to data destroyed.  Ultimately the
                     user is responsible for deallocating pointers.
           BUFFERSIZE = Raw data are transferred from the file in chunks
                     to conserve memory.  This is the size in bytes of
                     each chunk.  If a value of zero is given, then all
                     of the data are transferred in one pass.  Default is
                     32768 (32 kB).
     OPTIONAL OUTPUT KEYWORDS:
           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 ...
           WARNMSG = Messages which are considered to be non-fatal
                     "warnings" are returned in this output string.
                     Note that if some but not all columns are
                     unreadable, this is considered to be non-fatal.
           STATUS  = An output array containing the status for each
                     column read, 1 meaning success and 0 meaning failure.

     Calls       :
           FXPAR(), WHERENAN()
     Common      :
           Uses common block FXBINTABLE--see "fxbintable.pro" for more
           information.
     Restrictions:
           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.

           Generally speaking, FXBREADM will be faster than iterative
           calls to FXBREAD when (a) a large number of columns is to be
           read or (b) the size in bytes of each cell is small, so that
           the overhead of the FOR loop in FXBREAD becomes significant.

     SIDE EFFECTS:
           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.

     Category    :
           Data Handling, I/O, FITS, Generic.
     Prev. Hist. :
           C. Markwardt, based in concept on FXBREAD version 12 from
                                  IDLASTRO, but with significant and
                                  major changes to accommodate the
                                  multiple row/column technique.  Mostly
                                  the parameter checking and general data
                                  flow remain.
           C. Markwardt, updated to read variable length arrays, and to
                                  pass columns by handle or pointer.
                                  20 Jun 2001
           C. Markwardt, try to conserve memory when creating the arrays
                                  13 Oct 2001
       Handle case of GE 50 columns, C. Markwardt, 18 Apr 2002
       Handle case where TSCAL/TZERO changes type of column,
           C. Markwardt, 23 Feb 2003
       Fix bug in handling of FOUND and numeric columns,
           C. Markwardt 12 May 2003
       Removed pre-V5.0 HANDLE options  W. Landsman July 2004
       Fix bug when HANDLE options were removed, July 2004
       Handle special cases of TSCAL/TZERO which emulate unsigned
          integers, Oct 2003
       Add DEFAULT_FLOAT keyword to select float values instead of double
          for TSCAL'ed, June 2004
       Read 64bit integer columns, E. Hivon, Mar 2008
       Add support for columns with TNULLn keywords, C. Markwardt, Apr 2010
       Add support for files larger than 2 GB, C. Markwardt, 2012-04-17
       Use V6 notation, remove IEEE_TO_HOST  W. Landsman Mar 2014

(See external/astron/fits_bintable/fxbreadm.pro)

## FXBSTATE()

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

     NAME:
          FXBSTATE()

     PURPOSE:
           Returns the state of a FITS binary table.

     Explanation : This procedure returns the state of a FITS binary table that
                   was either opened for read with the command FXBOPEN, or for
                   write with the command FXBCREATE.

     Use         : Result = FXBSTATE(UNIT)

     Inputs      : UNIT    = Logical unit number returned by FXBOPEN routine.
                             Must be a scalar integer.

     Opt. Inputs : None.

     Outputs     : The result of the function is the state of the FITS binary
                   table that UNIT points to.  This can be one of three values:

                           0 = Closed
                           1 = Open for read
                           2 = Open for write

     Opt. Outputs: None.

     Keywords    : None.

     Calls       : FXBFINDLUN

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

     Restrictions: None.

     Side effects: If UNIT is an undefined variable, then 0 (closed) is returned.

     Category    : Data Handling, I/O, FITS, Generic.

     Prev. Hist. : None.

     Written     : William Thompson, GSFC, 1 July 1993.

     Modified    : Version 1, William Thompson, GSFC, 1 July 1993.

     Version     : Version 1, 1 July 1993.
           Converted to IDL V5.0   W. Landsman   September 1997

(See external/astron/fits_bintable/fxbstate.pro)

## FXBTDIM()

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

     NAME:
    	FXBTDIM()
     Purpose     :
    	Parse TDIM-like kwywords.
     Explanation :
    	Parses the value of a TDIM-like keyword (e.g. TDIMnnn, TDESC, etc.) to
    	return the separate elements contained within.
     Use         :
    	Result = FXBTDIM( TDIM_KEYWORD )
     Inputs      :
    	TDIM_KEYWORD	= The value of a TDIM-like keyword.  Must be a
    			  character string of the form "(value1,value2,...)".
    			  If the parentheses characters are missing, then the
    			  string is simply returned as is, without any further
    			  processing.
     Opt. Inputs :
    	None.
     Outputs     :
    	The result of the function is a character string array containing the
    	values contained within the keyword parameter.  If a numerical result
    	is desired, then simply call, e.g.

    		Result = FIX( FXBTDIM( TDIM_KEYWORD ))

     Opt. Outputs:
    	None.
     Keywords    :
    	None.
     Calls       :
    	GETTOK
     Common      :
    	None.
     Restrictions:
    	The input parameter must have the proper format.  The separate values
    	must not contain the comma character.  TDIM_KEYWORD must not be an
    	array.
     Side effects:
    	None.
     Category    :
    	Data Handling, I/O, FITS, Generic.
     Prev. Hist. :
    	William Thompson, Jan. 1992.
    	William Thompson, Jan. 1993, renamed to be compatible with DOS
    		limitations.
     Written     :
    	William Thompson, GSFC, January 1992.
     Modified    :
    	Version 1, William Thompson, GSFC, 12 April 1993.
    		Incorporated into CDS library.
     Version     :
    	Version 1, 12 April 1993.
    	Converted to IDL V5.0   W. Landsman   September 1997

(See external/astron/fits_bintable/fxbtdim.pro)

## FXBTFORM

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

     NAME:
    	FXBTFORM
     PURPOSE     :
    	Returns information about FITS binary table columns.
     EXPLANATION :
    	Procedure to return information about the format of the various columns
    	in a FITS binary table.
     Use         :
    	FXBTFORM,HEADER,TBCOL,IDLTYPE,FORMAT,NUMVAL,MAXVAL
     Inputs      :
    	HEADER	= Fits binary table header.
     Opt. Inputs :
    	None.
     Outputs     :
    	TBCOL	= Array of starting column positions in bytes.
    	IDLTYPE	= IDL data types of columns.
    	FORMAT	= Character code defining the data types of the columns.
    	NUMVAL	= Number of elements of the data arrays in the columns.
    	MAXVAL	= Maximum number of elements for columns containing variable
    		  length arrays, or zero otherwise.
     Opt. Outputs:
    	None.
     Keywords    :
    	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 = ''
    			FXBTFORM, ERRMSG=ERRMSG, ...
    			IF ERRMSG NE '' THEN ...

     Calls       :
    	FXPAR
     Common      :
    	None.
     Restrictions:
    	None.
     Side effects:
    	None.
     Category    :
    	Data Handling, I/O, FITS, Generic.
     Prev. Hist. :
    	W. Thompson, Feb. 1992, from TBINFO by D. Lindler.
    	W. Thompson, Jan. 1993, renamed to be compatible with DOS limitations.
     Written     :
    	William Thompson, GSFC, February 1992.
     Modified    :
    	Version 1, William Thompson, GSFC, 12 April 1993.
    		Incorporated into CDS library.
    	Version 2, William Thompson, GSFC, 21 June 1994
    		Added ERRMSG keyword.
           Version 3, William Thompson, GSFC, 23 June 1994
                   Modified so that ERRMSG is not touched if not defined.
    	Version 4, William Thompson, GSFC, 9 April 1997
    		Modified so that variable length arrays can be read, even if
    		the maximum array size is not in the header.
    	Version 5  Wayne Landsman, GSFC, August 1997
    		Recognize double complex array type if since IDL version 4.0
           Version 6  Optimized FXPAR call, CM 1999 Nov 18
           Version 7: Wayne Landsman, GSFC Feb 2006
                   Added support for 64bit integer K format
     Version:
           Version 8: Wayne Landsman GSFC Apr 2010
                   Remove use of obsolete !ERR variable

(See external/astron/fits_bintable/fxbtform.pro)

## FXBWRITE

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

     NAME:
    	FXBWRITE
     Purpose     :
    	Write a binary data array to a disk FITS binary table file.
     Explanation :
    	Each call to FXBWRITE will write to the data file, which should already
    	have been created and opened by FXBCREATE.  One needs to call this
    	routine for every column and every row in the binary table.  FXBFINISH
    	will then close the file.
     Use         :
    	FXBWRITE, UNIT, DATA, COL, ROW
     Inputs      :
    	UNIT	= Logical unit number corresponding to the file containing the
    		  binary table.
    	DATA	= IDL data array to be written to the file.
    	COL	= Column in the binary table to place data in, starting from
    		  column one.
    	ROW	= Row in the binary table to place data in, starting from row
    		  one.
     Opt. Inputs :
    	None.
     Outputs     :
    	None.
     Opt. Outputs:
    	None.
     Keywords    :
    	BIT	= Number of bits in bit mask arrays (type "X").  Only used if
    		  the column is of variable size.
    	NANVALUE= Value signalling data dropout.  All points corresponding to
    		  this value are set to be IEEE NaN (not-a-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 = ''
    			FXBWRITE, ERRMSG=ERRMSG, ...
    			IF ERRMSG NE '' THEN ...

     Calls       :
    	None.
     Common      :
    	Uses common block FXBINTABLE--see "fxbintable.pro" for more
    	information.
     Restrictions:
    	The binary table file must have been opened with FXBCREATE.

    	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.

     Side effects:
    	None.
     Category    :
    	Data Handling, I/O, FITS, Generic.
     Prev. Hist. :
    	W. Thompson, Jan 1992, based on WRITEFITS by J. Woffard and W. Landsman.
    	W. Thompson, Feb 1992, modified to support variable length arrays.
    	W. Thompson, Feb 1992, removed all references to temporary files.
     Written     :
    	William Thompson, GSFC, January 1992.
     Modified    :
    	Version 1, William Thompson, GSFC, 12 April 1993.
    		Incorporated into CDS library.
    	Version 2, William Thompson, GSFC, 21 July 1993.
    		Fixed bug with variable length arrays.
    	Version 3, William Thompson, GSFC, 31 May 1994
    		Added ERRMSG keyword.
           Version 4, William Thompson, GSFC, 23 June 1994
                   Modified so that ERRMSG is not touched if not defined.
    	Version 5, Wayne Landsman, GSFC, 12 Aug 1997
    		Recognize IDL double complex data type
    	Version 6, Converted to IDL V5.0   W. Landsman   September 1997
           Version 7, William Thompson, 18-May-2016, change POINTER to ULONG
     Version     :
           Version 7, 18-May-2016

(See external/astron/fits_bintable/fxbwrite.pro)

## FXBWRITM

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

     NAME:
    	FXBWRITM
     PURPOSE:
           Write multiple columns/rows to a disk FITS binary table file.
     EXPLANATION :
           A call to FXBWRITM will write multiple rows and multiple
           columns to a binary table in a single procedure call.  Up to
           fifty columns may be read in a single pass.  The file should
           have already been opened with FXBOPEN (with write access) or
           FXBCREATE.  FXBWRITM optimizes writing multiple columns by
           first writing a large chunk of data to the FITS file all at
           once.  FXBWRITM cannot write variable-length arrays; use
           FXBWRITE instead.

           The number of columns is limited to 50 if data are passed by
           positional argument.  However, this limitation can be overcome
           by passing pointers to FXBWRITM.  The user should set the PASS_METHOD
           keyword to 'POINTER'  as appropriate, and  an array of pointers to
           the data in the POINTERS keyword.  The user is responsible for freeing
            the pointers.

     CALLING SEQUENCE:
    	FXBWRITM, UNIT, COL, D0, D1, D2, ..., [ ROW= , PASS_METHOD, NANVALUE=
                                   POINTERS=,  BUFFERSIZE= ]

     INPUT PARAMETERS:
    	UNIT	= Logical unit number corresponding to the file containing the
    		  binary table.
    	D0,..D49= An IDL data array to be written to the file, one for
                     each column.      These parameters will be igonred if data
                     is passed through the POINTERS keyword.
    	COL	= Column in the binary table to place data in.   May be either
                     a list of column numbers where the first column is one, or
                     a string list of column names.

     OPTIONAL INPUT KEYWORDS:
    	ROW	= Either row number in the binary table to write data to,
    		  starting from row one, or a two element array containing a
    		  range of row numbers to write.  If not passed, then
    		  the entire column is written.
    	NANVALUE= Value signalling data dropout.  All points corresponding to
    		  this value are set to be IEEE NaN (not-a-number).  Ignored
    		  unless DATA is of type float, double-precision or complex.
           NOSCALE = If set, then TSCAL/TZERO values are ignored, and data is
                     written exactly as supplied.
           PASS_METHOD = A scalar string indicating method of passing
                     data to FXBWRITM.  One of 'ARGUMENT' (indicating
                     pass by positional argument),  or'POINTER' (indicating
                     passing an array of pointers by the POINTERS
                     keyword).
                     Default:  'ARGUMENT'
           POINTERS = If PASS_METHOD is 'POINTER' then the user must pass
                     an array of IDL pointers to this keyword, one for
                     each column.    Ultimately the user is responsible for
                     deallocating pointers.
           BUFFERSIZE = Data are transferred in chunks to conserve
                     memory.  This is the size in bytes of each chunk.
                     If a value of zero is given, then all of the data
                     are transferred in one pass.  Default is 32768 (32
                     kB).
     OPTIONAL OUTPUT KEYWORDS:
    	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 = ''
    			FXBWRITE, ERRMSG=ERRMSG, ...
    			IF ERRMSG NE '' THEN ...
           WARNMSG = Messages which are considered to be non-fatal
                     "warnings" are returned in this  output string.
           STATUS  = An output array containing the status for each
                     read, 1 meaning success and 0 meaning failure.

     PROCEDURE CALLS:
          None.
     EXAMPLE:
          Write a binary table 'sample.fits' giving 43 X,Y positions and a
          21 x 21 PSF at each position:

          (1) First, create sample values
          x = findgen(43) & y = findgen(43)+1 & psf = randomn(seed,21,21,43)

          (2) Create primary header, write it to disk, and make extension header
          fxhmake,header,/initialize,/extend,/date
          fxwrite,'sample.fits',header
          fxbhmake,header,43,'TESTEXT','Test binary table extension'

          (3) Fill extension header with desired column names
          fxbaddcol,1,header,x[0],'X'             ;Use first element in each array
          fxbaddcol,2,header,y[0],'Y'             ;to determine column properties
          fxbaddcol,3,header,psf[*,*,0],'PSF'

          (4) Write extension header to FITS file
          fxbcreate,unit,'sample.fits',header

          (5) Use FXBWRITM to write all data to the extension in a single call
          fxbwritm,unit,['X','Y','PSF'], x, y, psf
          fxbfinish,unit                 ;Close the file

     COMMON BLOCKS:
    	Uses common block FXBINTABLE--see "fxbintable.pro" for more
    	information.
     RESTRICTIONS:
    	The binary table file must have been opened with FXBCREATE or
           FXBOPEN (with write access).

    	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.

           A PASS_METHOD of POINTER does not use the EXECUTE() statement and can be
           used with the IDL Virtual Machine.   However, the EXECUTE() statement is
           used when the PASS_METHOD is by arguments.
     CATEGORY:
    	Data Handling, I/O, FITS, Generic.
     PREVIOUS HISTORY:
           C. Markwardt, based on FXBWRITE and FXBREADM (ver 1), Jan 1999
     WRITTEN:
    	Craig Markwardt, GSFC, January 1999.
     MODIFIED:
           Version 1, Craig Markwardt, GSFC 18 January 1999.
                   Documented this routine, 18 January 1999.
           C. Markwardt, added ability to pass by handle or pointer.
                   Some bug fixes, 20 July 2001
           W. Landsman/B.Schulz  Allow more than 50 arguments when using pointers
           W. Landsman  Remove pre-V5.0 HANDLE options      July 2004
           W. Landsman Remove EXECUTE() call with POINTERS   May 2005
           C. Markwardt Allow the output table to have TSCAL/TZERO
              keyword values; if that is the case, then the passed values
              will be quantized to match those scale factors before being
              written.  Sep 2007
           E. Hivon: write 64bit integer and double precision columns, Mar 2008
           C. Markwardt Allow unsigned integers, which have special
              TSCAL/TZERO values.  Feb 2009
           C. Markwardt Add support for files larger than 2 GB, 2012-04-17

(See external/astron/fits_bintable/fxbwritm.pro)

## FXFINDEND

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

     NAME:
    	FXFINDEND
     Purpose     :
    	Find the end of a FITS file.
     Explanation :
    	This routine finds the end of the last logical record in a FITS file,
    	which may be different from that of the physical end of the file.  Each
    	FITS header is read in and parsed, and the file pointer is moved to
    	where the next FITS extension header would be if there is one, or to
    	the end of the file if not.
     Use         :
    	FXFINDEND, UNIT [, EXTENSION]
     Inputs      :
    	UNIT	= Logical unit number for the opened file.
     Opt. Inputs :
    	None.
     Outputs     :
    	None.
     Opt. Outputs:
           EXTENSION = The extension number that a new extension would
                       have if placed at the end of the file.
     Keywords    :
    	None.
     Calls       :
    	FXHREAD, FXPAR
     Common      :
    	None.
     Restrictions:
    	The file must have been opened for block I/O.  There must not be any
    	FITS "special records" at the end of the file.
     Side effects:
    	None.
     Category    :
    	Data Handling, I/O, FITS, Generic.
     Prev. Hist. :
    	William Thompson, Feb. 1992.
     Written     :
    	William Thompson, GSFC, February 1992.
     Modified    :
    	Version 1, William Thompson, GSFC, 12 April 1993.
    		Incorporated into CDS library.
     Version     :
    	Version 1, 12 April 1993.
    	Converted to IDL V5.0   W. Landsman   September 1997
           Added EXTENSION parameter, CM 1999 Nov 18
           Allow for possible 64bit integer number of bytes W. Landsman Nov 2007
           make Ndata a long64 to deal with large files. E. Hivon Mar 2008

(See external/astron/fits_bintable/fxfindend.pro)

## FXHCLEAN

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

     NAME:
    	FXHCLEAN
     Purpose     :
    	Removes required keywords from FITS header.
     Explanation :
    	Removes any keywords relevant to array structure from a FITS header,
    	preparatory to recreating it with the proper values.
     Use         :
    	FXHCLEAN, HEADER
     Inputs      :
    	HEADER	= FITS header to be cleaned.
     Opt. Inputs :
    	None.
     Outputs     :
    	HEADER	= The cleaned FITS header is returned in place of the input
    		  array.
     Opt. Outputs:
    	None.
     Keywords    :
    	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 = ''
    			FXHCLEAN, ERRMSG=ERRMSG, ...
    			IF ERRMSG NE '' THEN ...

     Calls       :
    	SXDELPAR, FXPAR
     Common      :
    	None.
     Restrictions:
    	HEADER must be a string array containing a properly formatted FITS
    	header.
     Side effects:
    	Warning:  when cleaning a binary table extension header, not all of the
    	keywords pertaining to columns in the table may be removed.
     Category    :
    	Data Handling, I/O, FITS, Generic.
     Prev. Hist. :
    	William Thompson, Jan 1992.
     Written     :
    	William Thompson, GSFC, January 1992.
     Modified    :
    	Version 1, William Thompson, GSFC, 12 April 1993.
    		Incorporated into CDS library.
    	Version 2, William Thompson, GSFC, 31 May 1994
    		Added ERRMSG keyword.
           Version 3, William Thompson, GSFC, 23 June 1994
                   Modified so that ERRMSG is not touched if not defined.
    	Version 4, William Thompson, GSFC, 30 December 1994
    		Added TCUNIn to list of column keywords to be removed.
     Version     :
           Version 4, 30 December 1994
    	Converted to IDL V5.0   W. Landsman   September 1997

(See external/astron/fits_bintable/fxhclean.pro)

## FXHMAKE

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

     NAME:
    	FXHMAKE
     Purpose     :
    	Create a basic FITS header array.
     Explanation :
    	Creates a basic header array with all the required keywords.  This
    	defines a basic structure which can then be added to or modified by
    	other routines.
     Use         :
    	FXHMAKE, HEADER  [, DATA ]
     Inputs      :
    	None required.
     Opt. Inputs :
    	DATA	= IDL data array to be written to file.    It must be in the
                      primary data unit unless the XTENSION keyword is supplied.
    		  This array is used to determine the values of the BITPIX and
                     NAXIS, etc. keywords.

    		  If not passed, then BITPIX is set to eight, NAXIS is set to
    		  zero, and no NAXISnnn keywords are included in this
    		  preliminary header.
     Outputs     :
    	HEADER = String array containing FITS header.
     Opt. Outputs:
    	None.
     Keywords    :
    	INITIALIZE = If set, then the header is completely initialized, and any
    		     previous entries are lost.
    	EXTEND	= If set, then the keyword EXTEND is inserted into the file,
    		  with the value of "T" (true).
    	DATE	= If set, then the DATE keyword is added to the header.
    	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 = ''
    			FXHMAKE, ERRMSG=ERRMSG, ...
    			IF ERRMSG NE '' THEN ...
           XTENSION - If set, then the header is appropriate for an image
                      extension, rather than the primary data unit.
     Calls       :
    	GET_DATE, FXADDPAR, FXHCLEAN
     Common      :
    	None.
     Restrictions:
    	Groups are not currently supported.
     Side effects:
    	BITPIX, NAXIS, etc. are defined such that complex arrays are stored as
    	floating point, with an extra first dimension of two elements (real and
    	imaginary parts).
     Category    :
    	Data Handling, I/O, FITS, Generic.
     Prev. Hist. :
    	William Thompson, Jan 1992, from SXHMAKE by D. Lindler and M. Greason.
    	Differences include:

    		* Use of FITS standard (negative BITPIX) to signal floating
    		  point numbers instead of (SDAS/Geis) DATATYPE keyword.
    		* Storage of complex numbers as pairs of real numbers.
    		* Support for EXTEND keyword, and for cases where there is no
    		  primary data array.
    		* Insertion of DATE record made optional.  Only required FITS
    		  keywords are inserted automatically.
     Written     :
    	William Thompson, GSFC, January 1992.
     Modified    :
    	Version 1, William Thompson, GSFC, 12 April 1993.
    		Incorporated into CDS library.
    	Version 2, William Thompson, GSFC, 21 June 1994
    		Added ERRMSG keyword.
           Version 3, William Thompson, GSFC, 23 June 1994
                   Modified so that ERRMSG is not touched if not defined.
    	Version 4, Wayne Landsman, GSFC, 12 August 1997
    		Recognize double complex data type
    	Converted to IDL V5.0   W. Landsman   September 1997
           Version 6, William Thompson, GSFC, 22 September 2004
                   Recognize unsigned integer types.
           Version 6.1, C. Markwardt, GSFC, 19 Jun 2005
                   Add the XTENSION keyword, which writes an XTENSION
                   keyword instead of SIMPLE.
     Version     :
           Version 6.1, 19 June 2005

(See external/astron/fits_bintable/fxhmake.pro)

## FXHMODIFY

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

     NAME:
           FXHMODIFY
     PURPOSE     :
           Modify a FITS header in a file on disk.
     Explanation :
           Opens a FITS file, and adds or modifies a parameter in the FITS header.
           Can be used for either the main header, or for an extension header.
           The modification is performed directly on the disk file.
     Use         :
           FXHMODIFY, FILENAME, NAME, VALUE, COMMENT
     Inputs      :
           FILENAME = String containing the name of the file to be read.

           NAME    = Name of parameter, scalar string  If NAME is already in the
                     header the value and possibly comment fields are modified.
                     Otherwise a new record is added to the header.  If NAME is
                     equal to either "COMMENT" or "HISTORY" then the value will be
                     added to the record without replacement.  In this case the
                     comment parameter is ignored.

           VALUE   = Value for parameter.  The value expression must be of the
                     correct type, e.g. integer, floating or string.  String
                     values of 'T' or 'F' are considered logical values.

     Opt. Inputs :
           COMMENT = String field.  The '/' is added by this routine.  Added
                     starting in position 31.  If not supplied, or set equal to ''
                     (the null string), then any previous comment field in the
                     header for that keyword is retained (when found).
     Outputs     :
           None.
     Opt. Outputs:
           None.
     Keywords    :
           EXTENSION = Either the number of the FITS extension, starting with the
                       first extension after the primary data unit being one; or a
                       character string containing the value of EXTNAME to search
                       for.  If not passed, then the primary FITS header is
                       modified.

           BEFORE  = Keyword string name.  The parameter will be placed before the
                     location of this keyword.  For example, if BEFORE='HISTORY'
                     then the parameter will be placed before the first history
                     location.  This applies only when adding a new keyword;
                     keywords already in the header are kept in the same position.

           AFTER   = Same as BEFORE, but the parameter will be placed after the
                     location of this keyword.  This keyword takes precedence over
                     BEFORE.

           FORMAT  = Specifies FORTRAN-like format for parameter, e.g. "F7.3".  A
                     scalar string should be used.  For complex numbers the format
                     should be defined so that it can be applied separately to the
                     real and imaginary parts.
           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 = ''
                           FXHMODIFY, ERRMSG=ERRMSG, ...
                           IF ERRMSG NE '' THEN ...

           NEW_HEADER = If defined and passed, then ignore NAME, VALUE,
                        and COMMENT. Instead replace the old file header
                        with the strarr given.

     Calls       :
           FXHREAD, FXPAR, FXADDPAR, BLKSHIFT
     Restrictions:
           This routine can not be used to modify any of the keywords that control
           the structure of the FITS file, e.g. BITPIX, NAXIS, PCOUNT, etc.  Doing
           so could corrupt the readability of the FITS file.
     Example:
           Modify the name 'OBJECT' keyword in the primary FITS header of a FITS
           file 'spec98.ccd' to contain the value 'test domeflat'

           IDL> fxhmodify, 'spec98.ccd', 'OBJECT', 'test domeflat'

     Side effects:
           If adding a record to the FITS header would increase the
           number of 2880 byte records stored on disk, then the file is
           enlarged before modification, unless the NOGROW keyword is passed.

     Category    :
           Data Handling, I/O, FITS, Generic.
     Prev. Hist. :
           None.
     Written     :
           William Thompson, GSFC, 3 March 1994.
     Modified    :
           Version 1, William Thompson, GSFC, 3 March 1994.
           Version 2, William Thompson, GSFC, 31 May 1994
                   Added ERRMSG keyword.
           Version 3, William Thompson, GSFC, 23 June 1994
                   Modified so that ERRMSG is not touched if not defined.
           Version 3.1 Wayne Landsman GSFC   17 March 2006
                   Fix problem in BLKSHIFT call if primary header  extended
           Version 3.2 W. Landsman 14 November 204
                   Allow for need for 64bit number of bytes
           Version 4, William Thompson, GSFC, 22-Dec-2014
                   Modified test for keyword EXTEND to only issue warning.
           Version 5, Mats Löfdahl, ISP, 11-Oct-2017
    ; Version     :
           Version 5, 11-Oct-2017

(See external/astron/fits_bintable/fxhmodify.pro)

## FXHREAD

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

     NAME:
    	FXHREAD
     Purpose     :
           Reads a FITS header from an opened disk file.
     Explanation :
           Reads a FITS header from an opened disk file.
     Use         :
    	FXHREAD, UNIT, HEADER  [, STATUS ]
     Inputs      :
    	UNIT	= Logical unit number.
     Opt. Inputs :

     Outputs     :
    	HEADER	= String array containing the FITS header.
     Opt. Outputs:
    	STATUS	= Condition code giving the status of the read.  Normally, this
    		  is zero, but is set to !ERR if an error occurs, or if the
    		  first byte of the header is zero (ASCII null).
     Keywords    :
    	None.
     Calls       :
    	None.
     Common      :
    	None.
     Restrictions:
    	The file must already be positioned at the start of the header.  It
    	must be a proper FITS file.
     Side effects:
    	The file ends by being positioned at the end of the FITS header, unless
    	an error occurs.
     Category    :
    	Data Handling, I/O, FITS, Generic.
     Prev. Hist. :
    	W. Thompson, Feb 1992, from READFITS by J. Woffard and W. Landsman.
    	W. Thompson, Aug 1992, added test for SIMPLE keyword.
     Written     :
    	William Thompson, GSFC, February 1992.
     Modified    :
    	Version 1, William Thompson, GSFC, 12 April 1993.
    		Incorporated into CDS library.
     Version     :
    	Version 1, 12 April 1993.
    	Converted to IDL V5.0   W. Landsman   September 1997

(See external/astron/fits_bintable/fxhread.pro)

## FXPAR()

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

     NAME:
            FXPAR()
     PURPOSE:
           Obtain the value of a parameter in a FITS header.
     EXPLANATION:
           The first 8 chacters of each element of HDR are searched for a match to
           NAME.  If the keyword is one of those allowed to take multiple values
           ("HISTORY", "COMMENT", or "        " (blank)), then the value is taken
           as the next 72 characters.  Otherwise, it is assumed that the next
           character is "=", and the value (and optional comment) is then parsed
           from the last 71 characters.  An error occurs if there is no parameter
           with the given name.

           If the value is too long for one line, it may be continued on to the
           the next input card, using the CONTINUE Long String Keyword convention.
           For more info, http://fits.gsfc.nasa.gov/registry/continue_keyword.html

           Complex numbers are recognized as two numbers separated by one or more
           space characters.

           If a numeric value has no decimal point (or E or D) it is returned as
           type LONG.  If it contains more than 8 numerals, or contains the
           character 'D', then it is returned as type DOUBLE.  Otherwise it is
           returned as type FLOAT.    If an integer is too large to be stored as
           type LONG, then it is returned as DOUBLE.

           If a keyword is in the header and has no value, then the default
           missing value is returned as explained below.  This can be
           distinguished from the case where the keyword is not found by the fact
           that COUNT=0 in that case, while existing keywords without a value will
           be returned with COUNT=1 or more.

     CALLING SEQUENCE:
           Result = FXPAR( HDR, NAME  [, ABORT, COUNT=, COMMENT=, /NOCONTINUE ] )

           Result = FXPAR(HEADER,'DATE')           ;Finds the value of DATE
           Result = FXPAR(HEADER,'NAXIS*')         ;Returns array dimensions as
                                                   ;vector
     REQUIRED INPUTS:
           HDR     = FITS header string array (e.g. as returned by FXREAD).  Each
                     element should have a length of 80 characters
           NAME    = String name of the parameter to return.  If NAME is of the
                     form 'keyword*' then an array is returned containing values
                     of keywordN where N is an integer.  The value of keywordN
                     will be placed in RESULT(N-1).  The data type of RESULT will
                     be the type of the first valid match of keywordN
                     found, unless DATATYPE is given.
     OPTIONAL INPUT:
           ABORT   = String specifying that FXPAR should do a RETALL if a
                     parameter is not found.  ABORT should contain a string to be
                     printed if the keyword parameter is not found.  If not
                     supplied, FXPAR will return with a negative !err if a keyword
                     is not found.
     OUTPUT:
           The returned value of the function is the value(s) associated with the
           requested keyword in the header array.

           If the parameter is complex, double precision, floating point, long or
           string, then the result is of that type.  Apostrophes are stripped from
           strings.  If the parameter is logical, 1 is returned for T, and 0 is
           returned for F.

           If NAME was of form 'keyword*' then a vector of values are returned.

     OPTIONAL INPUT KEYWORDS:
           DATATYPE = A scalar value, indicating the type of vector
                      data.  All keywords will be cast to this type.
                      Default: based on first keyword.
                      Example: DATATYPE=0.0D (cast data to double precision)
           START   = A best-guess starting position of the sought-after
                     keyword in the header.  If specified, then FXPAR
                     first searches for scalar keywords in the header in
                     the index range bounded by START-PRECHECK and
                     START+POSTCHECK.  This can speed up keyword searches
                     in large headers.  If the keyword is not found, then
                     FXPAR searches the entire header.

                     If not specified then the entire header is searched.
                     Searches of the form 'keyword*' also search the
                     entire header and ignore START.

                     Upon return START is changed to be the position of
                     the newly found keyword.  Thus the best way to
                     search for a series of keywords is to search for
                     them in the order they appear in the header like
                     this:

                           START = 0L
                           P1 = FXPAR('P1', START=START)
                           P2 = FXPAR('P2', START=START)

           PRECHECK = If START is specified, then PRECHECK is the number
                      of keywords preceding START to be searched.
                      Default: 5
           POSTCHECK = If START is specified, then POSTCHECK is the number
                       of keywords after START to be searched.
                       Default: 20
           /NOCONTINUE = If set, then continuation lines will not be read, even
                     if present in the header
           MISSING = By default, this routine returns 0 when keyword values are
                     not found.  This can be overridden by using the MISSING
                     keyword, e.g. MISSING=-1.
           /NAN    = If set, then return Not-a-Number (!values.f_nan) for missing
                     values.  Ignored if keyword MISSING is present.
           /NULL   = If set, then return !NULL (undefined) for missing values.
                     Ignored if MISSING or /NAN is present, or if earlier than IDL
                     version 8.0.  If multiple values would be returned, then
                     MISSING= or /NAN should be used instead of /NULL, making sure
                     that the datatype is consistent with the non-missing values,
                     e.g. MISSING='' for strings, MISSING=-1 for integers, or
                     MISSING=-1.0 or /NAN for floating point.  /NAN should not be
                     used if the datatype would otherwise be integer.
           /MULTIVALUE = Allow multiple values to be returned, if found in the
                         header.
     OPTIONAL OUTPUT KEYWORD:
           COUNT   = Optional keyword to return a value equal to the number of
                     parameters found by FXPAR.
           COMMENTS= Array of comments associated with the returned values.

     PROCEDURE CALLS:
           GETTOK(), VALID_NUM
     SIDE EFFECTS:

           The system variable !err is set to -1 if parameter not found, 0 for a
           scalar value returned.  If a vector is returned it is set to the number
           of keyword matches found.    This use of !ERR is deprecated.

           If a keyword occurs more than once in a header, a warning is given,
           and the first occurence is used.  However, if the keyword is "HISTORY",
           "COMMENT", or "        " (blank), then multiple values are returned.

     NOTES:
    	The functions SXPAR() and FXPAR() are nearly identical, although
    	FXPAR() has slightly more sophisticated parsing.   There is no
    	particular reason for having two nearly identical procedures, but
    	both are too widely used to drop either one.

     REVISION HISTORY:
           Version 1, William Thompson, GSFC, 12 April 1993.
                   Adapted from SXPAR
           Version 2, William Thompson, GSFC, 14 October 1994
                   Modified to use VALID_NUM instead of STRNUMBER.  Inserted
                   additional call to VALID_NUM to trap cases where character
                   strings did not contain quotation marks.
           Version 3, William Thompson, GSFC, 22 December 1994
                   Fixed bug with blank keywords, following suggestion by Wayne
                   Landsman.
           Version 4, Mons Morrison, LMSAL, 9-Jan-98
                   Made non-trailing ' for string tag just be a warning (not
                   a fatal error).  It was needed because "sxaddpar" had an
                   error which did not write tags properly for long strings
                   (over 68 characters)
           Version 5, Wayne Landsman GSFC, 29 May 1998
                   Fixed potential problem with overflow of LONG values
           Version 6, Craig Markwardt, GSFC, 28 Jan 1998,
                   Added CONTINUE parsing
           Version 7, Craig Markwardt, GSFC, 18 Nov 1999,
                   Added START, PRE/POSTCHECK keywords for better
                   performance
           Version 8, Craig Markwardt, GSFC, 08 Oct 2003,
                   Added DATATYPE keyword to cast vector keywords type
           Version 9, Paul Hick, 22 Oct 2003, Corrected bug (NHEADER-1)
           Version 10, W. Landsman, GSFC  2 May 2012
                   Keywords of form "name_0" could confuse vector extractions
           Version 11 W. Landsman, GSFC 24 Apr 2014
                   Don't convert LONG64 numbers to to double precision
           Version 12, William Thompson, 13-Aug-2014
                   Add keywords MISSING, /NAN, and /NULL
    	Version 13, W. Landsman 25-Jan-2018
    		Return ULONG64 integer if LONG64 would overflow
           Version 14, William Thompson, 03-Jun-2019
                   Add /MULTIVALUE keyword
           Version 15, Mats Löfdahl, 11-Sep-2019
                   Read CONTINUE mechanism multi-line comments.

(See external/astron/fits_bintable/fxpar.pro)

## FXPARPOS()

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

     NAME:
    	FXPARPOS()
     Purpose     :
    	Finds position to insert record into FITS header.
     Explanation :
    	Finds the position to insert a record into a FITS header.  Called from
    	FXADDPAR.
     Use         :
    	Result = FXPARPOS(KEYWRD, IEND  [, BEFORE=BEFORE ]  [, AFTER=AFTER ])
     Inputs      :
    	KEYWRD	= Array of eight-character keywords in header.
    	IEND	= Position of END keyword.
     Opt. Inputs :
    	None.
     Outputs     :
    	Result of function is position to insert record.
     Opt. Outputs:
    	None.
     Keywords    :
    	BEFORE	= Keyword string name.  The parameter will be placed before the
    		  location of this keyword.  For example, if BEFORE='HISTORY'
    		  then the parameter will be placed before the first history
    		  location.  This applies only when adding a new keyword;
    		  keywords already in the header are kept in the same position.

    	AFTER	= Same as BEFORE, but the parameter will be placed after the
    		  location of this keyword.  This keyword takes precedence over
    		  BEFORE.

           LAST    = The parameter will be placed just after the last keyword
                     which is not a blank, COMMENT, or HISTORY record.  Both the
                     BEFORE and AFTER keywords take precedence over LAST.

    	If none of the BEFORE, AFTER, or LAST keywords are passed, then IEND is
    	returned.

     Calls       :
    	None.
     Common      :
    	None.
     Restrictions:
    	KEYWRD and IEND must be consistent with the relevant FITS header.
     Side effects:
    	None.
     Category    :
    	Data Handling, I/O, FITS, Generic.
     Prev. Hist. :
    	William Thompson, Jan 1992.
     Written     :
    	William Thompson, GSFC, January 1992.
     Modified    :
    	Version 1, William Thompson, GSFC, 12 April 1993.
    		Incorporated into CDS library.
     Version     :
    	Version 1, 12 April 1993.
    	Converted to IDL V5.0   W. Landsman   September 1997
           Version 3, 15-Mar-2017, William Thompson, GSFC
                   Test for continue lines when using AFTER option.
           Version 4, 16-Mar-2017, William Thompson, GSFC, added LAST keyword
           Version 5, 30-Mar-2017, William Thompson, GSFC, fix bug if AFTER=''

(See external/astron/fits_bintable/fxparpos.pro)

## FXREAD

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

     NAME:
    	FXREAD
     Purpose     :
    	Read basic FITS files.
     Explanation :
    	Read an image array from a disk FITS file.  Optionally allows the
    	user to read in only a subarray and/or every Nth pixel.
     Use         :
    	FXREAD, FILENAME, DATA  [, HEADER  [, I1, I2  [, J1, J2 ]]  [, STEP]]
     Inputs      :
    	FILENAME = String containing the name of the file to be read.
     Opt. Inputs :
    	I1,I2	 = Data range to read in the first dimension.  If passed, then
    		   HEADER must also be passed.  If not passed, or set to -1,-1,
    		   then the entire range is read.
    	J1,J2	 = Data range to read in the second dimension.  If passed, then
    		   HEADER and I1,J2 must also be passed.  If not passed, or set
    		   to -1,-1, then the entire range is read.
    	STEP	 = Step size to use in reading the data.  If passed, then
    		   HEADER must also be passed.  Default value is 1.  Ignored if
    		   less than 1.
     Outputs     :
    	DATA	 = Data array to be read from the file.
     Opt. Outputs:
    	HEADER	 = String array containing the header for the FITS file.
     Keywords    :
           /COMPRESS - If this keyword is set and non-zero, then then treat
                    the file as gzip compressed.    By default FXREAD assumes
                    the file is gzip compressed if it ends in ".gz"
    	NANVALUE = Value signalling data dropout.  All points corresponding to
    		   IEEE NaN (not-a-number) are set to this value.  Ignored
    		   unless DATA is of type float or double-precision.
           EXTENSION = FITS extension.  It can be a scalar integer,
                    indicating the extension number (extension number 0
                    is the primary HDU).  It can also be a scalar string,
                    indicating the extension name (EXTNAME keyword).
                    Default: 0 (primary HDU)
    	PROMPT	 = If set, then the optional parameters are prompted for at the
    		   keyboard.
    	AVERAGE	 = If set, then the array size is reduced by averaging pixels
    		   together rather than by subselecting pixels.  Ignored unless
    		   STEP is nontrivial.  Note:  this is much slower.
    	YSTEP	 = If passed, then STEP is the step size in the 1st dimension,
    		   and YSTEP is the step size in the 2nd dimension.  Otherwise,
    		   STEP applies to both directions.
    	NOSCALE	 = If set, then the output data will not be scaled using the
    		   optional BSCALE and BZERO keywords in the FITS header.
    		   Default is to scale, if and only if BSCALE and BZERO are
    		   present and nontrivial.
    	NOUPDATE = If set, then the optional BSCALE and BZERO keywords in the
    		   optional HEADER array will not be changed.  The default is
    		   to reset these keywords to BSCALE=1, BZERO=0.  Ignored if
    		   NOSCALE is set.
    	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 = ''
    			FXREAD, ERRMSG=ERRMSG, ...
    			IF ERRMSG NE '' THEN ...
           NODATA   = If set, then the array is not read in, but the
                      primary header is read.

     Calls       :
    	GET_DATE, FXADDPAR, FXHREAD, FXPAR, WHERENAN
     Common      :
    	None.
     Restrictions:
    	Groups are not supported.

    	The optional parameters I1, I2, and STEP only work with one or
    	two-dimensional arrays.  J1 and J2 only work with two-dimensional
    	arrays.

    	Use of the AVERAGE keyword is not compatible with arrays with missing
    	pixels.

     Side effects:
    	If the keywords BSCALE and BZERO are present in the FITS header, and
    	have non-trivial values, then the returned array DATA is formed by the
    	equation

    			DATA = BSCALE*original + BZERO

    	However, this behavior can overridden by using the /NOSCALE keyword.

    	If the data is scaled, then the optional HEADER array is changed so
    	that BSCALE=1 and BZERO=0.  This is so that these scaling parameters
    	are not applied to the data a second time by another routine.  Also,
    	history records are added storing the original values of these
    	constants.  Note that only the returned array is modified--the header
    	in the FITS file itself is untouched.

    	If the /NOUPDATE keyword is set, however, then the BSCALE and BZERO
    	keywords are not changed.  It is then the user's responsibility to
    	ensure that these parameters are not reapplied to the data.  In
    	particular, these keywords should not be present in any header when
    	writing another FITS file, unless the user wants their values to be
    	applied when the file is read back in.  Otherwise, FITS readers will
    	read in the wrong values for the data array.

     Category    :
    	Data Handling, I/O, FITS, Generic.
     Prev. Hist. :
    	W. Thompson, May 1992, based in part on READFITS by W. Landsman, and
    			       STSUB by M. Greason and K. Venkatakrishna.
    	W. Thompson, Jun 1992, added code to interpret BSCALE and BZERO
    			       records, and added NOSCALE and NOUPDATE
    			       keywords.
    	W. Thompson, Aug 1992, changed to call FXHREAD, and to add history
    			       records for BZERO, BSCALE.
     Minimium IDL Version:
           V6.0 (uses V6.0 notation)
     Written     :
    	William Thompson, GSFC, May 1992.
     Modified    :
    	Version 1, William Thompson, GSFC, 12 April 1993.
    		Incorporated into CDS library.
    	Version 2, William Thompson, GSFC, 17 November 1993.
    		Corrected bug with AVERAGE keyword on non-IEEE compatible
    		machines.
    		Corrected bug with subsampling on VAX machines.
    	Version 3, William Thompson, GSFC, 31 May 1994
    		Added ERRMSG keyword.
           Version 4, William Thompson, GSFC, 23 June 1994
                   Modified so that ERRMSG is not touched if not defined.
           Version 5, Zarro (SAC/GSFC), 14 Feb 1997
                   Added I/O error checking
           Version 6, 20-May-1998, David Schlegel/W. Thompson
                   Allow a single pixel to be read in.
                   Change the signal to read in the entire array to be -1
           Version 7 C. Markwardt 22 Sep 2003
                   If the image is empty (NAXIS EQ 0), or NODATA is set, then
                   return only the header.
           Version 8 W. Landsman  29 June 2004
                   Added COMPRESS keyword, check for .gz extension
           Version 9, William Thompson, 19-Aug-2004
                   Make sure COMPRESS is treated as a scalar
           Version 10, Craig Markwardt, 01 Mar 2004
                   Add EXTENSION keyword and ability to read different
                   extensions than the primary one.
           Version 11,  W. Landsman   September 2006
                   Assume since V5.5, remove VMS support
           Version 11.1,  W. Landsman   November 2007
                   Allow for possibility number of bytes requires 64 bit integer
           Version 12, William Thompson, 18-Jun-2010, update BLANK value.
           Version 13, W. Landsman  Remove IEEE_TO_HOST, V6.0 notation
           Version 14, William Thompson, 25-Sep-2014, fix BSCALE bug in version 13
           Version 15, William Thompson, 24-Jul-2017, allow NAXISn=0 if n>NAXIS
           Version 16, W. Landsman 25-Sep-2017, allow NAXISn=0

(See external/astron/fits_bintable/fxread.pro)

## FXWRITE

[Previous Routine] [List of Routines]

     NAME:
    	FXWRITE
     Purpose     :
    	Write a disk FITS file.
     Explanation :
           Creates or appends to a disk FITS file and writes a FITS
           header, and optionally an image data array.
     Use         :
    	FXWRITE, FILENAME, HEADER [, DATA ]
     Inputs      :
    	FILENAME = String containing the name of the file to be written.
    	HEADER	 = String array containing the header for the FITS file.
     Opt. Inputs :
    	DATA	 = IDL data array to be written to the file.  If not passed,
    		   then it is assumed that extensions will be added to the
    		   file.
     Outputs     :
    	None.
     Opt. Outputs:
    	None.
     Keywords    :
    	NANVALUE = Value signalling data dropout.  All points corresponding to
    		   this value are set to be IEEE NaN (not-a-number).  Ignored
    		   unless DATA is of type float, double-precision or complex.
    	NOUPDATE = If set, then the optional BSCALE and BZERO keywords in the
    		   HEADER array will not be changed.  The default is to reset
    		   these keywords to BSCALE=1, BZERO=0.
           APPEND = If set, then an existing file will be appended to.
                    Appending to a non-existent file will create it.  If
                    a primary HDU already exists then it will be modified
                    to have EXTEND = T.
           ALLOW_DEGEN = If set, then don't check for degenerate axes in
                         CHECK_FITS.
    	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 = ''
    			FXWRITE, ERRMSG=ERRMSG, ...
    			IF ERRMSG NE '' THEN ...

     Calls       :
    	CHECK_FITS, GET_DATE, FXADDPAR, FXPAR
     Common      :
    	None.
     Restrictions:
    	If DATA is passed, then HEADER must be consistent with it.  If no data
    	array is being written to the file, then HEADER must also be consistent
    	with that.  The routine FXHMAKE can be used to create a FITS header.

    	If found, then the optional keywords BSCALE and BZERO in the HEADER
    	array is changed so that BSCALE=1 and BZERO=0.  This is so that these
    	scaling parameters are not applied to the data a second time by another
    	routine.  Also, history records are added storing the original values
    	of these constants.  (Other values of BZERO are used for unsigned
    	integers.)

    	If the /NOUPDATE keyword is set, however, then the BSCALE and BZERO
    	keywords are not changed.  The user should then be aware that FITS
    	readers will apply these numbers to the data, even if the data is
    	already converted to floating point form.

    	Groups are not supported.

     Side effects:
    	HEADER may be modified.  One way it may be modified is describe
           above under NOUPDATE.  The first header card may also be
           modified to conform to the FITS standard if it does not
           already agree (i.e. use of either the SIMPLE or XTENSION
           keyword depending on whether the image is the primary HDU or
           not).
     Category    :
    	Data Handling, I/O, FITS, Generic.
     Prev. Hist. :
    	W. Thompson, Jan 1992, from WRITEFITS by J. Woffard and W. Landsman.
    	Differences include:

    		* Made DATA array optional, and HEADER array mandatory.
    		* Changed order of HEADER and DATA parameters.
    		* No attempt made to fix HEADER array.

    	W. Thompson, May 1992, changed open statement to force 2880 byte fixed
    			       length records (VMS).  The software here does not
    			       depend on this file configuration, but other
    			       FITS readers might.
    	W. Thompson, Aug 1992, added code to reset BSCALE and BZERO records,
    			       and added the NOUPDATE keyword.
     Written     :
    	William Thompson, GSFC, January 1992.
     Modified    :
    	Version 1, William Thompson, GSFC, 12 April 1993.
    		Incorporated into CDS library.
    	Version 2, William Thompson, GSFC, 31 May 1994
    		Added ERRMSG keyword.
    	Version 3, William Thompson, GSFC, 23 June 1994
    		Modified so that ERRMSG is not touched if not defined.
    	Version 4, William Thompson, GSFC, 12 August 1999
    		Catch error if unable to open file.
           Version 4.1 Wayne Landsman, GSFC, 02 May 2000
                   Remove !ERR in call to CHECK_FITS, Use ARG_PRESENT()
           Version 5, William Thompson, GSFC, 22 September 2004
                   Recognize unsigned integer types
           Version 5.1 W. Landsman 14 November 2004
                   Allow for need for 64bit number of bytes
           Version 6, Craig Markwardt, GSFC, 30 May 2005
                   Ability to append to existing files
           Version 7, W. Landsman GSFC, Mar 2014
                   Remove HOST_TO_IEEE, Use V6.0 notation
           Version 8, William Thompson, 26-Jun-2019, add /ALLOW_DEGEN
     Version     :
    	Version 8, 26-Jun-2019

(See external/astron/fits_bintable/fxwrite.pro)