NAME

ftchecksum -- Verify or update the checksum keywords in a FITS file or a list of FITS files.

USAGE

ftchecksum filename
or
ftchecksum @filelist

DESCRIPTION

This task verifies or updates the CHECKSUM and DATASUM keywords in each HDU of the input FITS file. A list of files can be verified by listing the file names in a text file, one file name per line, and then entering the name of the text file preceded by an '@' character.

The CHECKSUM and DATASUM keywords are used to embed a 32-bit 1's complement checksum into each HDU of the FITS file which can be used to verify the integrity of the file. The CHECKSUM keyword gives an ASCII encoded representation of the complement of the checksum for the entire HDU. A valid CHECKSUM keyword value causes the checksum for the whole HDU to have a value of zero. The DATASUM keyword gives the 32-bit unsigned integer value for the checksum of the data unit alone, stored as an ASCII string. Further details of this checksum algorithm have been published by Rob Seaman in the Astronomical Society of the Pacific Conference Series, Volume 77, "Astronomical Data Analysis Software and Systems IV" and in a revised draft dated June 1995.

This task may be used to either verify the checksums in a file or to update the checksum keyword values if they do not exist or are out of date. If the 'update' parameter has the default value of 'no' then the input file is not modified and the checksums are merely verified; a warning message is issued if the checksum values are not correct, thus indicating that the file has been modified or corrupted since the checksum keywords were originally written.

If an existing FITS file does not contain the checksum keywords or if the keyword values are out of date, then this task may be used to compute the new checksum keyword values by specifying 'update = yes'. If the FITS file already has the correct DATASUM keyword value in each HDU and only the header(s) have been modified then the CHECKSUM keywords can be quickly updated by specifying 'datasum = no'. Specifying 'yes' for this parameter will force the DATASUM keyword to be recomputed (which may take some time for large files) and updated if necessary before recomputing the CHECKSUM keyword value in each HDU.

Note that the ftverify task also checks the values of the checksum keywords if they are present.

PARAMETERS

infile [filename]
Name of the FITS file to be checksummed. A text file containing a list of file names to be processed, one per line, can also be entered by preceding the text file name with the '@' character.

(update = no) [boolean]
Should the checksum keywords be updated if they are no longer correct? By default the checksum keywords are simply verified and a warning message is issued if they are not correct.

(datasum = yes) [boolean]
Should the DATASUM keyword be verified and updated before recomputing the CHECKSUM keyword value? If this parameter is set to 'No', then the DATASUM keyword will be assumed to be correct and will simply be added to the checksum for the header to generate the total checksum for the HDU.

(chatter = 2) [integer, 0 - 5]
Controls the amount of informative text written to standard output. Setting chatter = 1 or higher will produce one line of output per file, indicating whether all the checksum keywords are valid or not. If chatter = 2 or higher then a more detailed listing will also be produced, showing the status of the CHECKSUM and DATASUM keywords in every HDU in the file(s). Setting chatter = 0 will turn off the text output completely.

(allok = yes) [boolean]
This output parameter is set to 'Yes' if all the checksum keywords in all the files that were checked are valid. Otherwise, it is set to 'No' if any of the CHECKSUM or DATASUM keywords are invalid or missing in any of the HDUs. This may be useful in data processing scripts to check if a file or a set of files all have valid checksums.

EXAMPLES

1. Verify the checksum values, without updating the input file.

      ftchecksum  test.fits

2. Verify the checksum keywords in the input file and update the values if the keywords don't exist or have invalid values. Chatter = 0 turns off all the diagnostic output.

      ftchecksum  test.fits  update=yes chatter=0

3. Update the checksum keywords in a list of files contained in the filelist.txt text file.

      ftchecksum  @filelist.txt  update=yes

SEE ALSO

ftverify

fv, the interactive FITS file editor, can also be used to create and verify the checksum keywords FITS HDUs.

LAST MODIFIED

April 2002