KPG1_ASFRM

Sets the current Frame in a FrameSet to a Frame specified through the environment

Description:

This routine allows the user to specify a new Current Frame for a FrameSet using an environment parameter.

Invocation

CALL KPG1_ASFRM( PARAM, EPARAM, IWCS, WCDOM, DCDOM, PROMPT, TOKEN, STATUS )

Arguments

PARAM = CHARACTER ∗ ( ∗ ) (Given)
Name of parameter to use to get Frame description.
EPARAM = CHARACTER ∗ ( ∗ ) (Given)
Name of parameter to use to get Epoch value (if needed).
IWCS = INTEGER (Given)
An AST pointer to the FrameSet.
WCDOM = CHARACTER ∗ ( ∗ ) (Given)
The Domain name to use if the user requests " WORLD" co-ordinates. No translation of WORLD takes place if a blank value is supplied.
DCDOM = CHARACTER ∗ ( ∗ ) (Given)
The Domain name to use if the user requests " DATA" co-ordinates. No translation of DATA takes place if a blank value is supplied.
PROMPT = LOGICAL (Given)
An error is always reported if the requested Frame is not available in the FrameSet. PROMPT controls what happens after the error has been reported. If .TRUE., then the error is flushed, the parameter is cancelled, and the user is re-prompted for a new %PARAM value. Otherwise, the error is retained, and the routine exits with STATUS set to SAI__ERROR.
TOKEN = CHARACTER ∗ ( ∗ ) (Given)
A string containing an MSG message token reference (e.g. " ^FRED" ). The value of the token is used within error messages and should describe the object (NDF, catalogue, etc.) from which the supplied FrameSet is derived. If the token reference string is blank it is ignored.
STATUS = INTEGER (Given and Returned)
The global status.

Notes:

Environment Parameters :

%PARAM = LITERAL (Read)
A string specifying the new co-ordinate Frame. If a null parameter value is supplied, then the error is annulled and the current Frame is left unchanged. The string can be one of the following:

  • A Domain name such as SKY, AXIS, PIXEL, etc. The two " pseudo-domains" WORLD and DATA may be supplied and will be translated into the values supplied for arguments WCDOM and DCDOM respectively, so long as the FrameSet does not contain Frames with Domains WORLD or DATA.

  • An integer value giving the index of the required Frame within the WCS component.

  • An IRAS90 Sky Co-ordinate System (SCS) values such as EQUAT(J2000) (see SUN/163).

%EPARAM = _DOUBLE (Read)
If a celestial co-ordinate system is supplied (using parameter %PARAM) then an epoch value is needed to qualify it. This is the epoch at which the supplied sky positions were determined. It should be given as a decimal years value, with or without decimal places (" 1996.8" for example). Such values are interpreted as a Besselian epoch if less than 1984.0 and as a Julian epoch otherwise.