next up previous
Next: Source and Sink Routines for FitsChans
Up: Storing AST Objects in FITS Headers (FitsChans)
Previous: Mixing Native Objects with Other FITS Cards

Finding and Changing Cards in a FitsChan  

You can search for, and retrieve, particular cards in a FitsChan by keyword, using the function AST_FINDFITS. This performs a search, starting at the current card, until it finds a card whose keyword matches the template you supply, or the end-of-file is reached.

If a suitable card is found, AST_FINDFITS returns the card's contents and then sets the FitsChan's Card attribute either to identify the card found, or the one following it. The way you want the Card attribute to be set is indicated by the fourth (logical) argument to AST_FINDFITS. A value of .TRUE. is returned to indicate success. If a suitable card cannot be found, AST_FINDFITS returns a value of .FALSE. to indicate failure and sets the FitsChan's Card attribute to the end-of-file.

Requesting that the Card attribute be set to indicate the card that AST_FINDFITS finds is useful if you want to replace that card with a new one, as in this example:

      CHARACTER * ( 80 ) NEWCARD
      LOGICAL JUNK

      ...

      JUNK = AST_FINDFITS( FITSCHAN, 'AIRMASS', CARD, .FALSE., STATUS )
      CALL AST_PUTFITS( FITSCHAN, NEWCARD, .TRUE., STATUS )

Here, AST_FINDFITS is used to search for a card with the keyword AIRMASS. If the card is found, AST_PUTFITS then overwrites it with a new card. Otherwise, the Card attribute ends up pointing at the end-of-file and the new card is simply appended to the end of the FitsChan.

A similar approach can be used to delete selected cards from a FitsChan using AST_DELFITS, which deletes the current card:

      IF ( AST_FINDFITS( FITSCHAN, 'BSCALE', CARD, .FALSE., STATUS ) ) THEN
         CALL AST_DELFITS( FITSCHAN, STATUS )
      END IF

This deletes the first card, if any, with the BSCALE keyword.

Requesting that AST_FINDFITS increments the Card attribute to identify the card following the one found is more useful when writing loops. For example, the following loop extracts each card whose keyword matches the template ``CD%6d'' (that is, ``CD'' followed by six decimal digits):

 4    CONTINUE
      IF ( AST_FINDFITS( FITSCHAN, 'CD%6d', CARD, .TRUE., STATUS ) ) THEN
         <process the card's contents>
         GO TO 4
      END IF

For further details of keyword templates, see the description of AST_FINDFITS in [*].



next up previous
Next: Source and Sink Routines for FitsChans
Up: Storing AST Objects in FITS Headers (FitsChans)
Previous: Mixing Native Objects with Other FITS Cards

AST A Library for Handling World Coordinate Systems in Astronomy
Starlink User Note 210
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