next up previous contents Back To Software Index
Next: Arrays of Strings Up: Local FITS Conventions Previous: Local FITS Conventions

Long String Keyword Values.

The length of a standard FITS string keyword is limited to 68 characters because it must fit entirely within a single FITS header keyword record. In some instances it is necessary to encode strings longer than this limit, so CFITSIO supports a local convention in which the string value is continued over multiple keywords. This continuation convention uses a ampersand character at the end of each substring to indicate that it is continued on the next keyword, and the continuation keywords all have the name CONTINUE without an equal sign in column 9. The string value may be continued in this way over as many additional CONTINUE keywords as is required. The following lines illustrate this continuation convention which is used in the value of the STRKEY keyword:

LONGSTRN= 'OGIP 1.0'    / The OGIP Long String Convention may be used.
STRKEY  = 'This is a very long string keyword&'  / Optional Comment
CONTINUE  ' value that is continued over 3 keywords in the &  '
CONTINUE  'FITS header.' / This is another optional comment.
It is recommended that the LONGSTRN keyword, as shown here, always be included in any HDU that uses this longstring convention as a warning to any software that must read the keywords. A routine called ffplsw has been provided in CFITSIO to write this keyword if it does not already exist.

This long string convention is supported by the following CFITSIO routines:

      ffpkls - write an arbitrarily long string keyword value
      ffgkls - read  an arbitrarily long string keyword value
      ffdkey - delete a keyword
The ffgkls routine is unique among all the CFITSIO routines in that it internally allocates memory for the long string value; all the other CFITSIO routines that deal with strings require that the calling program pre-allocate adequate space to hold the array of characters. Consequently, programs which use the ffgkls routine must be careful to free the allocated memory for the string when it is no longer needed.

The following 2 routines also have limited support for this long string convention,

      ffmkys - modify an existing string keyword value
      ffukys - update a string keyword value
in that they will correctly overwrite an existing long string value, but the new string value is limited to a maximum of 68 characters in length.

The more commonly used CFITSIO routine to write string valued keywords (ffpkys) does NOT support this long string convention and only supports strings up to 68 characters in length. This has been done deliberately to prevent programs from inadvertently writing keywords using this non-standard convention without the explicit intent of the programmer or user. The ffpkls routine must be called instead to write long strings. This routine can also be used to write ordinary string values less than 68 characters in length.

next up previous contents Back To Software Index
Next: Arrays of Strings Up: Local FITS Conventions Previous: Local FITS Conventions