5.4.2 Keyword Writing Routines

1

Write a keyword of the appropriate data type into the CHU. The first routine simply appends a new keyword whereas the second routine will update the value and comment fields of the keyword if it already exists, otherwise it appends a new keyword. Note that the address to the value, and not the value itself, must be entered. The datatype parameter specifies the data type of the keyword value with one of the following values: TSTRING, TLOGICAL (== int), TBYTE, TSHORT, TUSHORT, TINT, TUINT, TLONG, TLONGLONG, TULONG, TULONGLONG, TFLOAT, TDOUBLE. Within the context of this routine, TSTRING corresponds to a 'char*' data type, i.e., a pointer to a character array. A null pointer may be entered for the comment parameter in which case the keyword comment field will be unmodified or left blank.

  int fits_write_key / ffpky
      (fitsfile *fptr, int datatype, char *keyname, DTYPE *value,
          char *comment, > int *status)

  int fits_update_key / ffuky
      (fitsfile *fptr, int datatype, char *keyname, DTYPE *value,
          char *comment, > int *status)

2

Write a keyword with a null or undefined value (i.e., the value field in the keyword is left blank). The first routine simply appends a new keyword whereas the second routine will update the value and comment fields of the keyword if it already exists, otherwise it appends a new keyword. A null pointer may be entered for the comment parameter in which case the keyword comment field will be unmodified or left blank.

  int fits_write_key_null / ffpkyu
      (fitsfile *fptr, char *keyname, char *comment, > int *status)

  int fits_update_key_null / ffukyu
      (fitsfile *fptr, char *keyname, char *comment, > int *status)

3

Write (append) a COMMENT or HISTORY keyword to the CHU. The comment or history string will be continued over multiple keywords if it is longer than 70 characters.

  int fits_write_comment / ffpcom
      (fitsfile *fptr, char *comment, > int *status)

  int fits_write_history / ffphis
      (fitsfile *fptr, char *history, > int *status)

4

Write the DATE keyword to the CHU. The keyword value will contain the current system date as a character string in 'yyyy-mm-ddThh:mm:ss' format. If a DATE keyword already exists in the header, then this routine will simply update the keyword value with the current date.

  int fits_write_date / ffpdat
      (fitsfile *fptr, > int *status)

5

Write a user specified keyword record into the CHU. This is a low-level routine which can be used to write any arbitrary record into the header. The record must conform to the all the FITS format requirements.

  int fits_write_record / ffprec
      (fitsfile *fptr, char *card, > int *status)

6

Update an 80-character record in the CHU. If a keyword with the input name already exists, then it is overwritten by the value of card. This could modify the keyword name as well as the value and comment fields. If the keyword doesn't already exist then a new keyword card is appended to the header.

  int fits_update_card / ffucrd
      (fitsfile *fptr, char *keyname, char *card, > int *status)

7

Modify (overwrite) the comment field of an existing keyword.

  int fits_modify_comment / ffmcom
      (fitsfile *fptr, char *keyname, char *comment, > int *status)

8

Write the physical units string into an existing keyword. This routine uses a local convention, shown in the following example, in which the keyword units are enclosed in square brackets in the beginning of the keyword comment field.

     VELOCITY=                 12.3 / [km/s] orbital speed

  int fits_write_key_unit / ffpunt
      (fitsfile *fptr, char *keyname, char *unit, > int *status)

9

Rename an existing keyword, preserving the current value and comment fields.

  int fits_modify_name / ffmnam
      (fitsfile *fptr, char *oldname, char *newname, > int *status)

10

Delete a keyword record. The space occupied by the keyword is reclaimed by moving all the following header records up one row in the header. The first routine deletes a keyword at a specified position in the header (the first keyword is at position 1), whereas the second routine deletes a specifically named keyword. Wild card characters may be used when specifying the name of the keyword to be deleted. The third routine deletes the (next) keyword that contains the literal character string specified by the 'string' argument.

  int fits_delete_record / ffdrec
      (fitsfile *fptr, int   keynum,  > int *status)

  int fits_delete_key / ffdkey
      (fitsfile *fptr, char *keyname, > int *status)

  int fits_delete_str / ffdstr
      (fitsfile *fptr, char *string, > int *status)