next up previous 264
Next: AST_MAPHASKEY - Check if an entry with a given key exists in a KeyMap
Up: AST Routine Descriptions
Previous: AST_MAPGET1X - Get a vector value from a KeyMap


AST_MAPGETELEM$<$X$>$ - Get a single element of a vector value from a KeyMap

Description:
This is a set of functions for retrieving a single element of a vector value from a KeyMap. You should replace $<$X$>$ in the generic function name AST_MAPGETELEM$<$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_MAPGETELEM$<$X$>$( THIS, KEY, ELEM, 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.
ELEM = INTEGER (Given)
The index of the required vector element, starting at one. An error will be reported if the value is outside the range of the vector.
VALUE = $<$X$>$type (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.
STATUS = INTEGER (Given and Returned)
The global status.
Returned Value:
AST_MAPGETELEM$<$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, or if it has an undefined value, but a .FALSE. value will be returned as the function value.
Data Type Codes
To select the appropriate routine, you should replace $<$X$>$ in the generic routine name AST_MAPGETELEM$<$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_MAPGETELEMD would be used to get a DOUBLE PRECISION value, while AST_MAPGETELEMI would be used to get an INTEGER value, etc.


next up previous 264
Next: AST_MAPHASKEY - Check if an entry with a given key exists in a KeyMap
Up: AST Routine Descriptions
Previous: AST_MAPGET1X - Get a vector 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