Next: AST_MAPGETELEMX - Get a single element of a vector value from a KeyMap
Up: AST Routine Descriptions
Previous: AST_MAPGET0X - Get a scalar value from a KeyMap
AST_MAPGET1
X
-
Get a vector value from a KeyMap
- Description:
- This is a set of functions for retrieving a vector value from a KeyMap.
You should replace
X
in the generic function name
AST_MAPGET1
X
by an appropriate 1-character type code (see the "Data Type Codes"
section below for the code appropriate to each supported data type).
The stored value is converted to the data type indiced by
X
before being returned (an error is reported if it is not possible to
convert the stored value to the requested data type).
- Invocation:
- RESULT = AST_MAPGET1
X
( THIS, KEY, MXVAL, NVAL, VALUE, STATUS )
- Arguments:
-
THIS = INTEGER (Given)
-
Pointer to the KeyMap.
-
KEY = CHARACTER
(
) (Given)
-
The character string identifying the value to be retrieved. Trailing
spaces are ignored.
The supplied string is converted to upper case before use if the
KeyCase attribute is currently set to zero.
-
MXVAL = INTEGER (Given)
-
The number of elements in the
VALUE array.
-
NVAL = INTEGER (Returned)
-
The
number of elements stored in the
Any unused elements of the array are left unchanged.
-
VALUE( MXVAL ) =
X
type (Returned)
-
The requested values.
If the requested key is not found, or if it is found but has an
undefined value (see
AST_MAPPUTU),
then the contents of the
buffer on entry to this function will be unchanged on exit.
-
STATUS = INTEGER (Given and Returned)
-
The global status.
- Returned Value:
-
AST_MAPGET1
X
= LOGICAL
-
.TRUE.
is returned if the requested key name was found, and does not have
an undefined value (see
AST_MAPPUTU). .FALSE.
is returned otherwise.
- Notes:
- No error is reported if the requested key cannot be found in the
given KeyMap, but a
.FALSE.
value will be returned as the function value. The supplied array
will be returned unchanged.
- If the stored value is a scalar value, then the value will be
returned in the first element of the supplied array, and
NVAL
will be returned set to 1.
-
Data Type Codes
- To select the appropriate
routine, you should replace
X
in the generic routine name AST_MAPGET1
X
with a 1-character data type code, so as to match the data type
X
type
of the data you are processing, as follows:
- D: DOUBLE PRECISION
- R: REAL
- I: INTEGER
- C: CHARACTER
- A: INTEGER used to identify an AstObject
- S: INTEGER
2 (short integer)
- B: Unsigned byte
For example, AST_MAPGET1D would be used to get DOUBLE PRECISION values,
while AST_MAPGET1I would be used to get INTEGER values, etc.
Next: AST_MAPGETELEMX - Get a single element of a vector value from a KeyMap
Up: AST Routine Descriptions
Previous: AST_MAPGET0X - Get a scalar value from a KeyMap
AST A Library for Handling World Coordinate Systems in Astronomy
Starlink User Note 210
R.F. Warren-Smith & D.S. Berry
24th May 2011
E-mail:ussc@star.rl.ac.uk
Copyright (C) 2009 Science \& Technology Facilities Council