fitskey Struct Reference

Keyword/value information. More...

#include <fitshdr.h>

Data Fields
int	keyno
int	keyid
int	status
char	keyword [12]
int	type
int	padding
union {
int   i
int64   k
int   l [8]
double   f
double   c [2]
char   s [72]
}	keyvalue
int	ulen
char	comment [84]

Detailed Description

Keyword/value information.

fitshdr() returns an array of fitskey structs, each of which contains the result of parsing one FITS header keyrecord. All members of the fitskey struct are returned by fitshdr(), none are given by the user.

Field Documentation

keyno

int fitskey::keyno

(Returned) Keyrecord number (1-relative) in the array passed as input to fitshdr(). This will be negated if the keyword matched any specified in the keyids[] index.

keyid

int fitskey::keyid

(Returned) Index into the first entry in keyids[] with which the keyrecord matches, else -1.

status

int fitskey::status

(Returned) Status flag bit-vector for the header keyrecord employing the following bit masks defined as preprocessor macros:

• FITSHDR_KEYWORD: Illegal keyword syntax.
• FITSHDR_KEYVALUE: Illegal keyvalue syntax.
• FITSHDR_COMMENT: Illegal keycomment syntax.
• FITSHDR_KEYREC: Illegal keyrecord, e.g. an END keyrecord with trailing text.
• FITSHDR_TRAILER: Keyrecord following a valid END keyrecord.

The header keyrecord is syntactically correct if no bits are set.

keyword

char fitskey::keyword

(Returned) Keyword name, null-filled for keywords of less than eight characters (trailing blanks replaced by nulls).

Use

sprintf(dst, "%.8s", keyword)

to copy it to a character array with null-termination, or

sprintf(dst, "%8.8s", keyword)

to blank-fill to eight characters followed by null-termination.

type

int fitskey::type

(Returned) Keyvalue data type:

• 0: No keyvalue (both the value and type are undefined).
• 1: Logical, represented as int.
• 2: 32-bit signed integer.
• 3: 64-bit signed integer (see below).
• 4: Very long integer (see below).
• 5: Floating point (stored as double).
• 6: Integer complex (stored as double[2]).
• 7: Floating point complex (stored as double[2]).
• 8: String.
• 8+10*n: Continued string (described below and in fitshdr() note 2).

A negative type indicates that a syntax error was encountered when attempting to parse a keyvalue of the particular type.

Comments on particular data types:

• 64-bit signed integers lie in the range

  (-9223372036854775808 <= int64 <  -2147483648) ||
           (+2147483647 <  int64 <= +9223372036854775807)

  A native 64-bit data type may be defined via preprocessor macro WCSLIB_INT64 defined in wcsconfig.h, e.g. as 'long long int'; this will be typedef'd to 'int64' here. If WCSLIB_INT64 is not set, then int64 is typedef'd to int[3] instead and fitskey::keyvalue is to be computed as

  ((keyvalue.k[2]) * 1000000000 +
    keyvalue.k[1]) * 1000000000 +
    keyvalue.k[0]

  and may reported via

  if (keyvalue.k[2]) {
    printf("%d%09d%09d", keyvalue.k[2], abs(keyvalue.k[1]),
                         abs(keyvalue.k[0]));
  } else {
    printf("%d%09d", keyvalue.k[1], abs(keyvalue.k[0]));
  }

  where keyvalue.k[0] and keyvalue.k[1] range from -999999999 to +999999999.

• Very long integers, up to 70 decimal digits in length, are encoded in keyvalue.l as an array of int[8], each of which stores 9 decimal digits. fitskey::keyvalue is to be computed as

  (((((((keyvalue.l[7]) * 1000000000 +
         keyvalue.l[6]) * 1000000000 +
         keyvalue.l[5]) * 1000000000 +
         keyvalue.l[4]) * 1000000000 +
         keyvalue.l[3]) * 1000000000 +
         keyvalue.l[2]) * 1000000000 +
         keyvalue.l[1]) * 1000000000 +
         keyvalue.l[0]

• Continued strings are not reconstructed, they remain split over successive fitskey structs in the keys[] array returned by fitshdr(). fitskey::keyvalue data type, 8 + 10n, indicates the segment number, n, in the continuation.

padding

int fitskey::padding

(An unused variable inserted for alignment purposes only.)

i

int fitskey::i

(Returned) Logical (fitskey::type == 1) and 32-bit signed integer (fitskey::type == 2) data types in the fitskey::keyvalue union.

k

int64 fitskey::k

(Returned) 64-bit signed integer (fitskey::type == 3) data type in the fitskey::keyvalue union.

l

int fitskey::l

(Returned) Very long integer (fitskey::type == 4) data type in the fitskey::keyvalue union.

f

double fitskey::f

(Returned) Floating point (fitskey::type == 5) data type in the fitskey::keyvalue union.

c

double fitskey::c

(Returned) Integer and floating point complex (fitskey::type == 6 || 7) data types in the fitskey::keyvalue union.

s

char fitskey::s

(Returned) Null-terminated string (fitskey::type == 8) data type in the fitskey::keyvalue union.

keyvalue

union fitskey::keyvalue

(Returned) A union comprised of

• fitskey::i,
• fitskey::k,
• fitskey::l,
• fitskey::f,
• fitskey::c,
• fitskey::s,

used by the fitskey struct to contain the value associated with a keyword.

ulen

int fitskey::ulen

(Returned) Where a keycomment contains a units string in the standard form, e.g. [m/s], the ulen member indicates its length, inclusive of square brackets. Otherwise ulen is zero.

comment

char fitskey::comment

(Returned) Keycomment, i.e. comment associated with the keyword or, for keyrecords rejected because of syntax errors, the compete keyrecord itself with null-termination.

Comments are null-terminated with trailing spaces removed. Leading spaces are also removed from keycomments (i.e. those immediately following the '/' character), but not from COMMENT or HISTORY keyrecords or keyrecords without a value indicator (''= '' in columns 9-80).