next up previous 264
Next: astGetFrame - Obtain a pointer to a specified Frame in a FrameSet
Up: AST Function Descriptions
Previous: astGetColumnData - Retrieve all the data values stored in a column


astGetFits$<$X$>$ - Get a named keyword value from a FitsChan

Description:
This is a family of functions which gets a value for a named keyword from a FitsChan using one of several different data types. The data type of the returned value is selected by replacing $<$X$>$ in the function name by one of the following strings representing the recognised FITS

data types:

The data type of the returned value is selected by replacing $<$X$>$ in the function name by one of the following strings representing the

recognised FITS data types:

  • CF - Complex floating point values.

  • CI - Complex integer values.

  • F - Floating point values.

  • I - Integer values.

  • L - Logical (i.e. boolean) values.

  • S - String values.

  • CN - A "CONTINUE" value, these are treated like string values, but are encoded without an equals sign.

The data type of the "value" parameter

depends on $<$X$>$ as follows:

  • CF - "double $*$" (a pointer to a 2 element array to hold the real and imaginary parts of the complex value).

  • CI - "int $*$" (a pointer to a 2 element array to hold the real and imaginary parts of the complex value).

  • F - "double $*$".

  • I - "int $*$".

  • L - "int $*$".

  • S - "char $*$$*$" (a pointer to a static "char" array is returned at the location given by the "value" parameter, Note, the stored string may change on subsequent invocations of astGetFitsS so a permanent copy should be taken of the string if necessary).

  • CN - Like"S".
Synopsis:
int astGetFits$<$X$>$( AstFitsChan $*$this, const char $*$name, $<$X$>$type $*$value )
Parameters:
this
Pointer to the FitsChan.
name
Pointer to a null-terminated character string containing the FITS keyword name. This may be a complete FITS header card, in which case the keyword to use is extracted from it. No more than 80 characters are read from this string.
value
A pointer to a buffer to receive the keyword value. The data type depends on $<$X$>$ as described above. The conents of the buffer on entry are left unchanged if the keyword is not found.
Returned Value:
astGetFits$<$X$>$$<$X$>$()
A value of zero is returned if the keyword was not found in the FitsChan (no error is reported). Otherwise, a value of one is returned.
Notes:
  • The card following the current card is checked first. If this is not the required card, then the rest of the FitsChan is searched, starting with the first card added to the FitsChan. Therefore cards should be accessed in the order they are stored in the FitsChan (if possible) as this will minimise the time spent searching for cards.

  • If the requested card is found, it becomes the current card, otherwise the current card is left pointing at the "end-of-file".

  • If the stored keyword value is not of the requested type, it is converted into the requested type.

  • If the keyword is found in the FitsChan, but has no associated value, an error is reported. If necessary, the astTestFits function can be used to determine if the keyword has a defined value in the FitsChan prior to calling this function.

  • An error will be reported if the keyword name does not conform to FITS requirements.

  • Zero

  • .FALSE. is returned as the function value if an error has already occurred, or if this function should fail for any reason.

  • The FITS standard says that string keyword values should be padded with trailing spaces if they are shorter than 8 characters. For this reason, trailing spaces are removed from the string returned by astGetFitsS if the original string (including any trailing spaces) contains 8 or fewer characters. Trailing spaces are not removed from longer strings.


next up previous 264
Next: astGetFrame - Obtain a pointer to a specified Frame in a FrameSet
Up: AST Function Descriptions
Previous: astGetColumnData - Retrieve all the data values stored in a column

AST A Library for Handling World Coordinate Systems in Astronomy
Starlink User Note 211
R.F. Warren-Smith & D.S. Berry
24th May 2011
E-mail:ussc@star.rl.ac.uk

Copyright (C) 2009 Science \& Technology Facilities Council