9.3.3 Write Keyword Routines

These routines simply append a new keyword to the header and do not check to see if a keyword with the same name already exists. In general it is preferable to use the fits_update_key routine to ensure that the same keyword is not written more than once to the header. See Appendix B for the definition of the parameters used in these routines.

1

Write (append) a new keyword of the appropriate data type into the CHU. A null pointer may be entered for the comment parameter, which will cause the comment field of the keyword to be left blank. The flt, dbl, cmp, and dblcmp versions of this routine have the added feature that if the 'decimals' parameter is negative, then the 'G' display format rather then the 'E' format will be used when constructing the keyword value, taking the absolute value of 'decimals' for the precision. This will suppress trailing zeros, and will use a fixed format rather than an exponential format, depending on the magnitude of the value.

  int fits_write_key_str / ffpkys
      (fitsfile *fptr, char *keyname, char *value, char *comment,
       > int *status)

  int fits_write_key_[log, lng] /  ffpky[lj]
      (fitsfile *fptr, char *keyname, DTYPE numval, char *comment,
       > int *status)

  int fits_write_key_[flt, dbl, fixflg, fixdbl] / ffpky[edfg]
      (fitsfile *fptr, char *keyname, DTYPE numval, int decimals,
      char *comment, > int *status)

  int fits_write_key_[cmp, dblcmp, fixcmp, fixdblcmp] / ffpk[yc,ym,fc,fm]
      (fitsfile *fptr, char *keyname, DTYPE *numval, int decimals,
      char *comment, > int *status)

2

Write (append) a string valued keyword into the CHU which may be longer than 68 characters in length. This uses the Long String Keyword convention that is described in the`Local FITS Conventions' section in Chapter 4. Since this uses a non-standard FITS convention to encode the long keyword string, programs which use this routine should also call the fits_write_key_longwarn routine to add some COMMENT keywords to warn users of the FITS file that this convention is being used. The fits_write_key_longwarn routine also writes a keyword called LONGSTRN to record the version of the longstring convention that has been used, in case a new convention is adopted at some point in the future. If the LONGSTRN keyword is already present in the header, then fits_write_key_longwarn will simply return without doing anything.

  int fits_write_key_longstr / ffpkls
      (fitsfile *fptr, char *keyname, char *longstr, char *comment,
       > int *status)

  int fits_write_key_longwarn / ffplsw
      (fitsfile *fptr, > int *status)

3

Write (append) a numbered sequence of keywords into the CHU. The starting index number (nstart) must be greater than 0. One may append the same comment to every keyword (and eliminate the need to have an array of identical comment strings, one for each keyword) by including the ampersand character as the last non-blank character in the (first) COMMENTS string parameter. This same string will then be used for the comment field in all the keywords. One may also enter a null pointer for the comment parameter to leave the comment field of the keyword blank.

  int fits_write_keys_str / ffpkns
      (fitsfile *fptr, char *keyroot, int nstart, int nkeys,
       char **value, char **comment, > int *status)

  int fits_write_keys_[log, lng] / ffpkn[lj]
      (fitsfile *fptr, char *keyroot, int nstart, int nkeys,
       DTYPE *numval, char **comment, int *status)

  int fits_write_keys_[flt, dbl, fixflg, fixdbl] / ffpkne[edfg]
      (fitsfile *fptr, char *keyroot, int nstart, int nkey,
       DTYPE *numval, int decimals, char **comment, > int *status)

4

Copy an indexed keyword from one HDU to another, modifying the index number of the keyword name in the process. For example, this routine could read the TLMIN3 keyword from the input HDU (by giving keyroot = `TLMIN' and innum = 3) and write it to the output HDU with the keyword name TLMIN4 (by setting outnum = 4). If the input keyword does not exist, then this routine simply returns without indicating an error.

  int fits_copy_key / ffcpky
      (fitsfile *infptr, fitsfile *outfptr, int innum, int outnum,
       char *keyroot, > int *status)

5

Write (append) a `triple precision' keyword into the CHU in F28.16 format. The floating point keyword value is constructed by concatenating the input integer value with the input double precision fraction value (which must have a value between 0.0 and 1.0). The ffgkyt routine should be used to read this keyword value, because the other keyword reading routines will not preserve the full precision of the value.

  int fits_write_key_triple / ffpkyt
      (fitsfile *fptr, char *keyname, long intval, double frac,
       char *comment, > int *status)

6

Write keywords to the CHDU that are defined in an ASCII template file. The format of the template file is described under the fits_parse_template routine.

  int fits_write_key_template / ffpktp
      (fitsfile *fptr, const char *filename, > int *status)