[svn-r26643] Purpose: Adding new wrappers (HDFFR-9167 partially)

Description:
    Added wrappers for C functions H5P[s/g]et_libver_bounds and wrappers
    for getting object header version

      // Sets bounds on versions of library format to be used when creating
      // or writing objects.
      void setLibverBounds(H5F_libver_t libver_low, H5F_libver_t libver_high) const;

      // Gets the current settings for the library version format bounds.
      void getLibverBounds(H5F_libver_t& libver_low, H5F_libver_t& libver_high) const;

      // Returns the object header version of an object in a file or group,
      // given the object's name.
      unsigned childObjVersion(const char* objname) const;
      unsigned childObjVersion(const H5std_string& objname) const;

Platforms tested:
    Linux/64 (platypus)
    Linux/32 2.6
    SunOS 5.11

7 files changed, 256 insertions, 2 deletions

diff --git a/c++/src/H5CommonFG.cpp b/c++/src/H5CommonFG.cpp
index 3aa0386..1ef36eb 100644
--- a/c++/src/H5CommonFG.cpp
+++ b/c++/src/H5CommonFG.cpp
@@ -1100,6 +1100,58 @@ H5O_type_t CommonFG::childObjType(hsize_t index, H5_index_t index_type, H5_iter_
     return(objtype);
 }
 
+//--------------------------------------------------------------------------
+// Function:	CommonFG::childObjVersion
+///\brief	Returns the object header version of an object in this file/group,
+///		given the object's name.
+///\param	objname - IN: Name of the object
+///\return	Object version, which can have the following values:
+///		\li \c H5O_VERSION_1
+///		\li \c H5O_VERSION_2
+///\exception	H5::FileIException or H5::GroupIException
+///		Exception will be thrown when:
+///		- an error returned by the C API
+///		- version number is not one of the valid values above
+// Programmer	Binh-Minh Ribler - April, 2014
+//--------------------------------------------------------------------------
+unsigned CommonFG::childObjVersion(const char* objname) const
+{
+    H5O_info_t objinfo;
+
+    // Use C API to get information of the object
+    herr_t ret_value = H5Oget_info_by_name(getLocId(), objname, &objinfo, H5P_DEFAULT);
+
+    // Throw exception if C API returns failure
+    if (ret_value < 0)
+	throwException("childObjVersion", "H5Oget_info_by_name failed");
+    // Return a valid version or throw an exception for invalid value
+    else
+    {
+	unsigned version = objinfo.hdr.version;
+	if (version != H5O_VERSION_1 && version != H5O_VERSION_2)
+	    throwException("childObjVersion", "Invalid version for object");
+	else
+	    return(version);
+    }
+}
+
+//--------------------------------------------------------------------------
+// Function:	CommonFG::childObjVersion
+///\brief	This is an overloaded member function, provided for convenience.
+///		It takes an \a H5std_string for the object's name.
+///\brief	Returns the type of an object in this group, given the
+///		object's name.
+///\param	objname - IN: Name of the object (H5std_string&)
+///\exception	H5::FileIException or H5::GroupIException
+// Programmer	Binh-Minh Ribler - April, 2014
+//--------------------------------------------------------------------------
+unsigned CommonFG::childObjVersion(const H5std_string& objname) const
+{
+    // Use overloaded function
+    unsigned version = childObjVersion(objname.c_str());
+    return(version);
+}
+
 #ifndef H5_NO_DEPRECATED_SYMBOLS
 #ifndef DOXYGEN_SHOULD_SKIP_THIS
 //--------------------------------------------------------------------------
diff --git a/c++/src/H5CommonFG.h b/c++/src/H5CommonFG.h
index 5c8a142..2fbbaf2 100644
--- a/c++/src/H5CommonFG.h
+++ b/c++/src/H5CommonFG.h
@@ -70,6 +70,11 @@ class H5_DLLCPP CommonFG {
 	H5O_type_t childObjType(const char* objname) const;
 	H5O_type_t childObjType(hsize_t index, H5_index_t index_type=H5_INDEX_NAME, H5_iter_order_t order=H5_ITER_INC, const char* objname=".") const;
 
+	// Returns the object header version of an object in this file or group,
+	// given the object's name.
+	unsigned childObjVersion(const char* objname) const;
+	unsigned childObjVersion(const H5std_string& objname) const;
+
 #ifndef H5_NO_DEPRECATED_SYMBOLS
 	// Returns the type of an object in this group, given the
 	// object's index.
diff --git a/c++/src/H5DataType.cpp b/c++/src/H5DataType.cpp
index 9040668..4783fbc 100644
--- a/c++/src/H5DataType.cpp
+++ b/c++/src/H5DataType.cpp
@@ -226,6 +226,7 @@ void DataType::copy(const DataSet& dset)
 //		characteristics as the original one, specifically, if the
 //		rhs represents a named datatype, "this" would still be a
 //		transient datatype.
+//		BMR - Mar, 2015
 //--------------------------------------------------------------------------
 DataType& DataType::operator=( const DataType& rhs )
 {
diff --git a/c++/src/H5FaccProp.cpp b/c++/src/H5FaccProp.cpp
index 5696742..5ce9d8e 100644
--- a/c++/src/H5FaccProp.cpp
+++ b/c++/src/H5FaccProp.cpp
@@ -40,10 +40,10 @@ FileAccPropList::FileAccPropList() : PropList( H5P_FILE_ACCESS ) {}
 //--------------------------------------------------------------------------
 // Function:	FileAccPropList copy constructor
 ///\brief	Copy Constructor: makes a copy of the original
-///		FileAccPropList object.
+///\param	original - IN: FileAccPropList instance to copy
 // Programmer:	Binh-Minh Ribler - 2000
 //--------------------------------------------------------------------------
-FileAccPropList::FileAccPropList(const FileAccPropList& orig) : PropList(orig) {}
+FileAccPropList::FileAccPropList(const FileAccPropList& original) : PropList(original) {}
 
 //--------------------------------------------------------------------------
 // Function:	FileAccPropList overloaded constructor
@@ -664,6 +664,67 @@ unsigned FileAccPropList::getGcReferences() const
 }
 
 //--------------------------------------------------------------------------
+// Function:	FileAccPropList::setLibverBounds
+///\brief	Sets bounds on versions of library format to be used when creating
+///		or writing objects.
+///\param	libver_low  - IN: Earliest version of the library that will be
+///				  used for creating or writing objects
+///\param	libver_high - IN: Latest version of the library that will be
+///\exception	H5::PropListIException
+///\par Description
+///		Valid values of \a libver_low are as follows:
+///		\li \c H5F_LIBVER_EARLIEST   (Default)
+///		\li \c H5F_LIBVER_18
+///		\li \c H5F_LIBVER_LATEST
+///
+///		Valid values of \a libver_high are as follows:
+///		\li \c H5F_LIBVER_18
+///		\li \c H5F_LIBVER_LATEST   (Default)
+///
+///		For more details, please refer to
+/// http://www.hdfgroup.org/HDF5/doc/RM/RM_H5P.html#Property-SetLibverBounds
+// Programmer:  Binh-Minh Ribler - March, 2015
+//--------------------------------------------------------------------------
+void FileAccPropList::setLibverBounds(H5F_libver_t libver_low, H5F_libver_t libver_high) const
+{
+    herr_t ret_value = H5Pset_libver_bounds(id, libver_low, libver_high);
+    if (ret_value < 0)
+    {
+	throw PropListIException("FileAccPropList::setLibverBounds", "H5Pset_libver_bounds failed");
+    }
+}
+
+//--------------------------------------------------------------------------
+// Function:	FileAccPropList::getLibverBounds
+///\brief	Gets the current settings for the library version format bounds
+///		from a file access property list.
+///\param	libver_low  - OUT: Earliest version of the library that will be
+///				   used for creating or writing objects
+///\param	libver_high - OUT: Latest version of the library that will be
+///				   used for creating or writing objects
+///\exception	H5::PropListIException
+///\par Description
+///		On success, the argument \a libver_low can have the following
+///		values:
+///		\li \c H5F_LIBVER_EARLIEST
+///		\li \c H5F_LIBVER_18
+///		\li \c H5F_LIBVER_LATEST
+///
+///		and \a libver_high:
+///		\li \c H5F_LIBVER_18
+///		\li \c H5F_LIBVER_LATEST
+// Programmer:  Binh-Minh Ribler - March, 2015
+//--------------------------------------------------------------------------
+void FileAccPropList::getLibverBounds(H5F_libver_t& libver_low, H5F_libver_t& libver_high) const
+{
+    herr_t ret_value = H5Pget_libver_bounds(id, &libver_low, &libver_high);
+    if( ret_value < 0 )
+    {
+	throw PropListIException("FileAccPropList::getLibverBounds", "H5Pget_libver_bounds failed");
+    }
+}
+
+//--------------------------------------------------------------------------
 // Function:	FileAccPropList destructor
 ///\brief	Noop destructor
 // Programmer	Binh-Minh Ribler - 2000
diff --git a/c++/src/H5FaccProp.h b/c++/src/H5FaccProp.h
index 861ac4c..fddc446 100644
--- a/c++/src/H5FaccProp.h
+++ b/c++/src/H5FaccProp.h
@@ -126,6 +126,13 @@ class H5_DLLCPP FileAccPropList : public PropList {
 	// Returns garbage collecting references setting.
 	unsigned getGcReferences() const;
 
+	// Sets bounds on versions of library format to be used when creating
+	// or writing objects.
+	void setLibverBounds(H5F_libver_t libver_low, H5F_libver_t libver_high) const;
+
+	// Gets the current settings for the library version format bounds.
+	void getLibverBounds(H5F_libver_t& libver_low, H5F_libver_t& libver_high) const;
+
 	///\brief Returns this class name.
 	virtual H5std_string fromClass () const { return("FileAccPropList"); }
 
diff --git a/c++/src/H5Include.h b/c++/src/H5Include.h
index 87cb182..1e0e952 100644
--- a/c++/src/H5Include.h
+++ b/c++/src/H5Include.h
@@ -28,3 +28,15 @@ typedef int bool;
 const bool  false = 0;
 const bool  true  = 1;
 #endif
+
+// These are defined in H5Opkg.h, which should not be included in the C++ API,
+// so re-define them here for now.
+
+/* Initial version of the object header format */
+#define H5O_VERSION_1	1
+
+/* Revised version - leaves out reserved bytes and alignment padding, and adds
+ *      magic number as prefix and checksum as suffix for all chunks.
+ */
+#define H5O_VERSION_2	2
+
diff --git a/c++/test/tfile.cpp b/c++/test/tfile.cpp
index ad5e6fc..6d5dc23 100644
--- a/c++/test/tfile.cpp
+++ b/c++/test/tfile.cpp
@@ -501,6 +501,7 @@ const H5std_string	FATTR1_NAME ("file attribute 1");
 const H5std_string	FATTR2_NAME ("file attribute 2");
 int fattr_data[ATTR1_DIM1]={512,-234,98123}; /* Test data for file attribute */
 int dattr_data[ATTR1_DIM1]={256,-123,1000}; /* Test data for dataset attribute */
+
 static void test_file_attribute()
 {
     int rdata[ATTR1_DIM1];
@@ -602,6 +603,119 @@ static void test_file_attribute()
     }
 }   // test_file_attribute()
 
+const H5std_string	FILE6("tfile5.h5");
+const H5std_string	ROOTGROUP("/");
+const H5std_string	GROUP1("/G1");
+const H5std_string	SUBGROUP3("/G1/G3");
+
+/*-------------------------------------------------------------------------
+ * Function:	test_libver_bounds_real
+ *
+ * Purpose:	Verify that a file created and modified with the
+ *		specified libver bounds has the specified object header
+ *		versions for the right objects.
+ *
+ * Return:	None
+ *
+ * Programmer:	Binh-Minh Ribler (use C version)
+ *		March, 2015
+ *
+ *-------------------------------------------------------------------------
+ */
+static void test_libver_bounds_real(
+		H5F_libver_t libver_create, unsigned oh_vers_create,
+		H5F_libver_t libver_mod, unsigned oh_vers_mod)
+{
+    try {
+
+    /*
+     * Create a new file using the default creation property and access property
+     * with latest library version.
+     */
+    FileAccPropList fapl;
+    fapl.setLibverBounds(libver_create, H5F_LIBVER_LATEST);
+    H5File file(FILE6, H5F_ACC_TRUNC, FileCreatPropList::DEFAULT, fapl);
+
+    /*
+     * Make sure the root group has the correct object header version
+     */
+    unsigned obj_version = file.childObjVersion(ROOTGROUP);
+    verify_val(obj_version, oh_vers_create, "H5File::childObjVersion", __LINE__, __FILE__);
+
+    /*
+     * Reopen the file and make sure the root group still has the correct version
+     */
+    file.close();
+
+    fapl.setLibverBounds(libver_mod, H5F_LIBVER_LATEST);
+
+    file.openFile(FILE6, H5F_ACC_RDWR, fapl);
+
+    obj_version = file.childObjVersion(ROOTGROUP);
+    verify_val(obj_version, oh_vers_create, "H5File::childObjVersion", __LINE__, __FILE__);
+
+    /*
+     * Create a group named "/G1" in the file, and make sure it has the correct
+     * object header version
+     */
+    Group group = file.createGroup(GROUP1);
+
+    obj_version = file.childObjVersion(GROUP1);
+    verify_val(obj_version, oh_vers_mod, "H5File::childObjVersion", __LINE__, __FILE__);
+
+    group.close(); // close "/G1"
+
+    /*
+     * Create a group named "/G1/G3" in the file, and make sure it has the
+     * correct object header version
+     */
+    group = file.createGroup(SUBGROUP3);
+
+    obj_version = group.childObjVersion(SUBGROUP3);
+    verify_val(obj_version, oh_vers_mod, "H5File::childObjVersion", __LINE__, __FILE__);
+
+    group.close(); // close "/G1/G3"
+
+    /*
+     * Make sure the root group still has the correct object header version
+     */
+    obj_version = file.childObjVersion(ROOTGROUP);
+    verify_val(obj_version, oh_vers_create, "H5File::childObjVersion", __LINE__, __FILE__);
+
+    // Everything should be closed as they go out of scope
+    }   // end of try block
+
+    catch (Exception E) {
+        issue_fail_msg("test_libver_bounds_real()", __LINE__, __FILE__, E.getCDetailMsg());
+    }
+
+} /* end test_libver_bounds_real() */
+
+/*-------------------------------------------------------------------------
+ *
+ * Function:    test_libver_bounds
+ *
+ * Purpose:     Verify that a file created and modified with various
+ *		libver bounds is handled correctly.
+ *
+ * Return:      None
+ *
+ * Programmer:  Binh-Minh Ribler (use C version)
+ *              March 2015
+ *
+ *-------------------------------------------------------------------------
+ */
+static void test_libver_bounds()
+{
+    // Output message about test being performed
+    SUBTEST("Setting library version bounds");
+
+    /* Run the tests */
+    test_libver_bounds_real(H5F_LIBVER_EARLIEST, H5O_VERSION_1, H5F_LIBVER_LATEST, H5O_VERSION_2);
+    test_libver_bounds_real(H5F_LIBVER_LATEST, H5O_VERSION_2, H5F_LIBVER_EARLIEST, H5O_VERSION_1);
+    PASSED();
+} /* end test_libver_bounds() */
+
 /*-------------------------------------------------------------------------
  * Function:    test_file
  *
@@ -629,6 +743,7 @@ void test_file()
     test_file_size();	// Test file size
     test_file_name();	// Test getting file's name
     test_file_attribute();	// Test file attribute feature
+    test_libver_bounds();	// Test format version
 }   // test_file()
 
 
@@ -655,4 +770,5 @@ void cleanup_file()
     HDremove(FILE3.c_str());
     HDremove(FILE4.c_str());
     HDremove(FILE5.c_str());
+    HDremove(FILE6.c_str());
 }   // cleanup_file