fitshdr.h File Reference

#include "wcsconfig.h"

Go to the source code of this file.

Data Structures
struct	fitskeyid
	Keyword indexing. More...
struct	fitskey
	Keyword/value information. More...

Macros
#define	FITSHDR_KEYWORD   0x01
	Flag bit indicating illegal keyword syntax. More...
#define	FITSHDR_KEYVALUE   0x02
	Flag bit indicating illegal keyvalue syntax. More...
#define	FITSHDR_COMMENT   0x04
	Flag bit indicating illegal keycomment syntax. More...
#define	FITSHDR_KEYREC   0x08
	Flag bit indicating illegal keyrecord. More...
#define	FITSHDR_CARD   0x08 /* Alias for backwards compatibility. */
	Deprecated. More...
#define	FITSHDR_TRAILER   0x10
	Flag bit indicating keyrecord following a valid END keyrecord. More...
#define	KEYIDLEN   (sizeof(struct fitskeyid)/sizeof(int))
#define	KEYLEN   (sizeof(struct fitskey)/sizeof(int))

Typedefs
typedef int	int64[3]
	64-bit signed integer data type. More...

Functions
int	fitshdr (const char header[], int nkeyrec, int nkeyids, struct fitskeyid keyids[], int *nreject, struct fitskey **keys)
	FITS header parser routine. More...

Variables
const char *	fitshdr_errmsg []
	Status return messages. More...

Detailed Description

The Flexible Image Transport System (FITS), is a data format widely used in astronomy for data interchange and archive. It is described in

"Definition of the Flexible Image Transport System (FITS), version 3.0",
Pence, W.D., Chiappetti, L., Page, C.G., Shaw, R.A., & Stobie, E. 2010,
A&A, 524, A42 - http://dx.doi.org/10.1051/0004-6361/201015362

See also http:
fitshdr() is a generic FITS header parser provided to handle keyrecords that are ignored by the WCS header parsers, wcspih() and wcsbth(). Typically the latter may be set to remove WCS keyrecords from a header leaving fitshdr() to handle the remainder.

Macro Definition Documentation

#define FITSHDR_KEYWORD   0x01

Bit mask for the status flag bit-vector returned by fitshdr() indicating illegal keyword syntax.

#define FITSHDR_KEYVALUE   0x02

Bit mask for the status flag bit-vector returned by fitshdr() indicating illegal keyvalue syntax.

#define FITSHDR_COMMENT   0x04

Bit mask for the status flag bit-vector returned by fitshdr() indicating illegal keycomment syntax.

#define FITSHDR_KEYREC   0x08

Bit mask for the status flag bit-vector returned by fitshdr() indicating an illegal keyrecord, e.g. an END keyrecord with trailing text.

#define FITSHDR_CARD   0x08 /* Alias for backwards compatibility. */

Deprecated:

Added for backwards compatibility, use FITSHDR_KEYREC instead.

#define FITSHDR_TRAILER   0x10

Bit mask for the status flag bit-vector returned by fitshdr() indicating a keyrecord following a valid END keyrecord.

#define KEYIDLEN   (sizeof(struct fitskeyid)/sizeof(int))

#define KEYLEN   (sizeof(struct fitskey)/sizeof(int))

Typedef Documentation

int64

64-bit signed integer data type defined via preprocessor macro WCSLIB_INT64 which may be defined in wcsconfig.h. For example

#define WCSLIB_INT64 long long int

This is typedef'd in fitshdr.h as

#ifdef WCSLIB_INT64
  typedef WCSLIB_INT64 int64;
#else
  typedef int int64[3];
#endif

See fitskey::type.

Function Documentation

int fitshdr	(	const char	header[],
		int	nkeyrec,
		int	nkeyids,
		struct fitskeyid	keyids[],
		int *	nreject,
		struct fitskey **	keys
	)

fitshdr() parses a character array containing a FITS header, extracting all keywords and their values into an array of fitskey structs.

Parameters

[in]	header	Character array containing the (entire) FITS header, for example, as might be obtained conveniently via the CFITSIO routine fits_hdr2str(). Each header "keyrecord" (formerly "card image") consists of exactly 80 7-bit ASCII printing characters in the range 0x20 to 0x7e (which excludes NUL, BS, TAB, LF, FF and CR) especially noting that the keyrecords are NOT null-terminated.
[in]	nkeyrec	Number of keyrecords in header[].
[in]	nkeyids	Number of entries in keyids[].
[in,out]	keyids	While all keywords are extracted from the header, keyids[] provides a convienient way of indexing them. The fitskeyid struct contains three members; fitskeyid::name must be set by the user while fitskeyid::count and fitskeyid::idx are returned by fitshdr(). All matched keywords will have their fitskey::keyno member negated.
[out]	nreject	Number of header keyrecords rejected for syntax errors.
[out]	keys	Pointer to an array of nkeyrec fitskey structs containing all keywords and keyvalues extracted from the header. Memory for the array is allocated by fitshdr() and this must be freed by the user by invoking free() on the array.

Returns

Status return value:

• 0: Success.
• 1: Null fitskey pointer passed.
• 2: Memory allocation failed.
• 3: Fatal error returned by Flex parser.

Notes:

1. Keyword parsing is done in accordance with the syntax defined by NOST 100-2.0, noting the following points in particular:

   1. Sect. 5.1.2.1 specifies that keywords be left-justified in columns 1-8, blank-filled with no embedded spaces, composed only of the ASCII characters ABCDEFGHJKLMNOPQRSTUVWXYZ0123456789-_

      fitshdr() accepts any characters in columns 1-8 but flags keywords that do not conform to standard syntax.

   2. Sect. 5.1.2.2 defines the "value indicator" as the characters ''= '' occurring in columns 9 and 10. If these are absent then the keyword has no value and columns 9-80 may contain any ASCII text (but see note 2 for CONTINUE keyrecords). This is copied to the comment member of the fitskey struct.

   3. Sect. 5.1.2.3 states that a keyword may have a null (undefined) value if the value/comment field, columns 11-80, consists entirely of spaces, possibly followed by a comment.

   4. Sect. 5.1.1 states that trailing blanks in a string keyvalue are not significant and the parser always removes them. A string containing nothing but blanks will be replaced with a single blank.

      Sect. 5.2.1 also states that a quote character (') in a string value is to be represented by two successive quote characters and the parser removes the repeated quote.

   5. The parser recognizes free-format character (NOST 100-2.0, Sect. 5.2.1), integer (Sect. 5.2.3), and floating-point values (Sect. 5.2.4) for all keywords.

   6. Sect. 5.2.3 offers no comment on the size of an integer keyvalue except indirectly in limiting it to 70 digits. The parser will translate an integer keyvalue to a 32-bit signed integer if it lies in the range -2147483648 to +2147483647, otherwise it interprets it as a 64-bit signed integer if possible, or else a "very long" integer (see fitskey::type).

   7. END not followed by 77 blanks is not considered to be a legitimate end keyrecord.

2. The parser supports a generalization of the OGIP Long String Keyvalue Convention (v1.0) whereby strings may be continued onto successive header keyrecords. A keyrecord contains a segment of a continued string if and only if

   1. it contains the pseudo-keyword CONTINUE,

   2. columns 9 and 10 are both blank,

   3. columns 11 to 80 contain what would be considered a valid string keyvalue, including optional keycomment, if column 9 had contained '=',

   4. the previous keyrecord contained either a valid string keyvalue or a valid CONTINUE keyrecord.

   If any of these conditions is violated, the keyrecord is considered in isolation.

   Syntax errors in keycomments in a continued string are treated more permissively than usual; the '/' delimiter may be omitted provided that parsing of the string keyvalue is not compromised. However, the FITSHDR_COMMENT status bit will be set for the keyrecord (see fitskey::status).

   As for normal strings, trailing blanks in a continued string are not significant.

   In the OGIP convention "the '&' character is used as the last non-blank character of the string to indicate that the string is (probably) continued on the following keyword". This additional syntax is not required by fitshdr(), but if '&' does occur as the last non-blank character of a continued string keyvalue then it will be removed, along with any trailing blanks. However, blanks that occur before the '&' will be preserved.

Variable Documentation

const char * fitshdr_errmsg[]

Error messages to match the status value returned from each function.