- 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.
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
Version 10, 21-Jun-2018