I/O between AST Objects and FITS headers is supported by a specialised
form of ChannelChannel called a FitsChanFitsChan. A FitsChan contains a buffer which
may hold any number, including zero, of FITS header cards. This buffer
forms a workspace in which you can assemble FITS cards and manipulate
them before writing them out to a file.
By default, when a FitsChan is first created, it contains no cards and
there are five ways of inserting cards into it:
- You may add cards yourself, one at a time, using astPutFitsastPutFits
(§16.8).
- You may add cards yourself, supplying all cards concatenated into a
single string, using astPutCardsastPutCards
(§16.9).
- You may write an AST ObjectObject to the FitsChan (using astWriteastWrite),
which will have the effect of creating new cards within the FitsChan
which describe the Object (§16.5).
- You may assign a value to the SourceFileSourceFile attribute of the FitsChan.
The value should be the path to a text file holding a set of FITS header
cards, one per line. When the SourceFile value is set (using
astSetC or astSetastSet),
the file is opened and the headers copied from it into the FitsChan.
The file is then immediately closed.
- You may specify a source function which reads data from some
external store of FITS cards, just like the source associated with a
basic Channel (§15.13). If you supply a source
function, it will be called when the FitsChan is created in order to
fill it with an initial set of cards (§16.14).
There are also four ways of removing cards from a FitsChan:
- You may delete cards yourself, one at a time, using astDelFitsastDelFits
(§16.13).
- You may read an AST Object from the FitsChan (using astReadastRead),
which will have the effect of removing those cards from the FitsChan
which describe the Object (§16.10).
- You may assign a value to the FitsChan's SinkFileSinkFile attribute. When
the FitsChan is deleted, any remaining headers are written out to a text
file with path equal to the value of the SinkFile attribute.
- Alternatively, you may specify a sink function which writes data to some
external store of FITS cards, just like the sink associated with a
basic Channel (§15.14). If you supply a sink function,
it will be called when the FitsChan is deleted in order to write out
any FITS cards that remain in it (§16.14). Note,
the sink function is not called if the SinkFile attribute has been set.
Note, in particular, that reading an AST Object from a FitsChan is
destructive. That is, it deletes the FITS cards that describe the
Object. The reason for this is explained in
§17.5.
In addition to the above, you may also read individual cards from a
FitsChan using the function astFindFitsastFindFits (which is not
destructive). This is the main means of writing out FITS cards if you
have not supplied a sink function. astFindFits also provides a means
of searching for particular FITS cards (by keyword, for example) and
there are other facilities for overwriting cards when required
(§16.13).