KPG1_RDLST

Reads a set of positions from a CAT catalogue

Description:

This routine reads a FrameSet, and a set of positions with associated integer identifiers from a CAT catalogue. The FrameSet should be stored as an AST Dump in the textual information associated with the catalogue. Such catalogues can be created using KPG1_WRLST. If the catalogue does not contain a FrameSet, then a default FrameSet will be used if possible. If the catalogue contains floating point columns named RA and DEC, then the default FrameSet contains a single SkyFrame (Epoch and Equinox are set from the EPOCH and EQUINOX catalogue parameters - if they exist). Otherwise, if the catalogue contains floating point columns named X and Y, then the default FrameSet contains a single two-dimensional Frame with axis symbols X and Y, and Domain GRID. If there is also a column named Z, then the Frame will be three-dimensional, with a Z axis.

However the FrameSet is obtained, it is assumed that the columns containing the axis values have CAT names equal to the Symbol attribute of the corresponding AST Axis. The catalogue columns from which to read the axis values are chosen by matching column names with Axis Symbols (only columns containing floating point values are considered). Frames are checked in the following order: the Base Frame, the Current Frame, all other Frames in order of increasing Frame index. An error is reported if no Frame has a set of corresponding columns.

It is assumed that position identifiers are stored in an integer column with name PIDENT. If no such column is found, the returned position identifiers start at 1 and increase monotonically.

The routine KPG1_RDTAB is like KPG1_RDLST, but provides an extra option to return a group of position labels read from a LABEL column in the catalogue.

Invocation

CALL KPG1_RDLST( PARAM, CURFRM, IWCS, NPOS, NAX, IPPOS, IPID, TITLE, NAME, STATUS )

Arguments

PARAM = CHARACTER ∗ ( ∗ ) (Given)
The name of the parameter to use.
CURFRM = LOGICAL (Given)
If .TRUE. the positions read from the catalogue are Mapped into the Current Frame of the associated FrameSet before being returned. Otherwise, they are returned in the Base Frame.
IWCS = INTEGER (Returned)
An AST pointer to the FrameSet read from the catalogue.
NPOS = INTEGER (Returned)
The number of positions returned.
NAX = INTEGER (Returned)
The number of axes in the Frame requested by CURFRM.
IPPOS = INTEGER (Returned)
A pointer to a two-dimensional DOUBLE PRECISION array holding the returned positions. Element (I,J) of this array gives axis J for position I. The first axis will have NPOS elements, and the second will have NAX elements. Should be released using PSX_FREE when no longer needed.
IPID = INTEGER (Returned)
A pointer to a one-dimensional INTEGER array holding the integer identifiers for the returned positions. The array will have NPOS elements. Should be released using PSX_FREE when no longer needed.
TITLE = CHARACTER ∗ ( ∗ ) (Returned)
The value of the TITLE parameter in the supplied catalogue. Returned blank if there is no TITLE parameter.
NAME = CHARACTER ∗ ( ∗ ) (Returned)
The file spec of the catalogue containing the positions list. Not accessed if the declared length is 1.
STATUS = INTEGER (Given and Returned)
The global status.