next up previous
Next: astFindFrame - Find a coordinate system with specified characteristics
Up: AST Function Descriptions
Previous: astExport - Export an Object pointer to an outer context

   
astFindFits - Find a FITS card in a FitsChan by keyword

Description:
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".

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

Parameters:
this
Pointer to the FitsChan.
name
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".
card
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.
inc
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:
astFindFits()
One if the search was successful, otherwise zero.

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

Notes:
  • 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 astClear). 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 zero will be returned if this function is invoked with the AST error status set, or if it should fail for any reason.

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:

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



next up previous
Next: astFindFrame - Find a coordinate system with specified characteristics
Up: AST Function Descriptions
Previous: astExport - Export an Object pointer to an outer context

AST A Library for Handling World Coordinate Systems in Astronomy
Starlink User Note 211
R.F. Warren-Smith & D.S. Berry
30th April 2003
E-mail:ussc@star.rl.ac.uk

Copyright (C) 2003 Central Laboratory of the Research Councils