Read Keyword Routines

These routines return the value of the specified keyword(s). Wild card characters (*, ?, or #) may be used when specifying the name of the keyword to be read: a '?' will match any single character at that position in the keyword name and a '*' will match any length (including zero) string of characters. The '#' character will match any consecutive string of decimal digits (0 - 9). Note that when a wild card is used in the input keyword name, the routine will only search for a match from the current header position to the end of the header. It will not resume the search from the top of the header back to the original header position as is done when no wildcards are included in the keyword name. If the desired keyword string is 8-characters long (the maximum length of a keyword name) then a '*' may be appended as the ninth character of the input name to force the keyword search to stop at the end of the header (e.g., 'COMMENT *' will search for the next COMMENT keyword). The ffgrec routine may be used to set the starting position when doing wild card searches.

1

Get the nth 80-character header record from the CHU. The first keyword in the header is at keynum = 1; if keynum = 0 then this routine simple moves the internal pointer to the beginning of the header so that subsequent keyword operations will start at the top of the header; it returns a null card value in this case.

  int fits_read_record / ffgrec
      (fitsfile *fptr, int keynum, > char *card, int *status)

2

Get the name, value (as a string), and comment of the nth keyword in CHU. This routine also checks that the returned keyword name (keyname) contains only legal ASCII characters. If a NULL comment pointer is given on input, then the comment string will not be returned. A null value string will be returned if the keyword has no defined value (i.e., if the value field in the keyword is blank).

  int fits_read_keyn / ffgkyn
      (fitsfile *fptr, int keynum, > char *keyname, char *value,
       char *comment, int *status)

3

Get the 80-character header record for the named keyword

  int fits_read_card / ffgcrd
      (fitsfile *fptr, char *keyname, > char *card, int *status)

4

Get the next keyword whose name matches one of the strings in 'inclist' but does not match any of the strings in 'exclist'. The strings in inclist and exclist may contain wild card characters (*, ?, and #) as described at the beginning of this section. This routine searches from the current header position to the end of the header, only, and does not continue the search from the top of the header back to the original position. The current header position may be reset with the ffgrec routine. Note that nexc may be set = 0 if there are no keywords to be excluded. This routine returns status = KEY_NO_EXIST (202) if a matching keyword is not found.

  int fits_find_nextkey / ffgnxk
      (fitsfile *fptr, char **inclist, int ninc, char **exclist,
       int nexc, > char *card, int  *status)

5

Get the literal keyword value as a character string. Regardless of the datatype of the keyword, this routine simply returns the string of characters in the value field of the keyword along with the comment field. If a NULL comment pointer is given on input, then the comment string will not be returned.

  int fits_read_keyword / ffgkey
      (fitsfile *fptr, char *keyname, > char *value, char *comment,
       int *status)

6

Get a keyword value (with the appropriate datatype) and comment from the CHU. The datatype parameter specifies the datatype of the keyword value and can have one of the following symbolic constant values: TSTRING, TLOGICAL, TBYTE, TSHORT, TUSHORT, TINT, TLONG, TULONG, TFLOAT, TDOUBLE. If a NULL comment pointer is given on input, then the comment string will not be returned. If the value of the keyword is not defined (i.e., the value field is blank) then an error status = VALUE_UNDEFINED (204) will be returned and the input value will not be changed.

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

7

Get a keyword value (with the appropriate datatype) and comment from the CHU. If a NULL comment pointer is given on input, then the comment string will not be returned. If the value of the keyword is not defined (i.e., the value field is blank) then an error status = VALUE_UNDEFINED (204) will be returned and the input value will not be changed.

  int fits_read_key_str / ffgkys
      (fitsfile *fptr, char *keyname, > char *value, char *comment,
       int *status);

  NOTE: after calling the following routine, programs must explicitly free
        the memory allocated for 'longstr' after it is no longer needed.

  int fits_read_key_longstr / ffgkls
      (fitsfile *fptr, char *keyname, > char **longstr, char *comment,
             int *status)

  int fits_read_key_[log, lng, flt, dbl] / ffgky[ljed]
      (fitsfile *fptr, char *keyname, > DTYPE *numval, char *comment,
       int *status)

8

Get a sequence of indexed keyword values. If the value of any of the keywords is not defined (i.e., the value field is blank) then an error status = VALUE_UNDEFINED (204) will be returned and the input value for the undefined keyword(s) will not be changed.

  int fits_read_keys_str / ffgkns
      (fitsfile *fptr, char *keyname, int nstart, int nkeys,
       > char **value, int *nfound,  int *status)

  int fits_read_keys_[log, lng, flt, dbl] / ffgkn[ljed]
      (fitsfile *fptr, char *keyname, int nstart, int nkeys,
       > DTYPE *numval, int *nfound, int *status)

9

Get the value of a floating point keyword, returning the integer and fractional parts of the value in separate routine arguments. This routine may be used to read any keyword but is especially useful for reading the 'triple precision' keywords written by ffpkyt.

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

10

Get the physical units string in 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. A null string is returned if no units are defined for the keyword.

  VELOCITY=                 12.3 / [km/s] orbital speed

  int fits_read_key_unit / ffgunt
      (fitsfile *fptr, char *keyname, > char *unit, int *status)