6. Changing Keywords

fh_set_int(), fh_set_flt(), fh_set_str(), fh_set_bool(), and fh_set_val() all follow the same logic to change or add a keyword to a FITS header:

1. If the keyword already exists:
   • The original position in the header and `idx' assignment are kept. (So the `idx' argument to fh_set() is ignored in this case.)
   • The new value is substituted.
   • A new comment is inserted, unless comment is NULL, in which case the old comment is left in tact.
2. If the keyword is not found:
   • A new card is inserted according to the `idx' number given (at the end of the list if idx == FH_AUTO.)
   • The new value is used.
   • The new comment is used, or if it is NULL, no comment field is inserted (not even the '/' character.)

For fh_set_com(), each call results in (case 2), a new card being added, unless an matching keyword with exactly the same `idx' number (and not FH_AUTO) is found. So, specific COMMENT idx=1001.1 could be set and re-set any number of times with fh_set_com(), but if the `idx' numbers were different, or equal to FH_AUTO then multiple fh_set_com() calls would result in multiple COMMENT cards being added to the header.

All of this is done in memory. Nothing happens to the file until fh_rewrite() is called. At that time, if new keywords were added, the call may fail because of lack of space in the header.

6.1 fh_remove()

Remove a card from the list. Upon the following fh_rewrite(), the card will disappear from the file, and an extra reserved COMMENT card will appear at the end to replace it, keeping the header the same size, no matter how many cards you remove.

6.2 fh_set_all_units()

By default, if fh_set() operations are performed on a PHU read from a file, they are not applied to extension units. Call this function before calling any other fh_set* functions on a PHU when you also want the extensions (which you'd get with fh_ehu()) to be changed, otherwise fh_set() only applies to the current HeaderUnit.

6.3 fh_set_com()

`name' should be either "COMMENT" or "HISTORY" and `value' is the rest of the line (will be truncated at 72 characters.)

6.4 fh_set_bool()

Set a logical or boolean FITS keyword. A non-zero `value' or FH_TRUE is saved as 'T' and FH_FALSE is saved as 'F'.

6.5 fh_set_int()

Set an integer FITS keyword.

6.6 fh_set_flt()

Use this to set float (real) values. The value must be of type `double' and will be inserted in the FITS card as a number with a decimal point, and possibly an exponent (as determined by the %G format instruction to printf). `digits' is the number of significant digits in the quantity `value'. It must be an integer value 1 or greater. Alternatively, `digits' can be specified as .1, .2, .3, ... .9 to specify up to 9 fixed digits after the decimal point (and used instead of plus a trailing decimal to keep it a legal FITS floating point keyword. When printing a year, with a century, prec should be 0, or at least 4 to ensure that the value does not get printed with an exponent by %G.

6.7 fh_set_str()

Set a string FITS keyword. If string is longer than 18 characters, the start of the comment field will be shifted, and a comment may get truncated.

6.8 fh_set_val()

Similar to fh_set_str(), but assumes that you have already sprintf'd the value into a buffer. Use this to get precise control over the formatting of the value field.

6.9 fh_merge()

Merge source_hu into target_hu and sort according to the `idx' numbers in both lists. source_hu is not modified.