While a FitsChan is active, it represents a buffer which may
contain zero or more 80-character "header cards" conforming to
FITS conventions. Any sequence of FITS-conforming header cards
may be stored, apart from the "END" card whose existence is
merely implied. The cards may be accessed in any order by using
the FitsChan's integer Card attribute, which identifies a "current"
card, to which subsequent operations apply. Searches
based on keyword may be performed (using astFindFits), new
cards may be inserted (astPutFits, astPutCards, astSetFitsX
) and
existing ones may be deleted (astDelFits), extracted (astGetFits
X
),
or changed (astSetFits
X
).
When you create a FitsChan, you have the option of specifying "source" and "sink" functions which connect it to external data stores by reading and writing FITS header cards. If you provide a source function, it is used to fill the FitsChan with header cards when it is accessed for the first time. If you do not provide a source function, the FitsChan remains empty until you explicitly enter data into it (e.g. using astPutFits, astPutCards or astWrite). If you provide a sink function, it is used to deliver any remaining contents of a FitsChan to an external data store when the FitsChan is deleted. If you do not provide a sink function, any header cards remaining when the FitsChan is deleted will be lost, so you should arrange to extract them first if necessary (e.g. using astFindFits or astRead).
Coordinate system information may be described using FITS header cards using several different conventions, termed "encodings". When an AST Object is written to (or read from) a FitsChan, the value of the FitsChan's Encoding attribute determines how the Object is converted to (or from) a description involving FITS header cards. In general, different encodings will result in different sets of header cards to describe the same Object. Examples of encodings include the DSS encoding (based on conventions used by the STScI Digitised Sky Survey data), the FITS-WCS encoding (based on a proposed FITS standard) and the NATIVE encoding (a near loss-less way of storing AST Objects in FITS headers).
The available encodings differ in the range of Objects they can represent, in the number of Object descriptions that can coexist in the same FitsChan, and in their accessibility to other (external) astronomy applications (see the Encoding attribute for details). Encodings are not necessarily mutually exclusive and it may sometimes be possible to describe the same Object in several ways within a particular set of FITS header cards by using several different encodings.
The detailed behaviour of astRead and astWrite, when used with a FitsChan, depends on the encoding in use. In general, however, all successful use of astRead is destructive, so that FITS header cards are consumed in the process of reading an Object, and are removed from the FitsChan (this deletion can be prevented for specific cards by calling the astRetainFits function). An unsuccessful call of astRead (for instance, caused by the FitsChan not containing the necessary FITS headers cards needed to create an Object) results in the contents of the FitsChan being left unchanged.
If the encoding in use allows only a single Object description to be stored in a FitsChan (e.g. the DSS, FITS-WCS and FITS-IRAF encodings), then write operations using astWrite will over-write any existing Object description using that encoding. Otherwise (e.g. the NATIVE encoding), multiple Object descriptions are written sequentially and may later be read back in the same sequence.
FitsChan also has the following attributes:
AST A Library for Handling World Coordinate Systems in Astronomy