[svn-r21236] Purpose:

   Work for:
   HDFFV-7515 - GMQS: h5unjam - incorrect help page and should display when 
   no file is given.
   and
   HDFFV-5941 - h5jam: specifying a user block file with a proper HDF5 magic
   number will result in a corrupted HDF5 file.


Description:
   - Revised command help pages of h5jam and h5unjam. The descriptions
     were not up to date and some were missing. (HDFFV-7515)
   - Fixed h5jam not to allow specifying an HDF5 formatted file as input 
     file for -u (user block file) option, because the original HDF5 file 
     will not be accessible if allows. (HDFFV-5941)

Tested:
    jam (linux32-LE), koala (linux64-LE), heiwa (linuxppc64-BE), tejeda (mac32-LE), linew (solaris-BE), Cmake (jam, Wondows)

9 files changed, 293 insertions, 61 deletions

diff --git a/tools/h5jam/CMakeLists.txt b/tools/h5jam/CMakeLists.txt
index 536ca46..1c3e782 100644
--- a/tools/h5jam/CMakeLists.txt
+++ b/tools/h5jam/CMakeLists.txt
@@ -58,6 +58,7 @@ IF (BUILD_TESTING)
       u513.txt
       h5jam-help.txt
       h5unjam-help.txt
+      h5jam-ub-nohdf5.txt
   )
   SET (HDF5_REFERENCE_TEST_FILES
       tall.h5
@@ -94,36 +95,51 @@ IF (BUILD_TESTING)
 ##############################################################################
 ##############################################################################
 
-  MACRO (ADD_HELP_TEST testname resultcode)
+  # ============================================================
+  # TEST_H5JAM_OUTPUT
+  # For the purpose to verify only output & exitcode from h5jam
+  #
+  MACRO (TEST_H5JAM_OUTPUT expectfile resultcode)
     # If using memchecker add tests without using scripts
     IF (HDF5_ENABLE_USING_MEMCHECKER)
-      ADD_TEST (NAME H5JAM-${testname} COMMAND $<TARGET_FILE:h5jam> ${ARGN})
-      ADD_TEST (NAME H5JAM-UNJAM-${testname} COMMAND $<TARGET_FILE:h5unjam> ${ARGN})
+      ADD_TEST (NAME H5JAM-${expectfile} COMMAND $<TARGET_FILE:h5jam> ${ARGN})
     ELSE (HDF5_ENABLE_USING_MEMCHECKER)
       ADD_TEST (
-          NAME H5JAM-${testname}
+          NAME H5JAM-${expectfile}
           COMMAND "${CMAKE_COMMAND}"
               -D "TEST_PROGRAM=$<TARGET_FILE:h5jam>"
-              -D "TEST_ARGS=${ARGN}"
+              -D "TEST_ARGS:STRING=${ARGN}"
               -D "TEST_FOLDER=${PROJECT_BINARY_DIR}"
-              -D "TEST_OUTPUT=h5jam-${testname}.out"
+              -D "TEST_OUTPUT=${expectfile}.out"
               -D "TEST_EXPECT=${resultcode}"
-              -D "TEST_REFERENCE=testfiles/h5jam-${testname}.txt"
+              -D "TEST_REFERENCE=testfiles/${expectfile}.txt"
               -P "${HDF5_RESOURCES_DIR}/runTest.cmake"
       )
+    ENDIF (HDF5_ENABLE_USING_MEMCHECKER)
+  ENDMACRO (TEST_H5JAM_OUTPUT)
+
+  # ============================================================
+  # TEST_H5UNJAM_OUTPUT
+  # For the purpose to verify only output & exitcode from h5unjam
+  #
+  MACRO (TEST_H5UNJAM_OUTPUT expectfile resultcode)
+    # If using memchecker add tests without using scripts
+    IF (HDF5_ENABLE_USING_MEMCHECKER)
+      ADD_TEST (NAME H5JAM-UNJAM-${expectfile} COMMAND $<TARGET_FILE:h5unjam> ${ARGN})
+    ELSE (HDF5_ENABLE_USING_MEMCHECKER)
       ADD_TEST (
-          NAME H5JAM-UNJAM-${testname}
+          NAME H5JAM-UNJAM-${expectfile}
           COMMAND "${CMAKE_COMMAND}"
               -D "TEST_PROGRAM=$<TARGET_FILE:h5unjam>"
               -D "TEST_ARGS=${ARGN}"
               -D "TEST_FOLDER=${PROJECT_BINARY_DIR}"
-              -D "TEST_OUTPUT=h5unjam-${testname}.out"
+              -D "TEST_OUTPUT=${expectfile}.out"
               -D "TEST_EXPECT=${resultcode}"
-              -D "TEST_REFERENCE=testfiles/h5unjam-${testname}.txt"
+              -D "TEST_REFERENCE=testfiles/${expectfile}.txt"
               -P "${HDF5_RESOURCES_DIR}/runTest.cmake"
       )
     ENDIF (HDF5_ENABLE_USING_MEMCHECKER)
-  ENDMACRO (ADD_HELP_TEST)
+  ENDMACRO (TEST_H5UNJAM_OUTPUT)
 
   MACRO (CLEANUP testname)
     ADD_TEST (
@@ -342,7 +358,14 @@ IF (BUILD_TESTING)
 ##############################################################################
 ##############################################################################
 
-  ADD_HELP_TEST(help 0 -h)
+#-------------------------------
+# Testing h5jam
+#-------------------------------
+  # help page
+  TEST_H5JAM_OUTPUT(h5jam-help 0 -h)
+
+  # don't allow HDF5 format file as an user block file
+  TEST_H5JAM_OUTPUT(h5jam-ub-nohdf5 1 -i testfiles/tall.h5 -u testfiles/tall.h5 -o tall-tmp.h5)
 
   JAMTEST (tall_u10 u10.txt tall.h5 ta2.h5)
   CHECKFILE (tall_u10 tall.h5 ta2.h5)
@@ -457,6 +480,12 @@ IF (BUILD_TESTING)
   CHECKFILE (N_twithub513_u513_c tall.h5 tay9.h5)
 #  CLEANUP (N_twithub513_u513_c tay9.h5)
 
+#-------------------------------
+# Testing h5unjam
+#-------------------------------
+  # help page
+  TEST_H5UNJAM_OUTPUT(h5unjam-help 0 -h)
+
   SETUP (twithub_tall twithub.h5 tai1.h5)
   UNJAMTEST (twithub_tall tai1.h5 o10.txt taa1.h5)
   CHECKFILE (twithub_tall tall.h5 taa1.h5)
diff --git a/tools/h5jam/h5jam.c b/tools/h5jam/h5jam.c
index b300583..5520dc7 100644
--- a/tools/h5jam/h5jam.c
+++ b/tools/h5jam/h5jam.c
@@ -70,20 +70,51 @@ static struct long_options l_opts[] = {
 static void
 usage (const char *prog)
 {
-  fflush (stdout);
-  fprintf (stdout,
-     "usage: %s -u user_block_file -i h5_file [-o ofile | --clobber] \n",
-     prog);
-  fprintf (stdout, "           Add 'user_block_file' to front of \n");
-  fprintf (stdout,
-     "           'h5_file', pad so 'h5_file' starts on proper\n");
-  fprintf (stdout, "           byte.\n");
-  fprintf (stdout, "\n");
-  fprintf (stdout, "       %s -h \n", prog);
-  fprintf (stdout, "           Print a usage message and exit\n");
-  fprintf (stdout, "       %s -V \n", prog);
-  fprintf (stdout, "           Print HDF5 library version and exit\n");
-
+    HDfflush (stdout);
+    HDfprintf (stdout,
+    "usage: %s -i <in_file.h5> -u <in_user_file> [-o <out_file.h5>] [--clobber]\n", prog);
+    HDfprintf (stdout, "\n");
+    HDfprintf (stdout,
+    "Adds user block to front of an HDF5 file and creates a new concatenated file.\n");
+    HDfprintf (stdout, "\n");
+    HDfprintf (stdout, 
+    "OPTIONS\n");
+    HDfprintf (stdout, 
+    "  -i in_file.h5    Specifies the input HDF5 file.\n");
+    HDfprintf (stdout, 
+    "  -u in_user_file  Specifies the file to be inserted into the user block.\n");
+    HDfprintf (stdout, 
+    "                   Can be any file format except an HDF5 format.\n");
+    HDfprintf (stdout,
+    "  -o out_file.h5   Specifies the output HDF5 file.\n");
+    HDfprintf (stdout,
+    "                   If not specified, the user block will be concatenated in\n");
+    HDfprintf (stdout,
+    "                   place to the input HDF5 file.\n");
+    HDfprintf (stdout,
+    "  --clobber        Wipes out any existing user block before concatenating\n");
+    HDfprintf (stdout,
+    "                   the given user block.\n");
+    HDfprintf (stdout,
+    "                   The size of the new user block will be the larger of;\n");
+    HDfprintf (stdout,
+    "                    - the size of existing user block in the input HDF5 file\n");
+    HDfprintf (stdout,
+    "                    - the size of user block required by new input user file\n");
+    HDfprintf (stdout,
+    "                   (size = 512 x 2N,  N is positive integer.)\n");
+    HDfprintf (stdout, "\n");
+    HDfprintf (stdout,
+    "  -h               Prints a usage message and exits.\n");
+    HDfprintf (stdout,
+    "  -V               Prints the HDF5 library version and exits.\n");
+    HDfprintf (stdout, "\n");
+    HDfprintf (stdout,
+    "Exit Status:\n");
+    HDfprintf (stdout,
+    "   0   Succeeded.\n");
+    HDfprintf (stdout,
+    "   >0  An error occurred.\n");
 }
 
 
@@ -210,22 +241,30 @@ main (int argc, const char *argv[])
 
     if (ub_file == NULL) {
         /* no user block */
-        error_msg("no user block file name\n");
-        usage (h5tools_getprogname());
+        error_msg("missing arguemnt for -u <user_file>.\n");
+        help_ref_msg(stderr);
+        leave (EXIT_FAILURE);
+    }
+
+    testval = H5Fis_hdf5 (ub_file);
+
+    if (testval > 0) {
+        error_msg("-u <user_file> cannot be HDF5 file, but it appears to be an HDF5 file.\n");
+        help_ref_msg(stderr);
         leave (EXIT_FAILURE);
     }
 
     if (input_file == NULL) {
-        /* no user block */
-        error_msg("no HDF5 file\n");
-        usage (h5tools_getprogname());
+        error_msg("missing arguemnt for -i <HDF5 file>.\n");
+        help_ref_msg(stderr);
         leave (EXIT_FAILURE);
     }
 
     testval = H5Fis_hdf5 (input_file);
 
     if (testval <= 0) {
-        error_msg("Input HDF5 file is not HDF \"%s\"\n", input_file);
+        error_msg("Input HDF5 file \"%s\" is not HDF5 format.\n", input_file);
+        help_ref_msg(stderr);
         leave (EXIT_FAILURE);
     }
 
diff --git a/tools/h5jam/h5unjam.c b/tools/h5jam/h5unjam.c
index d3b36a9..14ed651 100644
--- a/tools/h5jam/h5unjam.c
+++ b/tools/h5jam/h5unjam.c
@@ -69,15 +69,56 @@ static struct long_options l_opts[] = {
 static void
 usage(const char *prog)
 {
-    fflush(stdout);
-    fprintf(stdout, "usage: %s -i h5_file -o user_block_file_out -o h5_file_out [-d | --delete]\n", prog);
-    fprintf(stdout, "           Extract user block from 'h5_file' into 'user_block_file'\n");
-    fprintf(stdout, "           and HDF5 file into 'h5_file_out'\n");
-
-    fprintf(stdout, "       %s -h\n",prog);
-    fprintf(stdout, "           Print a usage message and exit\n");
-    fprintf(stdout, "       %s -V \n", prog);
-    fprintf(stdout, "           Print HDF5 library version and exit\n");
+    HDfflush(stdout);
+    HDfprintf(stdout,
+    "usage: %s -i <in_file.h5>  [-o <out_file.h5> ] [-u <out_user_file> | --delete]\n", prog);
+    HDfprintf(stdout, "\n");
+    HDfprintf(stdout,
+    "Splits user file and HDF5 file into two files: user block data and HDF5 data.\n");
+    HDfprintf(stdout, "\n");
+    HDfprintf(stdout,
+    "OPTIONS\n");
+    HDfprintf(stdout,
+    "  -i in_file.h5   Specifies the HDF5 as input.  If the input HDF5 file\n");
+    HDfprintf(stdout,
+    "                  contains no user block, exit with an error message.\n");
+    HDfprintf(stdout,
+    "  -o out_file.h5  Specifies output HDF5 file without a user block.\n");
+    HDfprintf(stdout,
+    "                  If not specified, the user block will be removed from the\n");
+    HDfprintf(stdout,
+    "                  input HDF5 file.\n");
+    HDfprintf(stdout,
+    "  -u out_user_file\n");
+    HDfprintf(stdout,
+    "                  Specifies the output file containing the data from the\n");
+    HDfprintf(stdout,
+    "                  user block.\n");
+    HDfprintf(stdout,
+    "                  Cannot be used with --delete option.\n");
+    HDfprintf(stdout,
+    "  --delete        Remove the user block from the input HDF5 file. The content\n");
+    HDfprintf(stdout,
+    "                  of the user block is discarded.\n");
+    HDfprintf(stdout,
+    "                  Cannot be used with the -u option.\n");
+    HDfprintf(stdout, "\n");
+    HDfprintf(stdout,
+    "  -h              Prints a usage message and exits.\n");
+    HDfprintf(stdout,
+    "  -V              Prints the HDF5 library version and exits.\n");
+    HDfprintf(stdout, "\n");
+    HDfprintf(stdout,
+    "  If neither --delete nor -u is specified, the user block from the input file\n");
+    HDfprintf(stdout,
+    "  will be displayed to stdout.\n");
+    HDfprintf(stdout, "\n");
+    HDfprintf(stdout,
+    "Exit Status:\n");
+    HDfprintf(stdout,
+    "  0      Succeeded.\n");
+    HDfprintf(stdout,
+    "  >0    An error occurred.\n");
 }
 
 /*-------------------------------------------------------------------------
@@ -203,10 +244,18 @@ main(int argc, const char *argv[])
 
     parse_command_line(argc, argv);
 
+    if (input_file == NULL) {
+        /* no user block */
+        error_msg("missing arguemnt for HDF5 file input.\n");
+        help_ref_msg(stderr);
+        leave (EXIT_FAILURE);
+    }
+
     testval = H5Fis_hdf5(input_file);
 
     if (testval <= 0) {
-        error_msg("Input HDF5 file is not HDF \"%s\"\n", input_file);
+        error_msg("Input HDF5 file \"%s\" is not HDF\n", input_file);
+        help_ref_msg (stderr);
         h5tools_setstatus(EXIT_FAILURE);
         goto done;
     }
diff --git a/tools/h5jam/testfiles/h5jam-help.txt b/tools/h5jam/testfiles/h5jam-help.txt
index f5d1f19..ce97c22 100644
--- a/tools/h5jam/testfiles/h5jam-help.txt
+++ b/tools/h5jam/testfiles/h5jam-help.txt
@@ -1,9 +1,24 @@
-usage: h5jam -u user_block_file -i h5_file [-o ofile | --clobber] 
-           Add 'user_block_file' to front of 
-           'h5_file', pad so 'h5_file' starts on proper
-           byte.
-
-       h5jam -h 
-           Print a usage message and exit
-       h5jam -V 
-           Print HDF5 library version and exit
+usage: h5jam -i <in_file.h5> -u <in_user_file> [-o <out_file.h5>] [--clobber]
+
+Adds user block to front of an HDF5 file and creates a new concatenated file.
+
+OPTIONS
+  -i in_file.h5    Specifies the input HDF5 file.
+  -u in_user_file  Specifies the file to be inserted into the user block.
+                   Can be any file format except an HDF5 format.
+  -o out_file.h5   Specifies the output HDF5 file.
+                   If not specified, the user block will be concatenated in
+                   place to the input HDF5 file.
+  --clobber        Wipes out any existing user block before concatenating
+                   the given user block.
+                   The size of the new user block will be the larger of;
+                    - the size of existing user block in the input HDF5 file
+                    - the size of user block required by new input user file
+                   (size = 512 x 2N,  N is positive integer.)
+
+  -h               Prints a usage message and exits.
+  -V               Prints the HDF5 library version and exits.
+
+Exit Status:
+   0   Succeeded.
+   >0  An error occurred.
diff --git a/tools/h5jam/testfiles/h5jam-ub-nohdf5.txt b/tools/h5jam/testfiles/h5jam-ub-nohdf5.txt
new file mode 100644
index 0000000..72c0b17
--- /dev/null
+++ b/tools/h5jam/testfiles/h5jam-ub-nohdf5.txt
@@ -0,0 +1,2 @@
+h5jam error: -u <user_file> cannot be HDF5 file, but it appears to be an HDF5 file.
+Try '-h' or '--help' for more information or see the <h5jam> entry in the 'HDF5 Reference Manual'.
diff --git a/tools/h5jam/testfiles/h5unjam-help.txt b/tools/h5jam/testfiles/h5unjam-help.txt
index 3eb73c5..f0d92e9 100644
--- a/tools/h5jam/testfiles/h5unjam-help.txt
+++ b/tools/h5jam/testfiles/h5unjam-help.txt
@@ -1,7 +1,27 @@
-usage: h5unjam -i h5_file -o user_block_file_out -o h5_file_out [-d | --delete]
-           Extract user block from 'h5_file' into 'user_block_file'
-           and HDF5 file into 'h5_file_out'
-       h5unjam -h
-           Print a usage message and exit
-       h5unjam -V 
-           Print HDF5 library version and exit
+usage: h5unjam -i <in_file.h5>  [-o <out_file.h5> ] [-u <out_user_file> | --delete]
+
+Splits user file and HDF5 file into two files: user block data and HDF5 data.
+
+OPTIONS
+  -i in_file.h5   Specifies the HDF5 as input.  If the input HDF5 file
+                  contains no user block, exit with an error message.
+  -o out_file.h5  Specifies output HDF5 file without a user block.
+                  If not specified, the user block will be removed from the
+                  input HDF5 file.
+  -u out_user_file
+                  Specifies the output file containing the data from the
+                  user block.
+                  Cannot be used with --delete option.
+  --delete        Remove the user block from the input HDF5 file. The content
+                  of the user block is discarded.
+                  Cannot be used with the -u option.
+
+  -h              Prints a usage message and exits.
+  -V              Prints the HDF5 library version and exits.
+
+  If neither --delete nor -u is specified, the user block from the input file
+  will be displayed to stdout.
+
+Exit Status:
+  0      Succeeded.
+  >0    An error occurred.
diff --git a/tools/h5jam/testh5jam.sh.in b/tools/h5jam/testh5jam.sh.in
index 4508767..14b381c 100644
--- a/tools/h5jam/testh5jam.sh.in
+++ b/tools/h5jam/testh5jam.sh.in
@@ -83,6 +83,7 @@ $SRC_H5JAM_TESTFILES/u512.txt
 $SRC_H5JAM_TESTFILES/u513.txt
 $SRC_H5JAM_TESTFILES/h5jam-help.txt
 $SRC_H5JAM_TESTFILES/h5unjam-help.txt
+$SRC_H5JAM_TESTFILES/h5jam-ub-nohdf5.txt
 "
 
 #
@@ -115,8 +116,7 @@ COPY_TESTFILES_TO_TESTDIR()
 #
 TESTING() {
    SPACES="                                                               "
-   echo "Testing $* $SPACES"
-   #echo "Testing $* $SPACES" | cut -c1-70 | tr -d '\012'
+   echo "Testing $* $SPACES" | cut -c1-70 | tr -d '\012'
 }
 
 # Print a line-line message left justified in a field of 70 characters
@@ -446,6 +446,51 @@ UNJAMTEST () {
 }
 
 
+#
+# TOOLTEST_OUTPUT < JAM | UNJAM > expect-output.txt exit-code options
+#
+# Only verify stdout/stderr output from h5jam and j5unjam
+#
+
+TOOLTEST_OUTPUT() {
+    if [ "$1" == "JAM" ]; then
+        TOOLCMD=$JAM_BIN/$JAM
+    elif [ "$1" == "UNJAM" ]; then
+        TOOLCMD=$JAM_BIN/$UNJAM
+    fi
+    shift
+    expect="$TESTDIR/$1"
+    actual="$TESTDIR/`basename $1 .ls`.out"
+    actual_err="$TESTDIR/`basename $1 .ls`.err"
+    shift
+    retvalexpect=$1
+    shift
+
+    TESTING h5jam $@
+    (
+        cd $TESTDIR
+        $TOOLCMD "$@"
+    ) >$actual 2>$actual_err
+
+    # combine stderr to stdout for output compare 
+    cat $actual_err >> $actual
+
+    if [ ! -f $expect ]; then
+	    # Create the expect file if it doesn't yet exist.
+        echo " CREATED"
+        cp $actual $expect
+	    rm -f $actual $actual_err
+    elif $CMP $expect $actual; then
+        echo " PASSED"
+	    rm -f $actual $actual_err
+    else
+        echo "*FAILED*"
+	    echo "    Expected result differs from actual result"
+	    nerrors="`expr $nerrors + 1`"
+        test yes = "$verbose" && $DIFF $expect $actual |sed 's/^/    /'
+    fi
+}
+
 ##############################################################################
 ##############################################################################
 ###			  T H E   T E S T S                                ###
@@ -454,7 +499,15 @@ UNJAMTEST () {
 # prepare for test
 COPY_TESTFILES_TO_TESTDIR
 
-# test start
+#-------------------------------
+# Testing h5jam
+#-------------------------------
+# help page
+TOOLTEST_OUTPUT JAM h5jam-help.txt 0 -h
+
+# don't allow HDF5 format file as an user block file
+TOOLTEST_OUTPUT JAM h5jam-ub-nohdf5.txt 1 -i tall.h5 -u tall.h5 -o tall-tmp.h5
+
 JAMTEST $TESTDIR/u10.txt $TESTDIR/tall.h5 ta2.h5
 CHECKFILE $TESTDIR/tall.h5 ta2.h5
 CLEANUP ta2.h5
@@ -568,6 +621,12 @@ JAMTEST $TESTDIR/u513.txt tay9.h5 --clobber
 CHECKFILE $TESTDIR/tall.h5 tay9.h5
 CLEANUP tay9.h5
 
+#---------------------------------
+# Testing h5unjam 
+#---------------------------------
+# help page
+TOOLTEST_OUTPUT UNJAM h5unjam-help.txt 0 -h
+
 SETUP $TESTDIR/twithub.h5 tai1.h5
 UNJAMTEST tai1.h5 o10.txt taa1.h5
 CHECKFILE $TESTDIR/tall.h5 taa1.h5
diff --git a/tools/lib/h5tools_utils.c b/tools/lib/h5tools_utils.c
index ee6d5d2..ab8536f 100644
--- a/tools/lib/h5tools_utils.c
+++ b/tools/lib/h5tools_utils.c
@@ -178,6 +178,24 @@ warn_msg(const char *fmt, ...)
     va_end(ap);
 }
 
+/*-------------------------------------------------------------------------
+ * Function:  help_ref_msg
+ *
+ * Purpose: Print a message to refer help page 
+ *
+ * Return:  Nothing
+ *
+ * Modifications:
+ *
+ *-------------------------------------------------------------------------
+ */
+void
+help_ref_msg(FILE *output)
+{
+    HDfprintf(output, "Try '-h' or '--help' for more information or ");
+    HDfprintf(output, "see the <%s> entry in the 'HDF5 Reference Manual'.\n",h5tools_getprogname());
+}
+
 
 /*-------------------------------------------------------------------------
  * Function:    get_option
diff --git a/tools/lib/h5tools_utils.h b/tools/lib/h5tools_utils.h
index a7d06f7..be32d07 100644
--- a/tools/lib/h5tools_utils.h
+++ b/tools/lib/h5tools_utils.h
@@ -123,6 +123,7 @@ H5TOOLS_DLL void     print_version(const char *progname);
 H5TOOLS_DLL void     parallel_print(const char* format, ... );
 H5TOOLS_DLL void     error_msg(const char *fmt, ...);
 H5TOOLS_DLL void     warn_msg(const char *fmt, ...);
+H5TOOLS_DLL void     help_ref_msg(FILE *output);
 H5TOOLS_DLL void     free_table(table_t *table);
 #ifdef H5DUMP_DEBUG
 H5TOOLS_DLL void     dump_tables(find_objs_t *info)