- ←Prev
- AST
A Library for Handling
World Coordinate Systems
in Astronomy - Next→
- TOC ↑
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:
Copyright (C) 2021 East Asian Observatory
- ←Prev
- AST
A Library for Handling
World Coordinate
Systems
in Astronomy - Next→
- TOC ↑