The FitsChan Model

I/O between AST Objects and FITS headers is supported by a specialised form of Channel called a FitsChan. 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:

1. You may add cards yourself, one at a time, using astPutFits ().

2. You may add cards yourself, supplying all cards concatenated into a single string, using astPutCards ().

3. You may write an AST Object to the FitsChan (using astWrite), which will have the effect of creating new cards within the FitsChan which describe the Object ().

4. You may assign a value to the SourceFile 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 astSet), the file is opened and the headers copied from it into the FitsChan. The file is then imemdiately closed.

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

There are also four ways of removing cards from a FitsChan:

1. You may delete cards yourself, one at a time, using astDelFits ().

2. You may read an AST Object from the FitsChan (using astRead), which will have the effect of removing those cards from the FitsChan which describe the Object ().

3. You may assign a value to the FitsChan's SinkFile 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.

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

In addition to the above, you may also read individual cards from a FitsChan using the function astFindFits (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 ().