KPG1_RDCAT

Reads a set of positions with labels from a CAT catalogue

Description:

This routine is equivalent to KPG1_RDTAB except that the values of an arbitrary set of columns (including character-valued columns) can be returned within an AST KeyMap (see KEYMAP).

See KPG1_RDTAB for further information.

Invocation

CALL KPG1_RDCAT( PARAM, CURFRM, KEYMAP, LABS, 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.
KEYMAP = INTEGER (Given)
An AST pointer to an existing KeyMap, or AST__NULL. If a KeyMap is supplied, it should contain a vector valued entry called " COLNAMES" containing the names of one or more catalogue columns to be returned in the KeyMap. On exit, the KeyMap will contain the column values within a set of scalar entries. Each such entry will have a key of the form " <colname >_ <row number >" (" _1" for the first row). An error will be reported if the catalogue does not contain the requested columns.
LABS = INTEGER (Given and Returned)
A GRP identifier for a group containing the values in the LABEL column. If the catalogue contains a LABEL column, then its values are appended to the end of the supplied group. If LABS holds GRP__NOID on entry, then a new GRP group is created and its identifier returned in LABS, but only if the catalogue contains a LABEL column (otherwise the supplied value of GRP__NOID is retained on exit).
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.