[svn-r18266] Purpose:

    bugzilla 1754: h5diff: support comparing through links.
    (original check-in svn revision #18164)
Description:
    fix the hang issue in parallel mode when compare external-link.
    add --no-dangling-links option. 
    add test cases (#450-#459) relate to the new option.
    improve test script to check exit code.
    update --help relate to the new options.
    correct some indentations.

Tested:
    h5committest (jam, amani and linew)

1 files changed, 67 insertions, 32 deletions

diff --git a/tools/h5diff/testfiles/h5diff_624.txt b/tools/h5diff/testfiles/h5diff_624.txt
index d646a25..dc7c83b 100644
--- a/tools/h5diff/testfiles/h5diff_624.txt
+++ b/tools/h5diff/testfiles/h5diff_624.txt
@@ -4,64 +4,99 @@ usage: h5diff [OPTIONS] file1 file2 [obj1[obj2]]
   file2                    File name of the second HDF5 file
   [obj1]                   Name of an HDF5 object, in absolute path
   [obj2]                   Name of an HDF5 object, in absolute path
+
   OPTIONS
-   -h, --help              Print a usage message and exit
-   -V, --version           Print version number and exit
-   -r, --report            Report mode. Print differences
-   -v, --verbose           Verbose mode. Print differences, list of objects
-   -q, --quiet             Quiet mode. Do not do output
-   -l, --link-follow       Follow link(s)
+   -h, --help              Print a usage message and exit.
+   -V, --version           Print version number and exit.
+   -r, --report            Report mode. Print differences.
+   -v, --verbose           Verbose mode. Print differences, list of objects.
+   -q, --quiet             Quiet mode. Do not produce output.
+   --follow-links          Follow symbolic links (soft links and external links)
+                           and compare the links' target objects.
+                           If symbolic link(s) with the same name exist in the
+                           files being compared, then determine whether the 
+                           target of each link is an existing object (dataset,
+                           group, or named datatype) or the link is a dangling
+                           link (a soft or external link pointing to a target
+                           object that does not yet exist).
+                           - If both symbolic links are dangling links, they
+                             are treated as being the same; by default, h5diff
+                             returns an exit code of 0. If, however, 
+                             --no-dangling-links is used with --follow-links, 
+                             this situation is treated as an error and h5diff 
+                             returns an exit code of 2.
+                           - If only one of the two links is a dangling link,
+                             they are treated as being different and h5diff 
+                             returns an exit code of 1. If, however, 
+                             --no-dangling-links is used with --follow-links, 
+                             this situation is treated as an error and h5diff 
+                             returns an exit code of 2.
+                           - If both symbolic links point to existing objects,
+                             h5diff compares the two objects.
+                           If any symbolic link specified in the call to h5diff
+                           does not exist, h5diff treats it as an error and
+                           returns an exit code of 2.
+   --no-dangling-links     Must be used with --follow-links option;
+                           otherwise, h5diff shows error message and returns
+                           an exit code of 2.
+                           Check for any symbolic links (soft links or external
+                           links) that do not resolve to an existing object
+                           (dataset, group, or named datatype).  If any
+                           dangling link is found, this situation is treated as
+                           an error and h5diff returns an exit code of 2.
    -c, --compare           List objects that are not comparable
    -N, --nan               Avoid NaNs detection
-   -n C, --count=C         Print differences up to C number, C is a positive integer.
-   -d D, --delta=D         Print difference if (|a-b| > D), D is a positive number.
-   -p R, --relative=R      Print difference if (|(a-b)/b| > R), R is a positive number.
+   -n C, --count=C         Print differences up to C number, C is a positive
+                           integer.
+   -d D, --delta=D         Print difference if (|a-b| > D), D is a positive
+                           number.
+   -p R, --relative=R      Print difference if (|(a-b)/b| > R), R is a positive
+                           number.
    --use-system-epsilon    Print difference if (|a-b| > EPSILON),
-                           where EPSILON (FLT_EPSILON or FLT_EPSILON) is the system epsilon value. 
-                           If the system epsilon is not defined, use the value below:
+                           where EPSILON (FLT_EPSILON or FLT_EPSILON) is the
+                           system epsilon value. 
+                           If the system epsilon is not defined, use the value
+                           below:
                                FLT_EPSILON = 1.19209E-07 for float
                                DBL_EPSILON = 2.22045E-16 for double
-                           -d, -p, and --use-system-epsilon options are used for comparing floating point values.
-                           By default, strict equality is used. Use -p or -d to set specific tolerance.
+                           -d, -p, and --use-system-epsilon options are used for
+                           comparing floating point values.
+                           By default, strict equality is used. Use -p or -d to
+                           set specific tolerance.
 
  Modes of output:
-
   Default mode: print the number of differences found and where they occured
   -r Report mode: print the above plus the differences
   -v Verbose mode: print the above plus a list of objects and warnings
   -q Quiet mode: do not print output
 
  Compare criteria
-
- If no objects [obj1[obj2]] are specified, h5diff only compares objects
-   with the same absolute path in both files
+  If no objects [obj1[obj2]] are specified, h5diff only compares objects
+  with the same absolute path in both files
 
  The compare criteria is:
-   1) datasets: numerical array differences 2) groups: name string difference
-   3) datatypes: the return value of H5Tequal 4) links: name string difference
-   of the linked value
+  1) datasets: numerical array differences
+  2) groups: name string difference
+  3) datatypes: the return value of H5Tequal
+  4) links: name string difference of the linked value as default
+            (refer to --follow-links option).
 
- Return exit code:
-
-  1 if differences found, 0 if no differences, 2 if error
+ Exit code:
+  0 if no differences, 1 if differences found, 2 if error
 
  Examples of use:
-
  1) h5diff file1 file2 /g1/dset1 /g1/dset2
-
     Compares object '/g1/dset1' in file1 with '/g1/dset2' in file2
 
  2) h5diff file1 file2 /g1/dset1
-
     Compares object '/g1/dset1' in both files
 
  3) h5diff file1 file2
-
     Compares all objects in both files
 
- Note)  file1 and file2 can be the same file. Use
-
-    h5diff file1 file1 /g1/dset1 /g1/dset2
-
-    to compare '/g1/dset1' and '/g1/dset2' in the same file
+ Notes:
+  file1 and file2 can be the same file.
+  Use h5diff file1 file1 /g1/dset1 /g1/dset2 to compare
+  '/g1/dset1' and '/g1/dset2' in the same file
 
+EXIT CODE: 1