[svn-r18892] Improvment:

Revised the online help page of h5dump to explain the packed bits feature and
added an example too.

Tested: h5committest plus jam tested with --disable-h5dump-packedbits.

8 files changed, 84 insertions, 34 deletions

diff --git a/tools/h5dump/h5dump.c b/tools/h5dump/h5dump.c
index 5fe4315..d9c373a 100644
--- a/tools/h5dump/h5dump.c
+++ b/tools/h5dump/h5dump.c
@@ -682,8 +682,14 @@ usage(const char *prog)
     fprintf(stdout, "     -q Q, --sort_by=Q    Sort groups and attributes by index Q\n");
     fprintf(stdout, "     -z Z, --sort_order=Z Sort groups and attributes by order Z\n");
 #ifdef H5_HAVE_H5DUMP_PACKED_BITS
-    fprintf(stdout, "     -M M, --packedbits=M Print packed bits using mask format M for dataset P given\n");
-    fprintf(stdout, "                          in option d. Where M is (offset,length)[,(offset,length)].\n");
+    fprintf(stdout,
+	"     -M L, --packedbits=L Print packed bits as unsigned integers, using mask\n"
+	"                          format L for an integer dataset specified with\n"
+	"                          option -d. L is a list of offset,length values,\n"
+	"                          separated by commas. Offset is the beginning bit in\n"
+	"                          the data value and length is the number of bits of\n"
+	"                          the mask.\n"
+	);
 #endif
     fprintf(stdout, "     -R, --region         Print dataset pointed by region references\n");
     fprintf(stdout, "     -x, --xml            Output in XML using Schema\n");
@@ -724,10 +730,6 @@ usage(const char *prog)
     fprintf(stdout, "        -d (dataset) is used. B is an optional argument, defaults to NATIVE\n");
     fprintf(stdout, "  Q - is the sort index type. It can be \"creation_order\" or \"name\" (default)\n");
     fprintf(stdout, "  Z - is the sort order type. It can be \"descending\" or \"ascending\" (default)\n");
-#ifdef H5_HAVE_H5DUMP_PACKED_BITS
-    fprintf(stdout, "  M - is a paired list of integers the first number of which is the offset and the\n");
-    fprintf(stdout, "        second number is the length of the its being queried\n");
-#endif
     fprintf(stdout, "\n");
     fprintf(stdout, "  Examples:\n");
     fprintf(stdout, "\n");
@@ -743,6 +745,12 @@ usage(const char *prog)
     fprintf(stdout, "        using a little-endian type\n");
     fprintf(stdout, "\n");
     fprintf(stdout, "      h5dump -d /dset -b LE -o out.bin quux.h5\n");
+#ifdef H5_HAVE_H5DUMP_PACKED_BITS
+    fprintf(stdout, "\n");
+    fprintf(stdout, "  4) Display two packed bits (bits 0-1 and bits 4-6) in the dataset /dset\n");
+    fprintf(stdout, "\n");
+    fprintf(stdout, "      h5dump -d /dset -M 0,1,4,3 quux.h5\n");
+#endif
     fprintf(stdout, "\n");
 }
 
diff --git a/tools/testfiles/tnofilename-with-packed-bits.ddl b/tools/testfiles/tnofilename-with-packed-bits.ddl
index b33eaf8..89250fc 100644
--- a/tools/testfiles/tnofilename-with-packed-bits.ddl
+++ b/tools/testfiles/tnofilename-with-packed-bits.ddl
@@ -28,8 +28,12 @@ usage: h5dump [OPTIONS] file
      -m T, --format=T     Set the floating point output format
      -q Q, --sort_by=Q    Sort groups and attributes by index Q
      -z Z, --sort_order=Z Sort groups and attributes by order Z
-     -M M, --packedbits=M Print packed bits using mask format M for dataset P given
-                          in option d. Where M is (offset,length)[,(offset,length)].
+     -M L, --packedbits=L Print packed bits as unsigned integers, using mask
+                          format L for an integer dataset specified with
+                          option -d. L is a list of offset,length values,
+                          separated by commas. Offset is the beginning bit in
+                          the data value and length is the number of bits of
+                          the mask.
      -R, --region         Print dataset pointed by region references
      -x, --xml            Output in XML using Schema
      -u, --use-dtd        Output in XML using DTD
@@ -69,8 +73,6 @@ usage: h5dump [OPTIONS] file
         -d (dataset) is used. B is an optional argument, defaults to NATIVE
   Q - is the sort index type. It can be "creation_order" or "name" (default)
   Z - is the sort order type. It can be "descending" or "ascending" (default)
-  M - is a paired list of integers the first number of which is the offset and the
-        second number is the length of the its being queried
 
   Examples:
 
@@ -87,3 +89,7 @@ usage: h5dump [OPTIONS] file
 
       h5dump -d /dset -b LE -o out.bin quux.h5
 
+  4) Display two packed bits (bits 0-1 and bits 4-6) in the dataset /dset
+
+      h5dump -d /dset -M 0,1,4,3 quux.h5
+
diff --git a/tools/testfiles/tpbitsIncomplete.ddl b/tools/testfiles/tpbitsIncomplete.ddl
index dbde4f5..a5b19b1 100644
--- a/tools/testfiles/tpbitsIncomplete.ddl
+++ b/tools/testfiles/tpbitsIncomplete.ddl
@@ -28,8 +28,12 @@ usage: h5dump [OPTIONS] file
      -m T, --format=T     Set the floating point output format
      -q Q, --sort_by=Q    Sort groups and attributes by index Q
      -z Z, --sort_order=Z Sort groups and attributes by order Z
-     -M M, --packedbits=M Print packed bits using mask format M for dataset P given
-                          in option d. Where M is (offset,length)[,(offset,length)].
+     -M L, --packedbits=L Print packed bits as unsigned integers, using mask
+                          format L for an integer dataset specified with
+                          option -d. L is a list of offset,length values,
+                          separated by commas. Offset is the beginning bit in
+                          the data value and length is the number of bits of
+                          the mask.
      -R, --region         Print dataset pointed by region references
      -x, --xml            Output in XML using Schema
      -u, --use-dtd        Output in XML using DTD
@@ -69,8 +73,6 @@ usage: h5dump [OPTIONS] file
         -d (dataset) is used. B is an optional argument, defaults to NATIVE
   Q - is the sort index type. It can be "creation_order" or "name" (default)
   Z - is the sort order type. It can be "descending" or "ascending" (default)
-  M - is a paired list of integers the first number of which is the offset and the
-        second number is the length of the its being queried
 
   Examples:
 
@@ -87,4 +89,8 @@ usage: h5dump [OPTIONS] file
 
       h5dump -d /dset -b LE -o out.bin quux.h5
 
+  4) Display two packed bits (bits 0-1 and bits 4-6) in the dataset /dset
+
+      h5dump -d /dset -M 0,1,4,3 quux.h5
+
 h5dump error: Bad mask list(0,2,2,1,0,2,2,)
diff --git a/tools/testfiles/tpbitsLengthExceeded.ddl b/tools/testfiles/tpbitsLengthExceeded.ddl
index 6b02648..9220d9e 100644
--- a/tools/testfiles/tpbitsLengthExceeded.ddl
+++ b/tools/testfiles/tpbitsLengthExceeded.ddl
@@ -28,8 +28,12 @@ usage: h5dump [OPTIONS] file
      -m T, --format=T     Set the floating point output format
      -q Q, --sort_by=Q    Sort groups and attributes by index Q
      -z Z, --sort_order=Z Sort groups and attributes by order Z
-     -M M, --packedbits=M Print packed bits using mask format M for dataset P given
-                          in option d. Where M is (offset,length)[,(offset,length)].
+     -M L, --packedbits=L Print packed bits as unsigned integers, using mask
+                          format L for an integer dataset specified with
+                          option -d. L is a list of offset,length values,
+                          separated by commas. Offset is the beginning bit in
+                          the data value and length is the number of bits of
+                          the mask.
      -R, --region         Print dataset pointed by region references
      -x, --xml            Output in XML using Schema
      -u, --use-dtd        Output in XML using DTD
@@ -69,8 +73,6 @@ usage: h5dump [OPTIONS] file
         -d (dataset) is used. B is an optional argument, defaults to NATIVE
   Q - is the sort index type. It can be "creation_order" or "name" (default)
   Z - is the sort order type. It can be "descending" or "ascending" (default)
-  M - is a paired list of integers the first number of which is the offset and the
-        second number is the length of the its being queried
 
   Examples:
 
@@ -87,4 +89,8 @@ usage: h5dump [OPTIONS] file
 
       h5dump -d /dset -b LE -o out.bin quux.h5
 
+  4) Display two packed bits (bits 0-1 and bits 4-6) in the dataset /dset
+
+      h5dump -d /dset -M 0,1,4,3 quux.h5
+
 h5dump error: Packed Bit offset+length value(9) too large. Max is 8
diff --git a/tools/testfiles/tpbitsLengthPositive.ddl b/tools/testfiles/tpbitsLengthPositive.ddl
index 0f4093e..1b2ef63 100644
--- a/tools/testfiles/tpbitsLengthPositive.ddl
+++ b/tools/testfiles/tpbitsLengthPositive.ddl
@@ -28,8 +28,12 @@ usage: h5dump [OPTIONS] file
      -m T, --format=T     Set the floating point output format
      -q Q, --sort_by=Q    Sort groups and attributes by index Q
      -z Z, --sort_order=Z Sort groups and attributes by order Z
-     -M M, --packedbits=M Print packed bits using mask format M for dataset P given
-                          in option d. Where M is (offset,length)[,(offset,length)].
+     -M L, --packedbits=L Print packed bits as unsigned integers, using mask
+                          format L for an integer dataset specified with
+                          option -d. L is a list of offset,length values,
+                          separated by commas. Offset is the beginning bit in
+                          the data value and length is the number of bits of
+                          the mask.
      -R, --region         Print dataset pointed by region references
      -x, --xml            Output in XML using Schema
      -u, --use-dtd        Output in XML using DTD
@@ -69,8 +73,6 @@ usage: h5dump [OPTIONS] file
         -d (dataset) is used. B is an optional argument, defaults to NATIVE
   Q - is the sort index type. It can be "creation_order" or "name" (default)
   Z - is the sort order type. It can be "descending" or "ascending" (default)
-  M - is a paired list of integers the first number of which is the offset and the
-        second number is the length of the its being queried
 
   Examples:
 
@@ -87,4 +89,8 @@ usage: h5dump [OPTIONS] file
 
       h5dump -d /dset -b LE -o out.bin quux.h5
 
+  4) Display two packed bits (bits 0-1 and bits 4-6) in the dataset /dset
+
+      h5dump -d /dset -M 0,1,4,3 quux.h5
+
 h5dump error: Packed Bit length value(0) must be positive.
diff --git a/tools/testfiles/tpbitsMaxExceeded.ddl b/tools/testfiles/tpbitsMaxExceeded.ddl
index 01e854d..c39b91f 100644
--- a/tools/testfiles/tpbitsMaxExceeded.ddl
+++ b/tools/testfiles/tpbitsMaxExceeded.ddl
@@ -28,8 +28,12 @@ usage: h5dump [OPTIONS] file
      -m T, --format=T     Set the floating point output format
      -q Q, --sort_by=Q    Sort groups and attributes by index Q
      -z Z, --sort_order=Z Sort groups and attributes by order Z
-     -M M, --packedbits=M Print packed bits using mask format M for dataset P given
-                          in option d. Where M is (offset,length)[,(offset,length)].
+     -M L, --packedbits=L Print packed bits as unsigned integers, using mask
+                          format L for an integer dataset specified with
+                          option -d. L is a list of offset,length values,
+                          separated by commas. Offset is the beginning bit in
+                          the data value and length is the number of bits of
+                          the mask.
      -R, --region         Print dataset pointed by region references
      -x, --xml            Output in XML using Schema
      -u, --use-dtd        Output in XML using DTD
@@ -69,8 +73,6 @@ usage: h5dump [OPTIONS] file
         -d (dataset) is used. B is an optional argument, defaults to NATIVE
   Q - is the sort index type. It can be "creation_order" or "name" (default)
   Z - is the sort order type. It can be "descending" or "ascending" (default)
-  M - is a paired list of integers the first number of which is the offset and the
-        second number is the length of the its being queried
 
   Examples:
 
@@ -87,4 +89,8 @@ usage: h5dump [OPTIONS] file
 
       h5dump -d /dset -b LE -o out.bin quux.h5
 
+  4) Display two packed bits (bits 0-1 and bits 4-6) in the dataset /dset
+
+      h5dump -d /dset -M 0,1,4,3 quux.h5
+
 h5dump error: Too many masks requested (max. 8). Mask list(0,1,0,1,1,1,2,1,3,1,4,1,5,1,6,1,7,1)
diff --git a/tools/testfiles/tpbitsOffsetExceeded.ddl b/tools/testfiles/tpbitsOffsetExceeded.ddl
index cf7055e..2859b5e 100644
--- a/tools/testfiles/tpbitsOffsetExceeded.ddl
+++ b/tools/testfiles/tpbitsOffsetExceeded.ddl
@@ -28,8 +28,12 @@ usage: h5dump [OPTIONS] file
      -m T, --format=T     Set the floating point output format
      -q Q, --sort_by=Q    Sort groups and attributes by index Q
      -z Z, --sort_order=Z Sort groups and attributes by order Z
-     -M M, --packedbits=M Print packed bits using mask format M for dataset P given
-                          in option d. Where M is (offset,length)[,(offset,length)].
+     -M L, --packedbits=L Print packed bits as unsigned integers, using mask
+                          format L for an integer dataset specified with
+                          option -d. L is a list of offset,length values,
+                          separated by commas. Offset is the beginning bit in
+                          the data value and length is the number of bits of
+                          the mask.
      -R, --region         Print dataset pointed by region references
      -x, --xml            Output in XML using Schema
      -u, --use-dtd        Output in XML using DTD
@@ -69,8 +73,6 @@ usage: h5dump [OPTIONS] file
         -d (dataset) is used. B is an optional argument, defaults to NATIVE
   Q - is the sort index type. It can be "creation_order" or "name" (default)
   Z - is the sort order type. It can be "descending" or "ascending" (default)
-  M - is a paired list of integers the first number of which is the offset and the
-        second number is the length of the its being queried
 
   Examples:
 
@@ -87,4 +89,8 @@ usage: h5dump [OPTIONS] file
 
       h5dump -d /dset -b LE -o out.bin quux.h5
 
+  4) Display two packed bits (bits 0-1 and bits 4-6) in the dataset /dset
+
+      h5dump -d /dset -M 0,1,4,3 quux.h5
+
 h5dump error: Packed Bit offset value(8) must be between 0 and 7
diff --git a/tools/testfiles/tpbitsOffsetNegative.ddl b/tools/testfiles/tpbitsOffsetNegative.ddl
index b514bca..af22bd3 100644
--- a/tools/testfiles/tpbitsOffsetNegative.ddl
+++ b/tools/testfiles/tpbitsOffsetNegative.ddl
@@ -28,8 +28,12 @@ usage: h5dump [OPTIONS] file
      -m T, --format=T     Set the floating point output format
      -q Q, --sort_by=Q    Sort groups and attributes by index Q
      -z Z, --sort_order=Z Sort groups and attributes by order Z
-     -M M, --packedbits=M Print packed bits using mask format M for dataset P given
-                          in option d. Where M is (offset,length)[,(offset,length)].
+     -M L, --packedbits=L Print packed bits as unsigned integers, using mask
+                          format L for an integer dataset specified with
+                          option -d. L is a list of offset,length values,
+                          separated by commas. Offset is the beginning bit in
+                          the data value and length is the number of bits of
+                          the mask.
      -R, --region         Print dataset pointed by region references
      -x, --xml            Output in XML using Schema
      -u, --use-dtd        Output in XML using DTD
@@ -69,8 +73,6 @@ usage: h5dump [OPTIONS] file
         -d (dataset) is used. B is an optional argument, defaults to NATIVE
   Q - is the sort index type. It can be "creation_order" or "name" (default)
   Z - is the sort order type. It can be "descending" or "ascending" (default)
-  M - is a paired list of integers the first number of which is the offset and the
-        second number is the length of the its being queried
 
   Examples:
 
@@ -87,4 +89,8 @@ usage: h5dump [OPTIONS] file
 
       h5dump -d /dset -b LE -o out.bin quux.h5
 
+  4) Display two packed bits (bits 0-1 and bits 4-6) in the dataset /dset
+
+      h5dump -d /dset -M 0,1,4,3 quux.h5
+
 h5dump error: Bad mask list(-1,1)