HIERARCH keywords in CFITSIO

[William Pence]

Here is some information about support for the HIERARCH keyword convention
in CFITSIO, for those who may be interested:

--------------------------------------------------------------------------

At the request of ESO scientists, the CFITSIO library (available at
http://legacy.gsfc.nasa.gov/fitsio) has been enhanced to support their 
convention for hierarchical FITS keyword names.  A typical keyword using 
this convention looks like:  

HIERARCH ESO INS FOCU POS = -0.00002500 / Focus position

Basically, this convention uses the FITS keyword 'HIERARCH' to indicate that this
convention is being used.  Then the actual keyword name begins in column 10 and
can be composed of a number of subfields.  In this example, 'ESO' indicates the
domain of the keyword, 'INS' is the catagory, and 'FOCU' and 'POS' are subsystems
to which the keyword applies. The equals sign marks the end of the keyword name
and is followed by the usual value and comment fields just as in ordinary FITS
keywords. Further details of this convention are described at
http://arcdev.hq.eso.org/dicb/dicd/dic-1-1.4.html (search for HIERARCH).

This specific use of the HIERARCH convention is probably of limited interest 
outside of ESO itself, but it has been implemented in CFITSIO in a general way 
so that a much broader range of keyword names are now supported, including names
up to 67 characters in length, and names containing other ASCII text characters 
that would otherwise not be allowed in a standard keyword name.  For example, 
all the following keywords can now be read or written with CFITSIO.

12345678901234567890123456789012345678901234567890123456789012345678901234567890
HIERARCH LongKeyword = 47.5 / This keyword has > 8 characters, and mixed case
HIERARCH XTE$TEMP = 98.6 / This keyword contains the '$' character
HIERARCH Earth is a star = F / This keyword contains embedded spaces
HIERARCH ThisIsOneOfTheLongestPossibleKeywordsAllowedWhenUsingThisConvention = 9

Application programs do not need to specify the 'HIERARCH' part of the keyword
name when reading or writing keywords with CFITSIO (although it may be specified
if desired).  When writing a keyword, CFITSIO first checks to see if the keyword
name is legal as a standard FITS keyword (no more than 8 characters long and
containing only letters, digits, or a minus sign or underscore). If so it writes
it as a normal FITS keyword, otherwise it uses the hierarch convention to write
the keyword.   As shown in the last example above, the maximum keyword name
length is 67 characters, (leaving only 1 space for the value field!).  A more
practical limit would be about 40 characters, which would leave enough room for
most keyword values.  Currently CFITSIO returns an error if there is not enough
room for both the keyword name and the keyword value on the 80-character card,
except for string-valued keywords which are simply truncated so that the closing
quote character falls in column 80.  Note that this hierarch convention can be
combined in CFITSIO with the HEASARC long string value convention to produce
keywords with both long keyword names and long string values extending over
multiple keywords (the keyword name must all fit on the first card however). In
the current implementation, CFITSIO preserves the case of the letters when
writing the keyword name, but it is case-insensitive when searching for a
keyword.  Thus, the first keyword in the examples above could be read by looking
for the keyword 'LONGKEYWORD' or 'Longkeyword', or any other combination of upper
and lower case. The current implementation allows any ASCII text character (ASCII
32 to ASCII 126) in the keyword name except for the '=' character.  A space is
also required on either side of the equal sign, but in principle this could be
relaxed to provide room for 2 more characters in the other keyword fields.

Obviously, this convention should be used sparingly, or not at all in FITS files
that are intended to be imported into other data systems that don't support this
convention.  On the otherhand, this convention will enable some new applications
that require longer keywords to use the FITS format. 

- Bill Pence
____________________________________________________________________
Dr. William Pence                          pence at tetra.gsfc.nasa.gov
NASA/GSFC Code 662         HEASARC         +1-301-286-4599 (voice)     
Greenbelt MD 20771                         +1-301-286-1684 (fax)