AST_COLUMNNULL

Get or set the null value for an integer column of a FITS table

Description:

This function allows a null value to be stored with a named integer-valued column in a FitsTable. The supplied null value is assigned to the TNULLn keyword in the FITS header associated with the FitsTable. A value in the named column is then considered to be null if 1) it equals the null value supplied to this function, or 2) no value has yet been stored in the cell.

As well as setting a new null value, this function also returns the previous null value. If no null value has been set previously, a default value will be returned. This default will be an integer value that does not currently occur anywhere within the named column. If no such value can be found, what happens depends on whether the column contains any cells in which no values have yet been stored. If so, an error will be reported. Otherwise (i.e. if there are no null values in the column), an arbitrary value of zero will be returned as the function value, and no TNULLn keyword will be stored in the FITS header.

A flag is returned indicating if the returned null value was set explicitly by a previous call to this function, or is a default value.

A second flag is returned indicating if the named column contains any null values (i.e. values equal to the supplied null value, or cells to which no value has yet been assigned).

Invocation

RESULT = AST_COLUMNNULL( THIS, COLUMN, SET, NEWVAL, WASSET, HASNULL, STATUS )

Arguments

THIS = INTEGER (Given)
Pointer to the FitsTable.
COLUMN = CHARACTER ( ) (Given)
The character string holding the name of the column. Trailing spaces are ignored.
SET = LOGICAL (Given)
If .TRUE., the value supplied for argument NEWVAL will be stored as the current null value, replacing any value set by a previous call to this function. If .FALSE., the value supplied for argument NEWVAL is ignored and the current null value is left unchanged.
NEWVAL = INTEGER (Given)
The new null value to use. Ignored if SET is .FALSE. An error will be reported if the supplied value is outside the range of values that can be stored in the integer data type associated with the column.
WASSET = LOGICAL (Returned)
.TRUE. will be returned if the returned null value was set previously via an earlier invocation of this function. .FALSE. is returned otherwise. If the named column does not exist, or an error occurs, a value of .FALSE. is returned.
HASNULL = LOGICAL (Returned)
.TRUE. will be returned if and only if the named column currently contains any values equal to the null value on exit (i.e. NEWVAL if SET is .TRUE. or the returned function value otherwise), or contains any empty cells. If the named column does not exist, or an error occurs, a value of .FALSE. is returned.
STATUS = INTEGER (Given and Returned)
The global status.

Returned Value

AST_COLUMNNULL = INTEGER
The null value that was in use on entry to this function. If a null value has been set by a previous invocation of this function, it will be returned. Otherwise, if SET is .TRUE., the supplied NEWVAL value is returned. Otherwise, a default value is chosen (if possible) that does not currently occur in the named column. If all available values are in use in the column, an error is reported if and only if the column contains any empty cells. Otherwise, a value of zero is returned. A value of zero is also returned if the named column does not exist, or an error occurs.

Notes: