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 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 .FALSE. and the Card attribute is set to the " end-of-file" .

RESULT = AST_FINDFITS( THIS, NAME, CARD, INC, STATUS )

THIS = INTEGER (Given)

NAME = CHARACTER $\ast$ ( $\ast$ ) (Given)

CARD = CHARACTER $\ast$ ( 80 ) (Returned)

INC = LOGICAL (Given)

STATUS = INTEGER (Given and Returned)

AST_FINDFITS = LOGICAL

RESULT = AST_FINDFITS( FITSCHAN, ’ %f’ , CARD, .TRUE., STATUS )

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 = AST_FINDFITS( FITSCHAN, ’ BITPIX’ , CARD, .TRUE., STATUS )

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 = AST_FINDFITS( FITSCHAN, ’ COMMENT’ , CARD, .FALSE., STATUS )

Sets the Card attribute of a FitsChan to identify the next COMMENT card (if any) and returns that card.

RESULT = AST_FINDFITS( FITSCHAN, ’ CRVAL%1d’ , CARD, .TRUE., STATUS )

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).

• The search always starts with the current card, as identified by the Card attribute. To ensure you search the entire contents of a FitsChan, you should first clear the Card attribute (using AST_CLEAR). This effectively " rewinds" the FitsChan.

• If a search is unsuccessful, the Card attribute is set to the " end-of-file" (i.e. to one more than the number of cards in the FitsChan). No error occurs.

• A value of .FALSE. will be returned if this function is invoked with the AST error status set, or if it should fail for any reason.

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:

• " c" : matches all upper case letters,

• " d" : matches all decimal digits,

• " f" : matches all characters which are permitted within a FITS keyword (upper case letters, digits, underscores and hyphens).

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:

• The template " %f" will match a blank FITS keyword consisting of 8 spaces (as well as matching all other keywords).

• A template consisting of 8 spaces will match a blank keyword (only).

For example:

• The template " BitPix" will match the keyword " BITPIX" only.

• The template " crpix%1d" will match keywords consisting of " CRPIX" followed by one decimal digit.

• The template " P%c" will match any keyword starting with " P" and followed by one or more letters.

• The template " E%0f" will match any keyword beginning with " E" .

• The template " %f" will match any keyword at all (including a blank one).