This page was created by the IDL library routine
mk_html_help2.
Last modified: Wed Dec 20 10:37:44 2023.
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)