12.2 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 an 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 fits_write_key_longwarn 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:

    fits_write_key_longstr  - write a long string keyword value
    fits_insert_key_longstr - insert a long string keyword value
    fits_modify_key_longstr - modify a long string keyword value
    fits_update_key_longstr - modify a long string keyword value
    fits_read_key_longstr   - read  a long string keyword value
    fits_delete_key         - delete a keyword

The fits_read_key_longstr 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 arrays require that the calling program pre-allocate adequate space to hold the array of data. Consequently, programs which use the fits_read_key_longstr 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,

      fits_modify_key_str - modify an existing string keyword value
      fits_update_key_str - 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 routines to write string valued keywords (fits_update_key and fits_write_key) do not support this long string convention and only support 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 fits_write_key_longstr 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.