AST_TABLESOURCE

Register a source routine for accessing tables in FITS files

Description:

This routine can be used to register a call-back routine with a FitsChan. The registered routine is called when-ever the FitsChan needs to read information from a binary table contained within a FITS file. This occurs if the AST_READ function is invoked to read a FrameSet from a set of FITS headers that use the " -TAB" algorithm to describe one or more axes. Such axes use a FITS binary table to store a look-up table of axis values. The FitsChan will fail to read such axes unless the " TabOK" attribute is set to a non-zero positive integer value. The table containing the axis values must be made available to the FitsChan either by storing the table contents in the FitsChan (using AST_PUTTABLES or AST_PUTTABLE) prior to invoking AST_READ or by registering a call-back routine using AST_TABLESOURCE. The first method is possibly simpler, but requires that the name of the extension containing the table be known in advance. Since the table name is embedded in the FITS headers, the name is often not known in advance. If a call-back is registered, the FitsChan will determine the name of the required table and invoke the call-back routine to supply the table at the point where it is needed (i.e. within the AST_READ method).

Invocation

CALL AST_TABLESOURCE( THIS, TABSOURCE, STATUS )

Arguments

THIS = INTEGER (Given)
Pointer to the FitsChan.
TABSOURCE = SUBROUTINE (Given)
The table source routine to use. It takes five arguments - the first is a pointer to the FitsChan, the second is a string holding the name of the FITS extension containing the required binary table (" EXTNAME" ), the third is the integer FITS " EXTVER" header value for the required extension, the fourth is the integer FITS " EXTLEVEL" header value for the required extension, and the fifth is the usual inherited status value.

The call-back should read the entire contents (header and data) of the binary table in the named extension of the external FITS file, storing the contents in a newly created FitsTable object. It should then store this FitsTable in the FitsChan using the AST_PUTTABLES or AST_PUTTABLE method, and finally annull its local copy of the FitsTable pointer. If the table cannot be read for any reason, or if any other error occurs, it should return a non-zero integer for the final (third) argument (otherwise zero should be returned).

If TABSOURCE is AST_NULL, any registered call-back function will be removed.

STATUS = INTEGER (Given and Returned)
The global status.

Notes: