This is a set of functions for retrieving a scalar value from a KeyMap.
You should replace X in the generic function name
AST_MAPGET0X
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).
Note, the version of this function which returns character strings,
AST_MAPGET0C, has an extra parameter in which is returned the number
of characters written into the supplied CHARACTER variable.
Invocation:
RESULT = AST_MAPGET0X( THIS, KEY, VALUE, STATUS )
RESULT = AST_MAPGET0C( THIS, KEY, VALUE, L, 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.
VALUE = Xtype (Returned)
The requested value.
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.
L = INTEGER (Returned)
This parameter is only present in the interface for the AST_MAPGET0C
function. It is returned holding the number of characters
written into the CHARACTER variable supplied for parameter VALUE.
STATUS = INTEGER (Given and Returned)
The global status.
Returned Value:
AST_MAPGET0X = 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 buffer
will be returned unchanged.
If the stored value is a vector value, then the first value in
the vector will be returned.
If the returned value is an AST Object pointer, the Object's reference
count is incremented by this call. Any subsequent changes made to
the Object using the returned pointer will be reflected in any
any other active pointers for the Object. The returned pointer
should be annulled using
AST_ANNUL
when it is no longer needed.
Data Type Codes
To select the appropriate
routine, you should replace X in the generic routine name AST_MAPGET0X
with a 1-character data type code, so as to match the data type Xtype
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: INTEGER2 (short integer)
B: Unsigned byte
For example, AST_MAPGET0D would be used to get a DOUBLE PRECISION value,
while AST_MAPGET0I would be used to get an INTEGER, etc.
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