.help fdiff Sep98 ftools.futils
.ih
NAME
fdiff -- display differences between pairs of fits file.
.ih
USAGE
fdiff fitsfile1 fitsfile2 
.ih
DESCRIPTION
This task compares details of the headers of the two fitsfile. 
It also can tell whether the Data units are the same or not by examining 
the datasums, and optionally, testing datum-by-datum.    

If extension names/numbers are not given for both files, the
program will compare all the HDUs.
If extension name/number is given in one of the file but not
the other, the program will only test the specified HDU of the two  
files with the same hdu number.   

Headers are compared keyword by keyword. The commentary keywords
(HISTORY, COMMENT, and keywords with a blank name), "CHECKSUM" and 
"DATE" keywords are not considered. 
Users can also exclude additional keywords by supplying a list as the 
value of the "exclude" parameter.  This list can  be either a string which  
consists of the keywords separated by  commas, or a filename of 
an ASCII file preceded with an @.  For the ASCII list file, each keyword  
will occupy one line. If the pattern is followed by *, 
keywords which matched that pattern from beginning will be excluded.  
For example, the DATE means DATE but not "DATE-OBS". 
The "DATE*" means all the keywords  "DATE", "DATE-OBS" and other DATExxxx 
but not "TSTDATE".

Users can  choose whether to compare the numerical keywords as 
numerical values by setting the cmpnum parameter. If the cmpnum 
parameter is not set, they will be compared as strings. For 
example, if cmpnum is not set,  the program will think the 1.0E2 and 
100 are the  different values in spite of the same numerical values. 

Numerical  quantities  are  flagged as different when their arithmetic
difference  exceeds  a  certain  threshold.  Users  can supply both an
absolute  and  relative  threshold  using the "tolerance" and "reltol"
parameters.  For  quantities  x1  and  x2 from file1 and file2, values
which satisfy this expression:

   |x1 - x2| > tolerance + |x1|*reltol

are   considered   to  be  different.  A  relative  tolerance  may  be
appropriate if there is a large dynamic range in values. By using both
an  absolute  and relative tolerance, users can also guard against the
case  when x1 is near zero. The default tolerances are '0', indicating
that an exact match is required.

For the data units, the datasums are examined. The default 
datasum value is the value of DATASUM keyword. If it does not 
exist, the users can choose whether they want to calculate 
the datasum by setting the caldsum parameter. If it is 
set, the datasum will be calculated and used for comparison.

If the cmpdata parameter is set, the details of data in image arrays 
and tables are also compared. 


.ih
PARAMETERS
.ls file1 [string]
File name of the the first fitsfile. 
.le
.ls file2 [string]
File name of the the second fitsfile. 
.le
.ls (exclude = "") [string]
The list of excluded keywords.  
.le
.ls (cmpnum = yes)  [boolean]
For the numerical keywords, should we compare them as numerical values? 
.le
.ls (tolerance = 0.) [double]
Numerical  tolerance.  If  the  values in the 2 files differ by
this  amount  or  less then they will be considered to have the
same value.
.le
.ls (reltol = 0.) [double]
Relative  numerical  tolerance.  If  the  values in the 2 files
differ  fractionally  by  this amount or less then they will be
considered to have the same value.
.le
.ls (caldsum = yes) [boolean]
Should we calculate the datasum if DATASUM keyword does not exist? 
.le
.ls (cmpdata = yes)  [boolean]
Should we compare the data Units (images and tables)?
.le
.ls (hdumaxdiff = 256)  [integer]
Maximum number of differences can allowed in a HDU (including 
keywords and data). If the number of differences in a HDU exceeds 
the hdumaxdiff, a warning message will be printed out, and the 
comparison test will be terminated for this HDU. 
.le
.ls (numdiffs)  [integer]
Returns the total number of found differences.
.le  
.ls (verbose = yes) [boolean]
Write informational message to screen. 
.le
.ih
EXAMPLES
1.   Display the differences between file1 and file2  

	ft> fdiff file1 file2 

2.   Display the differences between file1 and file2 but ignore the
     keywords KEY2, KEY31 and KEY32.

	ft> fdiff file1 file2 exclude="KEY2,KEY3*"

.fi
.ih
BUGS
The current version skips the variable length vector columns.
.ih
SEE ALSO
ftdiff, ftlist, ftchecksum, fv
.endhelp
