4.12.4 HIERARCH Convention for Extended Keyword Names

CFITSIO supports the HIERARCH keyword convention which allows keyword names that are longer than 8 characters. This convention was developed at the European Southern Observatory (ESO) and allows characters consisting of digits 0-9, upper case letters A-Z, the dash '-' and the underscore '_'. The components of hierarchical keywords are separated by a single ASCII space charater. For instance:

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 ('ESO INS FOCU POS' in this example) begins in column 10. The equals sign marks the end of the keyword name and is followed by the usual value and comment fields just as in standard FITS keywords. Further details of this convention are described at http://fits.gsfc.nasa.gov/registry/hierarch_keyword.html and in Section 4.4 of the ESO Data Interface Control Document that is linked to from http://archive.eso.org/cms/tools-documentation/eso-data-interface-control.html.

This convention allows a broader range of keyword names than is allowed by the FITS Standard. Here are more examples of such keywords:

HIERARCH LONGKEYWORD = 47.5 / Keyword has > 8 characters
HIERARCH LONG-KEY_WORD2 = 52.3 / Long keyword with hyphen, underscore and digit
HIERARCH EARTH IS A STAR = F / Keyword contains embedded spaces

CFITSIO will transparently read and write these keywords, so application programs do not in general need to know anything about the specific implementation details of the HIERARCH convention. In particular, application programs do not need to specify the `HIERARCH' part of the keyword name when reading or writing keywords (although it may be included 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 standard FITS keyword, otherwise it uses the hierarch convention to write the keyword. The maximum keyword name length is 67 characters, which leaves only 1 space for the value field. A more practical limit is about 40 characters, which leaves enough room for most keyword values. 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. A space is also required on either side of the equal sign.