9.3.4 Insert Keyword Routines

These insert routines are somewhat less efficient than the `update' or `write' keyword routines because the following keywords in the header must be shifted down to make room for the inserted keyword. See Appendix B for the definition of the parameters used in these routines.

1
Insert a new keyword record into the CHU at the specified position (i.e., immediately preceding the (keynum)th keyword in the header.)

  int fits_insert_record / ffirec
      (fitsfile *fptr, int keynum, char *card, > int *status)

2
Insert a new keyword into the CHU. The new keyword is inserted immediately following the last keyword that has been read from the header. The `longstr' version has the same functionality as the `str' version except that it also supports the local long string keyword convention for strings longer than 68 characters. A null pointer may be entered for the comment parameter which will cause the comment field 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_insert_card / ffikey
      (fitsfile *fptr, char *card, > int *status)

  int fits_insert_key_[str, longstr] / ffi[kys, kls]
      (fitsfile *fptr, char *keyname, char *value, char *comment,
       > int *status)

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

  int fits_insert_key_[flt, fixflt, dbl, fixdbl] / ffiky[edfg]
      (fitsfile *fptr, char *keyname, DTYPE numval, int decimals,
       char *comment, > int *status)

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

3
Insert a new keyword with an undefined, or null, value into the CHU. The value string of the keyword is left blank in this case.

  int fits_insert_key_null / ffikyu
      (fitsfile *fptr, char *keyname, char *comment, > int *status)