Find a FITS card in a FitsChan by keyword


This function searches for a card in a FitsChan by keyword. The search commences at the current card (identified by the Card attribute) and ends when a card is found whose FITS keyword matches the template supplied, or when the last card in the FitsChan has been searched.

If the search is successful (i.e. a card is found which matches the template), the contents of the card are (optionally) returned and the Card attribute is adjusted to identify the card found or, if required, the one following it. If the search is not successful, the function returns zero and the Card attribute is set to the " end-of-file" .


int astFindFits( AstFitsChan this, const char name, char card[ 81 ], int inc )


Pointer to the FitsChan.
Pointer to a null-terminated character string containing a template for the keyword to be found. In the simplest case, this should simply be the keyword name (the search is case insensitive and trailing spaces are ignored). However, this template may also contain " field specifiers" which are capable of matching a range of characters (see the " Keyword Templates" section for details). In this case, the first card with a keyword which matches the template will be found. To find the next FITS card regardless of its keyword, you should use the template " %f" .
An array of at least 81 characters (to allow room for a terminating null) in which the FITS card which is found will be returned. If the search is not successful (or a NULL pointer is given), a card will not be returned.
If this value is zero (and the search is successful), the FitsChan s Card attribute will be set to the index of the card that was found. If it is non-zero, however, the Card attribute will be incremented to identify the card which follows the one found.

Returned Value

One if the search was successful, otherwise zero.


result = astFindFits( fitschan, " %f" , card, 1 );
Returns the current card in a FitsChan and advances the Card attribute to identify the card that follows (the " %f" template matches any keyword).
result = astFindFits( fitschan, " BITPIX" , card, 1 );
Searches a FitsChan for a FITS card with the " BITPIX" keyword and returns that card. The Card attribute is then incremented to identify the card that follows it.
result = astFindFits( fitschan, " COMMENT" , NULL, 0 );
Sets the Card attribute of a FitsChan to identify the next COMMENT card (if any). The card itself is not returned.
result = astFindFits( fitschan, " CRVAL%1d" , card, 1 );
Searches a FitsChan for the next card with a keyword of the form " CRVALi" (for example, any of the keywords " CRVAL1" , " CRVAL2" or " CRVAL3" would be matched). The card found (if any) is returned, and the Card attribute is then incremented to identify the following card (ready to search for another keyword with the same form, perhaps).


Keyword Templates

The templates used to match FITS keywords are normally composed of literal characters, which must match the keyword exactly (apart from case). However, a template may also contain " field specifiers" which can match a range of possible characters. This allows you to search for keywords that contain (for example) numbers, where the digits comprising the number are not known in advance.

A field specifier starts with a " %" character. This is followed by an optional single digit (0 to 9) specifying a field width. Finally, there is a single character which specifies the

type of character to be matched, as follows:

If the field width is omitted, the field specifier matches one or more characters. If the field width is zero, it matches zero or more characters. Otherwise, it matches exactly the number of

characters specified. In addition to this:

For example: