[svn-r10971] Purpose: Bug fix

Description: See details from Bug #213.  Family member file size wasn't saved
anywhere in file.  When family file is opened, the first member size determine
the member size.

Solution:  Hopefully, this is the last step of checkin for this stage.  This step
mainly enables h5repart tool to be able to convert file driver from family to
sec2.  Because the library saves family information in file, in trying to convert
to sec2 driver, the library simply change the address of driver information to
undefined so that the driver information block can be ignored.  This step also
updates the reference manual of H5Pset_fapl_family() and h5repart.

In the fifth step of checkin, backward compatibility with v1.6
is tested.  A family file created was created with the v1.6 library and opened
with this version of the library.

In the fourth step of checkin, a test suit is added for h5repart,
including a program to generate the test files, a script file to run h5repart,
and a program to verify repartitioned files can be opened by the library.

There's a change from the first step of checkin.  Family name template is no
longer saved in the superblock because different pathname can make the name
different.

In the third step of checkin, h5repart has been modified.  If h5repart is used
to change the size of family member file, the new size(actual member size) is saved
in the superblock.

In the second step of checkin, multi driver is checked against the driver
name saved in superblock.  Wrong driver will result in a failure with an error message
indicating
multi driver should be used.  This change includes split driver because it's a special
case for multi
driver.

In the first step of checkin.  Family member size and name template(unused at this stage) are saved
in file superblock.  When file is reopened,the size passed in thrin superblock.  A different size
will trigger a failure with an error message indicating the right size.  Wrong driver to open family
file will cause a failure, too.


Platforms tested: h5committest and fuss.

Misc. update: doc/html/RM_H5P.html and doc/html/Tools.html

3 files changed, 94 insertions, 29 deletions

diff --git a/tools/misc/h5repart.c b/tools/misc/h5repart.c
index b3a463b..c88b5a8 100644
--- a/tools/misc/h5repart.c
+++ b/tools/misc/h5repart.c
@@ -65,9 +65,11 @@
 #   define MIN3(X,Y,Z)	MIN(MIN(X,Y),Z)
 #endif
 
-/*Make this private property(defined in H5Fprivate.h) available to h5repart, 
- *to update the member file size in the superblock.*/ 
+/*Make these 2 private properties(defined in H5Fprivate.h) available to h5repart. 
+ *The first one updates the member file size in the superblock.  The second one
+ *change file driver from family to sec2. */ 
 #define H5F_ACS_FAMILY_NEWSIZE_NAME            "family_newsize"
+#define H5F_ACS_FAMILY_TO_SEC2_NAME            "family_to_sec2"
 
 
 /*-------------------------------------------------------------------------
@@ -87,12 +89,13 @@
 static void
 usage (const char *progname)
 {
-    fprintf(stderr, "usage: %s [-v] [-V] [-[b|m] N[g|m|k]] SRC DST\n",
+    fprintf(stderr, "usage: %s [-v] [-V] [-[b|m] N[g|m|k]] [-family_to_sec2] SRC DST\n",
 	    progname);
     fprintf(stderr, "   -v     Produce verbose output\n");
     fprintf(stderr, "   -V     Print a version number and exit\n");
     fprintf(stderr, "   -b N   The I/O block size, defaults to 1kB\n");
     fprintf(stderr, "   -m N   The destination member size or 1GB\n");
+    fprintf(stderr, "   -family_to_sec2   Change file driver from family to sec2\n");
     fprintf(stderr, "   SRC    The name of the source file\n");
     fprintf(stderr, "   DST	The name of the destination files\n");
     fprintf(stderr, "Sizes may be suffixed with `g' for GB, `m' for MB or "
@@ -230,6 +233,7 @@ main (int argc, char *argv[])
     hid_t       fapl;                   /*file access property list     */
     hid_t       file;
     hsize_t     hdsize;                 /*destination logical memb size */
+    hbool_t     family_to_sec2=FALSE;   /*change family to sec2 driver? */
 
     /*
      * Get the program name from argv[0]. Use only the last component.
@@ -248,6 +252,9 @@ main (int argc, char *argv[])
 	    printf("This is %s version %u.%u release %u\n",
 		   prog_name, H5_VERS_MAJOR, H5_VERS_MINOR, H5_VERS_RELEASE);
 	    exit(0);
+        } else if (!strcmp (argv[argno], "-family_to_sec2")) {
+	    family_to_sec2 = TRUE;
+	    argno++;
 	} else if ('b'==argv[argno][1]) {
 	    blk_size = get_size (prog_name, &argno, argc, argv);
 	} else if ('m'==argv[argno][1]) {
@@ -449,36 +456,53 @@ main (int argc, char *argv[])
     }
     close (dst);
 
-    /* Modify family size saved in superblock through private property. It signals 
-     * library to save the new member size(specified in command line) in superblock.  
-     * This private property is for this tool only. */
+    /* Modify family driver information saved in superblock through private property. 
+     * These private properties are for this tool only. */
     if ((fapl=H5Pcreate(H5P_FILE_ACCESS))<0) {
         perror ("H5Pcreate");
         exit (1);
     }
 
-    if(H5Pset_fapl_family(fapl, H5F_FAMILY_DEFAULT, H5P_DEFAULT) < 0) {
-        perror ("H5Pset_fapl_family");
-        exit (1);
-    }
-
-    /* Set the property as hsize_t */
-    hdsize = dst_size;
-    if(H5Pset(fapl, H5F_ACS_FAMILY_NEWSIZE_NAME, &hdsize) < 0) { 
-        perror ("H5Pset_family_newsize");
-        exit (1);
+    if(family_to_sec2) {
+        /* The user wants to change file driver from family to sec2. Open the file
+         * with sec2 driver.  This property signals the library to ignore the family
+         * driver information saved in the superblock. */
+        if(H5Pset(fapl, H5F_ACS_FAMILY_TO_SEC2_NAME, &family_to_sec2) < 0) { 
+            perror ("H5Pset");
+            exit (1);
+        }
+    } else {
+        /* Modify family size saved in superblock through private property. It signals 
+         * library to save the new member size(specified in command line) in superblock.  
+         * This private property is for this tool only. */
+        if(H5Pset_fapl_family(fapl, H5F_FAMILY_DEFAULT, H5P_DEFAULT) < 0) {
+            perror ("H5Pset_fapl_family");
+            exit (1);
+        }
+
+        /* Set the property of the new member size as hsize_t */
+        hdsize = dst_size;
+        if(H5Pset(fapl, H5F_ACS_FAMILY_NEWSIZE_NAME, &hdsize) < 0) { 
+            perror ("H5Pset");
+            exit (1);
+        }
     }
 
-    /* Open file for "read and write" to flush metadata. Flushing metadata 
-     * will update the superblock to the new member size. */
-    if((file=H5Fopen(dst_gen_name, H5F_ACC_RDWR, fapl))<0) {
-        perror ("H5Fopen");
-        exit (1);
-    }
-  
-    if(H5Fclose(file)<0) {
-        perror ("H5Fclose");
-        exit (1);
+    /* If the new file is a family file, try to open file for "read and write" to 
+     * flush metadata. Flushing metadata will update the superblock to the new 
+     * member size.  If the original file is a family file and the new file is a sec2 
+     * file, the property FAMILY_TO_SEC2 will signal the library to switch to sec2 
+     * driver when the new file is opened.  If the original file is a sec2 file and the 
+     * new file can only be a sec2 file, reopen the new file should fail.  There's 
+     * nothing to do in this case. */
+    H5E_BEGIN_TRY {
+        file=H5Fopen(dst_gen_name, H5F_ACC_RDWR, fapl);
+    } H5E_END_TRY;
+    if(file>=0) { 
+        if(H5Fclose(file)<0) {
+            perror ("H5Fclose");
+            exit (1);
+        }
     }
 
     if(H5Pclose(fapl)<0) {
diff --git a/tools/misc/repart_test.c b/tools/misc/repart_test.c
index 7b81cf4..833a496 100644
--- a/tools/misc/repart_test.c
+++ b/tools/misc/repart_test.c
@@ -30,11 +30,12 @@
 const char *FILENAME[] = {      
     "fst_family%05d.h5",
     "scd_family%05d.h5",
+    "family_to_sec2.h5",
     NULL        
 };
 
-herr_t
-test_family_h5repart_opens(void);
+herr_t test_family_h5repart_opens(void);
+herr_t test_sec2_h5repart_opens(void);
 
 
 /*-------------------------------------------------------------------------
@@ -91,6 +92,43 @@ error:
 
 
 /*-------------------------------------------------------------------------
+ * Function:    test_sec2_h5repart_opens
+ *
+ * Purpose:     Tries to reopen a sec2 file.
+ *
+ * Return:      Success:        exit(0)
+ *
+ *              Failure:        exit(1)
+ *
+ * Programmer:  Raymond Lu
+ *              June 21, 2005
+ *
+ * Modifications:
+ *-------------------------------------------------------------------------
+ */
+herr_t
+test_sec2_h5repart_opens(void)
+{
+    hid_t       file=(-1);
+    
+    /* open the sec2 file */
+    if((file=H5Fopen(FILENAME[2], H5F_ACC_RDWR, H5P_DEFAULT))<0)
+        goto error;
+
+    if(H5Fclose(file)<0)
+        goto error;
+
+    return 0;
+
+error:
+    H5E_BEGIN_TRY {
+        H5Fclose(file);
+    } H5E_END_TRY;
+    return -1;
+}
+
+
+/*-------------------------------------------------------------------------
  * Function:    main
  * 
  * Purpose:     Tests h5repart-ed family files 
@@ -112,6 +150,7 @@ main(void)
     int                 nerrors=0;
          
     nerrors += test_family_h5repart_opens()<0   ?1:0;
+    nerrors += test_sec2_h5repart_opens()<0     ?1:0;
 
     if (nerrors) goto error;
     
diff --git a/tools/misc/testh5repart.sh.in b/tools/misc/testh5repart.sh.in
index 2fb90ea..744dd00 100644
--- a/tools/misc/testh5repart.sh.in
+++ b/tools/misc/testh5repart.sh.in
@@ -92,6 +92,8 @@ SKIP() {
 TOOLTEST -m 20000 family_file%05d.h5 $actual_dir/fst_family%05d.h5
 # repartition family member size to 5 KB.
 TOOLTEST -m 5k family_file%05d.h5 $actual_dir/scd_family%05d.h5
+# convert family file to sec2 file of 20,000 bytes
+TOOLTEST -m 20000 -family_to_sec2 family_file%05d.h5 $actual_dir/family_to_sec2.h5
 
 # test the output files repartitioned above.
 OUTPUTTEST
@@ -104,7 +106,7 @@ fi
 # Clean up output file
 if test -z "$HDF5_NOCLEANUP"; then
     cd $actual_dir
-    rm -f fst_family*.h5 scd_family*.h5
+    rm -f fst_family*.h5 scd_family*.h5 family_to_sec2.h5
 fi
 
 exit $nerrors