next up previous 264
Next: AST_FITSTABLE - Create a FitsTable
Up: AST Routine Descriptions
Previous: AST_FINDFRAME - Find a coordinate system with specified characteristics


AST_FITSCHAN - Create a FitsChan

Description:
This function creates a new FitsChan and optionally initialises its attributes.

A FitsChan is a specialised form of Channel which supports I/O operations involving the use of FITS (Flexible Image Transport System) header cards. Writing an Object to a FitsChan (using AST_WRITE) will, if the Object is suitable, generate a description of that Object composed of FITS header cards, and reading from a FitsChan will create a new Object from its FITS header card description.

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 AST_FINDFITS), new cards may be inserted (AST_PUTFITS, AST_PUTCARDS, AST_SETFITS$<$X$>$) and existing ones may be deleted (AST_DELFITS) or changed (AST_SETFITS$<$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 AST_PUTCARDS, AST_PUTFITS or AST_WRITE). 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 AST_FINDFITS or AST_READ).

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 AST_READ and AST_WRITE, when used with a FitsChan, depends on the encoding in use. In general, however, all use of AST_READ 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 AST_RETAINFITS routine).

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 AST_WRITE 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.

Invocation:
RESULT = AST_FITSCHAN( SOURCE, SINK, OPTIONS, STATUS )
Arguments:
SOURCE = FUNCTION (Given)
A source routine, which is a function taking two arguments: a character argument of length 80 to contain a FITS card, and an integer error status argument. It should return an integer value. This function will be used by the FitsChan to obtain input FITS header cards. On each invocation, it should read the next input card from some external source (such as a FITS file), and return the contents of the card via its character argument. It should return a function result of one unless there are no more cards to be read, in which case it should return zero. If an error occurs, it should set its error status argument to an error value before returning.

If the null routine AST_NULL is supplied as the SOURCE value, the FitsChan will remain empty until cards are explicitly stored in it (e.g. using AST_PUTCARDS or AST_PUTFITS).

SINK = SUBROUTINE (Given)
A sink routine, which is a subroutine which takes two arguments: a character argument of length 80 to contain a FITS card, and an integer error status argument. This routine will be used by the FitsChan to deliver any FITS header cards it contains when it is finally deleted. On each invocation, it should deliver the contents of the character string passed to it as a FITS header card to some external data store (such as a FITS file). If an error occurs, it should set its error status argument to an error value before returning.

If the null routine AST_NULL is supplied as the SINK value, the contents of the FitsChan will not be written out when it is deleted.

OPTIONS = CHARACTER $*$ ( $*$ ) (Given)
A character string containing an optional comma-separated list of attribute assignments to be used for initialising the new FitsChan. The syntax used is identical to that for the AST_SET routine.
STATUS = INTEGER (Given and Returned)
The global status.
Returned Value:
AST_FITSCHAN = INTEGER
A pointer to the new FitsChan.
Notes:
  • The names of the routines supplied for the SOURCE and SINK arguments should appear in EXTERNAL statements in the Fortran routine which invokes AST_FITSCHAN. However, this is not generally necessary for the null routine AST_NULL (so long as the AST_PAR include file has been used).

  • No FITS "END" card will be written via the sink routine. You should add this card yourself after the FitsChan has been deleted.

  • A null Object pointer (AST__NULL) will be returned if this function is invoked with the AST error status set, or if it should fail for any reason.

  • Note that the null routine AST_NULL (one underscore) is different to AST__NULL (two underscores), which is the null Object pointer.
Status Handling
The protected interface to this function includes an extra parameter at the end of the parameter list descirbed above. This parameter is a pointer to the integer inherited status variable: "int $*$status".


next up previous 264
Next: AST_FITSTABLE - Create a FitsTable
Up: AST Routine Descriptions
Previous: AST_FINDFRAME - Find a coordinate system with specified characteristics

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

Copyright (C) 2009 Science \& Technology Facilities Council