1. STScI
2. HST
3. Observatory
4. Reference Data for Calibration and Tools
5. The FITS++ Verify Program

The FITS++ Verify Program

NOTE: This document is a draft.

An Overview of the Verify Program

The Flexible Image Transport System (FITS) is recognized by the International Astronomical Union as a standard for the transfer of astronomical data. The FITS++ verify program verifies FITS file for conformity to the FITS standards.

A summary of the standard can be found in Definition of the Flexible Image Transport System (FITS), March 29, 1999, NOST 100-2.0, NASA/Science Office of Standards and Technology, Code 633.2, NASA Goddard Space Flight Center, Greenbelt MD 20771, USA. For further information about the FITS standard and related material, see The FITS Support Office at NASA/GSFC.

In general, a FITS file consists of a series of header-data-units. Each of these are header keywords, followed by data that is described by those keywords. The verify program scans all of the keywords in each header-data-unit, looking for conformity to FITS rules and also checking for internal consistency in the size of data blocks. It does not read the data associated with the header-data-unit. Errors are flagged and certain warnings are also issued. If a practice is not followed that the FITS standard strongly recommends, a warning message is issued.

Errors or warnings concerning keywords in the various FITS headers are printed following the banner line announcing the file being verified. The sequence number of the offending header-data-unit (HDU) is printed. followed by the full text of the keyword line and the error message.

For example:

	Errors or warnings in header to HDU #0:
	BLOCKED =                    T /Tape may be blocked
	This keyword is deprecated by the FITS standard.
	EPOCH   =      0.000000000E+00 /EPOCH OF RA DEC
	This keyword is deprecated by the FITS standard.

	Errors or warnings in header to HDU #2:
	FREQ    =   0.14524000059347599D+10
	Value does not conform to FITS fixed format

In addition to checking for errors and warnings, the verify program prints a summary of the contents of the FITS file. Included in this summary is the type of HDU, the type of data associated with the HDU, the values of the FITS keywords XTENSION, EXTNAME, EXTVER, as well as the dimensionality of the data, the total size (in bytes and FITS blocks), and the number of lines in the header. The severity of the errors or warning may be evaluated by the line following the summary contents.

For example:

	No problems were encountered.
	WARNINGS were encountered.
	ERRORS were encountered.

If the "No problems were encountered" message is found, there were no errors or warnings of any kind. The "WARNINGS were encountered" message indicates warnings were encountered, but no errors. Obviously, the final message indicates the presence of errors and possibly warnings as well.

One final explanation must be provided. The end of the summary contents of the FITS file contains a message the usually says, "No special records." This message refers to a seldom used, and little known, feature of FITS files. Following the sequence of HDUs, a FITS file may have any number of unstructured blocks of data, so long as each block is 2880 bytes long. These are called "special" records. The message indicates that there are no such "special" records, which is usually the case since they are rarely used. Sometimes, errors are made in a FITS file that makes what is intended to be a legitimate HDU impossible to identify. Under these circumstances, the intended HDU may look like these "special" records. If such a situation is detected, the existence of special records records are reported and a warning message is included at the end of the report:

	Special records exist!  This probably indicates a bad file.

This message should not be ignored; it may indicate a damaged file whose data can be recovered by correcting the values of some erroneous keywords.

Executing the Verify Program

The FITS++ verify program is installed in /usr/local/bin on various clusters in the Unix systems as "fitsverify". To execute the program:

	>fitsverify filename1 filename2 ...

An Example of Output from the Verify Program

The following output is the result of running the verify program on one of the NICMOS reference files.

FITS++ Verification Program Version 1.11
Fri Sep 26 10:00:32 1997
===================================================================
FITS Verification for file:  h4216218n_noi.fits








===================================================================
Summary contents of FITS file: h4216218n_noi.fits

0:  Primary Array ( SHORT )
		0 bytes, 176 header lines, 5 FITS blocks
1:  Image Extension ( FLOAT ) [IMAGE,SCI,1] 2 dims [256,256]
		262144 bytes, 95 header lines, 95 FITS blocks
2:  Image Extension ( FLOAT ) [IMAGE,ERR,1] 2 dims [256,256]
		262144 bytes, 39 header lines, 94 FITS blocks
3:  Image Extension ( SHORT ) [IMAGE,DQ,1] 2 dims [256,256]
		131072 bytes, 39 header lines, 48 FITS blocks
4:  Image Extension ( SHORT ) [IMAGE,SAMP,1]
		0 bytes, 40 header lines, 2 FITS blocks
5:  Image Extension ( FLOAT ) [IMAGE,TIME,1]
		0 bytes, 40 header lines, 2 FITS blocks
No special records.

===================================================================
No problems were encountered.