From c3bfac06392131adaec4744d50274e75638f76b6 Mon Sep 17 00:00:00 2001 From: Binh-Minh Ribler Date: Thu, 8 Jul 2004 14:48:45 -0500 Subject: [svn-r8837] Purpose: Update doc and fix minor bug Description: H5IdComponent.cpp: initialized a pointer to NULL H5Object.cpp: removed functions being added by mistake Update function headers for the rest. Platforms tested: SunOS 5.7 (arabica) Linux 2.4 (eirene) --- c++/src/H5DataSpace.cpp | 3 ++ c++/src/H5DcreatProp.cpp | 51 ++++++++++---------- c++/src/H5DxferProp.cpp | 118 ++++++++++++++++++++++++++++++++++++++-------- c++/src/H5FaccProp.cpp | 5 +- c++/src/H5FcreatProp.cpp | 6 +-- c++/src/H5File.cpp | 16 +++---- c++/src/H5File.h | 13 ++--- c++/src/H5IdComponent.cpp | 2 +- c++/src/H5Object.cpp | 47 ------------------ c++/src/H5PropList.cpp | 10 +++- 10 files changed, 159 insertions(+), 112 deletions(-) diff --git a/c++/src/H5DataSpace.cpp b/c++/src/H5DataSpace.cpp index 12fb269..6a119af 100644 --- a/c++/src/H5DataSpace.cpp +++ b/c++/src/H5DataSpace.cpp @@ -28,6 +28,9 @@ namespace H5 { #endif +//-------------------------------------------------------------------------- +///\brief Constant for default dataspace +//-------------------------------------------------------------------------- const DataSpace DataSpace::ALL( H5S_ALL ); //-------------------------------------------------------------------------- diff --git a/c++/src/H5DcreatProp.cpp b/c++/src/H5DcreatProp.cpp index f4150ac..2f031a6 100644 --- a/c++/src/H5DcreatProp.cpp +++ b/c++/src/H5DcreatProp.cpp @@ -26,6 +26,9 @@ namespace H5 { #endif +//-------------------------------------------------------------------------- +///\brief Constant for default property +//-------------------------------------------------------------------------- const DSetCreatPropList DSetCreatPropList::DEFAULT( H5P_DEFAULT ); //-------------------------------------------------------------------------- @@ -154,7 +157,7 @@ void DSetCreatPropList::setDeflate( int level ) const // Function: DSetCreatPropList::setFillValue ///\brief Sets a dataset fill value ///\param fvalue_type - IN: Data type for the value passed via \a value -///\param value - IN: Pointer to buffer containing the fill value +///\param value - IN: Pointer to buffer containing the fill value ///\exception H5::PropListIException ///\par Description /// The datatype may differ from that of the dataset, but it must @@ -181,7 +184,7 @@ void DSetCreatPropList::setFillValue( const DataType& fvalue_type, const void* v // Function: DSetCreatPropList::getFillValue ///\brief Retrieves a dataset fill value ///\param fvalue_type - IN: Data type for the value passed via \a value -///\param value - OUT: Pointer to buffer to hold the retrieved fill value +///\param value - OUT: Pointer to buffer to hold the retrieved fill value ///\exception H5::PropListIException ///\par Description /// The fill value is returned through \a value pointer @@ -290,15 +293,15 @@ int DSetCreatPropList::getNfilters() const //-------------------------------------------------------------------------- // Function: DSetCreatPropList::getFilter ///\brief Returns information about a filter in a pipeline -///\param filter_number - IN: Filter to get, range [0..N-1], where -/// N is returned by H5Pget_nfilters() -///\param flags - OUT: General properties of the filter -///\param cd_nelmts - IN/OUT: Number of elements in \a cd_values /Number -/// of values defined by the filter -///\param cd_values - OUT: Array to hold the data; allocated by the user -///\param namelen - OUT: Length of \a name -///\param name - OUT: Name of the filter -///\param filter_config - OUT: Flags indicating whether filter can encode/decode +///\param filter_number - IN: Filter to get, range [0..N-1], where +/// N is returned by H5Pget_nfilters() +///\param flags - OUT: General properties of the filter +///\param cd_nelmts - IN/OUT: Number of elements in \a cd_values /Number +/// of values defined by the filter +///\param cd_values - OUT: Array to hold the data; allocated by the user +///\param namelen - OUT: Length of \a name +///\param name - OUT: Name of the filter +///\param filter_config - OUT: Flags indicating whether filter can encode/decode ///\return Filter id ///\exception H5::PropListIException ///\par Description @@ -324,14 +327,14 @@ H5Z_filter_t DSetCreatPropList::getFilter(int filter_number, unsigned int &flags // Function: DSetCreatPropList::getFilterById ///\brief Returns information about a filter in a pipeline given the /// filter id -///\param filter_id - IN: Filter to get -///\param flags - OUT: General properties of the filter -///\param cd_nelmts - IN/OUT: Number of elements in \a cd_values /Number -/// of values defined by the filter -///\param cd_values - OUT: Array to hold the data; allocated by the user -///\param namelen - IN: Length of \a name -///\param name - OUT: Name of the filter -///\param filter_config - OUT: Flags indicating whether filter can encode/decode +///\param filter_id - IN: Filter to get +///\param flags - OUT: General properties of the filter +///\param cd_nelmts - IN/OUT: Number of elements in \a cd_values /Number +/// of values defined by the filter +///\param cd_values - OUT: Array to hold the data; allocated by the user +///\param namelen - IN: Length of \a name +///\param name - OUT: Name of the filter +///\param filter_config - OUT: Flags indicating whether filter can encode/decode ///\exception H5::PropListIException //-------------------------------------------------------------------------- void DSetCreatPropList::getFilterById(H5Z_filter_t filter_id, unsigned int &flags, size_t &cd_nelmts, @@ -569,12 +572,12 @@ int DSetCreatPropList::getExternalCount() const //-------------------------------------------------------------------------- // Function: DSetCreatPropList::getExternal ///\brief Returns information about an external file -///\param idx - IN: Index of the external file, ranges [0-(N-1)] and -/// returned by getExternalCount() +///\param idx - IN: Index of the external file, ranges [0-(N-1)] +/// and returned by \c getExternalCount() ///\param name_size - IN: Maximum length of \a name -///\param name - IN: Name of the external file -///\param offset - IN: Location to return an offset value -///\param size - OUT: Location to return the size of the external file data +///\param name - IN: Name of the external file +///\param offset - IN: Location to return an offset value +///\param size - OUT: Location to return the size of the external file data ///\exception H5::PropListIException ///\par Description /// The parameter \a idx ranges [0..N-1] where N is returned by diff --git a/c++/src/H5DxferProp.cpp b/c++/src/H5DxferProp.cpp index dd4df5d..dda7ba0 100644 --- a/c++/src/H5DxferProp.cpp +++ b/c++/src/H5DxferProp.cpp @@ -24,6 +24,9 @@ namespace H5 { #endif +//-------------------------------------------------------------------------- +///\brief Constant for default property +//-------------------------------------------------------------------------- const DSetMemXferPropList DSetMemXferPropList::DEFAULT( H5P_DEFAULT ); //-------------------------------------------------------------------------- @@ -44,7 +47,15 @@ DSetMemXferPropList::DSetMemXferPropList() : PropList(H5P_DATASET_XFER) {} //-------------------------------------------------------------------------- DSetMemXferPropList::DSetMemXferPropList( const DSetMemXferPropList& orig ) : PropList( orig ) {} -// Sets type conversion and background buffers +//-------------------------------------------------------------------------- +// Function: DSetMemXferPropList::setBuffer +///\brief Sets type conversion and background buffers. +///\param size - IN: Size, in bytes, of the type conversion and background buffers +///\param tconv - IN: Pointer to application-allocated type conversion buffer +///\param bkg - IN: Pointer to application-allocated background buffer +///\exception H5::PropListIException +// Programmer: Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- void DSetMemXferPropList::setBuffer( size_t size, void* tconv, void* bkg ) const { herr_t ret_value = H5Pset_buffer( id, size, tconv, bkg ); @@ -55,7 +66,16 @@ void DSetMemXferPropList::setBuffer( size_t size, void* tconv, void* bkg ) const } } -// Reads buffer settings +//-------------------------------------------------------------------------- +// Function: DSetMemXferPropList::getBuffer +///\brief Reads buffer settings. +///\param tconv - IN: Pointer to application-allocated type conversion buffer +///\param bkg - IN: Pointer to application-allocated background buffer +///\return Buffer size, in bytes +///\exception H5::PropListIException +// Programmer: Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- + size_t DSetMemXferPropList::getBuffer( void** tconv, void** bkg ) const { size_t buffer_size = H5Pget_buffer( id, tconv, bkg ); @@ -67,7 +87,13 @@ size_t DSetMemXferPropList::getBuffer( void** tconv, void** bkg ) const return( buffer_size ); } -// Sets the dataset transfer property list status to TRUE or FALSE +//-------------------------------------------------------------------------- +// Function: DSetMemXferPropList::setPreserve +///\brief Sets the dataset transfer property list status to true or false. +///\param status - IN: Status to set, true or false +///\exception H5::PropListIException +// Programmer: Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- void DSetMemXferPropList::setPreserve( bool status ) const { herr_t ret_value = H5Pset_preserve( id, (hbool_t) status ); @@ -78,7 +104,13 @@ void DSetMemXferPropList::setPreserve( bool status ) const } } -// Checks status of the dataset transfer property list +//-------------------------------------------------------------------------- +// Function: DSetMemXferPropList::getPreserve +///\brief Checks status of the dataset transfer property list. +///\return Status of the dataset transfer property list +///\exception H5::PropListIException +// Programmer: Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- bool DSetMemXferPropList::getPreserve() const { int ret_value = H5Pget_preserve( id ); @@ -93,7 +125,15 @@ bool DSetMemXferPropList::getPreserve() const } } -// Sets B-tree split ratios for a dataset transfer property list +//-------------------------------------------------------------------------- +// Function: DSetMemXferPropList::setBtreeRatios +///\brief Sets B-tree split ratios for a dataset transfer property list. +///\param left - IN: B-tree split ratio for left-most nodes +///\param middle - IN: B-tree split ratio for right-most nodes and lone nodes +///\param right - IN: B-tree split ratio for all other nodes +///\exception H5::PropListIException +// Programmer: Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- void DSetMemXferPropList::setBtreeRatios( double left, double middle, double right ) const { herr_t ret_value = H5Pset_btree_ratios( id, left, middle, right ); @@ -104,7 +144,15 @@ void DSetMemXferPropList::setBtreeRatios( double left, double middle, double rig } } -// Gets B-tree split ratios for a dataset transfer property list +//-------------------------------------------------------------------------- +// Function: DSetMemXferPropList::getBtreeRatios +///\brief Gets B-tree split ratios for a dataset transfer property list. +///\param left - OUT: B-tree split ratio for left-most nodes +///\param middle - OUT: B-tree split ratio for right-most nodes and lone nodes +///\param right - OUT: B-tree split ratio for all other nodes +///\exception H5::PropListIException +// Programmer: Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- void DSetMemXferPropList::getBtreeRatios( double& left, double& middle, double& right ) const { herr_t ret_value = H5Pget_btree_ratios( id, &left, &middle, &right ); @@ -115,8 +163,15 @@ void DSetMemXferPropList::getBtreeRatios( double& left, double& middle, double& } } -// Sets an exception handling callback for datatype conversion -// for a dataset transfer property list +//-------------------------------------------------------------------------- +// Function: DSetMemXferPropList::setTypeConvCB +///\brief Sets an exception handling callback for datatype conversion +/// for a dataset transfer property list. +///\param op - IN: User's function +///\param user_data - IN: User's data +///\exception H5::PropListIException +// Programmer: Binh-Minh Ribler - April, 2004 +//-------------------------------------------------------------------------- void DSetMemXferPropList::setTypeConvCB( H5T_conv_except_func_t op, void *user_data) const { herr_t ret_value = H5Pset_type_conv_cb( id, op, user_data); @@ -127,8 +182,14 @@ void DSetMemXferPropList::setTypeConvCB( H5T_conv_except_func_t op, void *user_d } } -// Sets an exception handling callback for datatype conversion -// for a dataset transfer property list +//-------------------------------------------------------------------------- +// Function: DSetMemXferPropList::getTypeConvCB +///\brief Gets the exception handling callback function and data. +///\param op - IN: Retrieved user function +///\param user_data - IN: Retrieved user data +///\exception H5::PropListIException +// Programmer: Binh-Minh Ribler - April, 2004 +//-------------------------------------------------------------------------- void DSetMemXferPropList::getTypeConvCB( H5T_conv_except_func_t *op, void **user_data) const { herr_t ret_value = H5Pget_type_conv_cb( id, op, user_data); @@ -139,7 +200,16 @@ void DSetMemXferPropList::getTypeConvCB( H5T_conv_except_func_t *op, void **user } } -// Sets the memory manager for variable-length datatype allocation +//-------------------------------------------------------------------------- +// Function: DSetMemXferPropList::setVlenMemManager +///\brief Sets the memory manager for variable-length datatype allocation. +///\param alloc_func - IN: User's allocate routine +///\param alloc_info - IN: User's allocation parameters +///\param free_func - IN: User's free routine +///\param free_info - IN: User's free parameters +///\exception H5::PropListIException +// Programmer: Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- void DSetMemXferPropList::setVlenMemManager( H5MM_allocate_t alloc_func, void* alloc_info, H5MM_free_t free_func, void* free_info ) const { herr_t ret_value = H5Pset_vlen_mem_manager( id, alloc_func, alloc_info, @@ -151,20 +221,28 @@ void DSetMemXferPropList::setVlenMemManager( H5MM_allocate_t alloc_func, void* a } } -// alloc_func and free_func are set to NULL, indicating that system malloc and -// free are to be used +//-------------------------------------------------------------------------- +// Function: DSetMemXferPropList::setVlenMemManager +///\brief Sets the memory manager for variable-length datatype +/// allocation - system \c malloc and \c free will be used. +///\exception H5::PropListIException +// Programmer: Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- void DSetMemXferPropList::setVlenMemManager() const { setVlenMemManager( NULL, NULL, NULL, NULL ); - //herr_t ret_value = H5Pset_vlen_mem_manager( id, NULL, NULL, NULL, NULL ); - //if( ret_value < 0 ) - //{ - //throw PropListIException("DSetMemXferPropList::setVlenMemManager", - //"H5Pset_vlen_mem_manager failed"); - //} } -// Gets the memory manager for variable-length datatype allocation +//-------------------------------------------------------------------------- +// Function: DSetMemXferPropList::getVlenMemManager +///\brief Gets the memory manager for variable-length datatype allocation +///\param alloc_func - OUT: User's allocate routine +///\param alloc_info - OUT: User's allocation parameters +///\param free_func - OUT: User's free routine +///\param free_info - OUT: User's free parameters +///\exception H5::PropListIException +// Programmer: Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- void DSetMemXferPropList::getVlenMemManager( H5MM_allocate_t& alloc_func, void** alloc_info, H5MM_free_t& free_func, void** free_info ) const { herr_t ret_value = H5Pget_vlen_mem_manager( id, &alloc_func, alloc_info, &free_func, free_info ); diff --git a/c++/src/H5FaccProp.cpp b/c++/src/H5FaccProp.cpp index d2da47d..fc1e0c7 100644 --- a/c++/src/H5FaccProp.cpp +++ b/c++/src/H5FaccProp.cpp @@ -24,6 +24,9 @@ namespace H5 { #endif +//-------------------------------------------------------------------------- +///\brief Constant for default property +//-------------------------------------------------------------------------- const FileAccPropList FileAccPropList::DEFAULT( H5P_DEFAULT ); //-------------------------------------------------------------------------- @@ -78,7 +81,7 @@ hid_t FileAccPropList::getDriver() const //-------------------------------------------------------------------------- // Function: FileAccPropList::setDriver ///\brief Set file driver for this property list -///\param new_driver_id - IN: Name of property to check for +///\param new_driver_id - IN: File driver ///\param new_driver_info - IN: Struct containing the driver-specific properites ///\exception H5::PropListIException ///\par Description diff --git a/c++/src/H5FcreatProp.cpp b/c++/src/H5FcreatProp.cpp index e6b6fb9..657b04b 100644 --- a/c++/src/H5FcreatProp.cpp +++ b/c++/src/H5FcreatProp.cpp @@ -231,9 +231,9 @@ unsigned FileCreatPropList::getIstorek() const } //-------------------------------------------------------------------------- -// Function: FileCreatPropList destructor -///\brief Properly terminates access to this file creation property list. -// Programmer Binh-Minh Ribler - 2000 +// Function: FileCreatPropList destructor +///\brief Noop destructor. +// Programmer Binh-Minh Ribler - 2000 //-------------------------------------------------------------------------- FileCreatPropList::~FileCreatPropList() {} diff --git a/c++/src/H5File.cpp b/c++/src/H5File.cpp index a39d93f..aca787a 100644 --- a/c++/src/H5File.cpp +++ b/c++/src/H5File.cpp @@ -484,22 +484,22 @@ hid_t H5File::getLocId() const //-------------------------------------------------------------------------- // Function: H5File::getFileSize -///\brief Retrieves the file size of the HDF5 file. This function -/// is called after an existing file is opened in order -/// to learn the true size of the underlying file. +///\brief Retrieves the file size of the HDF5 file. ///\exception H5::FileIException +///\return File size +///\par Description +/// This function is called after an existing file is opened in +/// order to learn the true size of the underlying file. // Programmer Raymond Lu - June 24, 2004 //-------------------------------------------------------------------------- haddr_t H5File::getFileSize(void) const { - herr_t ret; - - ret = H5Fget_filesize(id, size); - if( ret < 0 ) + haddr_t file_size = H5Fget_filesize(id); + if( file_size < 0 ) { throw FileIException("H5File::getFileSize", "H5Fget_filesize failed"); } - return ret; + return(file_size); } //-------------------------------------------------------------------------- diff --git a/c++/src/H5File.h b/c++/src/H5File.h index d688e6f..a6f40dd 100644 --- a/c++/src/H5File.h +++ b/c++/src/H5File.h @@ -73,23 +73,24 @@ class H5_DLLCPP H5File : public IdComponent, public CommonFG { DataSpace getRegion(void *ref, H5R_type_t ref_type = H5R_DATASET_REGION) const; // Retrieves the file size of an opened file. - herr_t getFileSize(hsize_t *size) const; + haddr_t getFileSize() const; - // Reopens this file + // Reopens this file. void reopen(); - // Gets the creation property list of this file + // Gets the creation property list of this file. FileCreatPropList getCreatePlist() const; - // Gets the access property list of this file + // Gets the access property list of this file. FileAccPropList getAccessPlist() const; - // Throw file exception + // Throw file exception. virtual void throwException(const string func_name, const string msg) const; - // Used by the API to appropriately close a file + // Used by the API to appropriately close a file. void p_close() const; + // H5File destructor. virtual ~H5File(); private: diff --git a/c++/src/H5IdComponent.cpp b/c++/src/H5IdComponent.cpp index f04039b..7ccb7ff 100644 --- a/c++/src/H5IdComponent.cpp +++ b/c++/src/H5IdComponent.cpp @@ -190,7 +190,7 @@ IdComponent::~IdComponent() { //-------------------------------------------------------------------------- void* IdComponent::p_reference(const char* name, hid_t space_id, H5R_type_t ref_type) const { - void *ref; + void *ref=NULL; herr_t ret_value = H5Rcreate(ref, id, name, ref_type, space_id); if (ret_value < 0) { diff --git a/c++/src/H5Object.cpp b/c++/src/H5Object.cpp index 5050f9d..1d6fd95 100644 --- a/c++/src/H5Object.cpp +++ b/c++/src/H5Object.cpp @@ -285,53 +285,6 @@ void H5Object::flush(H5F_scope_t scope ) const } //-------------------------------------------------------------------------- -// Function: H5Object::Reference -///\brief Creates a reference to an Hdf5 object or to a dataset region. -///\param name - IN: Name of the object to be referenced -///\param dataspace - IN: Dataspace with selection -///\param ref_type - IN: Type of reference; default to \c H5R_DATASET_REGION -///\return A reference -///\exception H5::ReferenceIException -// Programmer Binh-Minh Ribler - May, 2004 -//-------------------------------------------------------------------------- -void* H5Object::Reference(const char* name, DataSpace& dataspace, H5R_type_t ref_type) const -{ - void *ref; - herr_t ret_value = H5Rcreate(ref, id, name, ref_type, dataspace.getId()); - if (ret_value < 0) - { - throw AttributeIException("H5Object::Reference", - "H5Rcreate failed"); - } - return(ref); -} - -//-------------------------------------------------------------------------- -// Function: H5Object::Reference -///\brief This is an overloaded function, provided for your convenience. -/// It differs from the above function in that it only creates -/// a reference to an Hdf5 object, not to a dataset region. -///\param name - IN: Name of the object to be referenced -///\return A reference -///\exception H5::ReferenceIException -///\par Description -// This function passes H5R_OBJECT and -1 to the C API H5Rcreate -// to create a reference to the named object. The next function -// will create a reference to a dataset region. -// Programmer Binh-Minh Ribler - May, 2004 -//-------------------------------------------------------------------------- -void* H5Object::Reference(const char* name) const -{ - void *ref; - herr_t ret_value = H5Rcreate(ref, id, name, H5R_OBJECT, -1); - if (ret_value < 0) - { - throw AttributeIException("H5Object::Reference", - "H5Rcreate failed"); - } - return(ref); -} -//-------------------------------------------------------------------------- // Function: H5Object destructor ///\brief Noop destructor. // Programmer Binh-Minh Ribler - 2000 diff --git a/c++/src/H5PropList.cpp b/c++/src/H5PropList.cpp index 8cc06bf..110ce6d 100644 --- a/c++/src/H5PropList.cpp +++ b/c++/src/H5PropList.cpp @@ -28,6 +28,9 @@ namespace H5 { #endif +//-------------------------------------------------------------------------- +///\brief Constant for default property +//-------------------------------------------------------------------------- const PropList PropList::DEFAULT( H5P_DEFAULT ); //-------------------------------------------------------------------------- @@ -559,8 +562,11 @@ PropList PropList::getClassParent() const return(pclass); } -// The destructor of this instance calls the template resetIdComponent to -// reset its identifier +//-------------------------------------------------------------------------- +// Function: PropList destructor +///\brief Properly terminates access to this property list. +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- PropList::~PropList() { // The property list id will be closed properly -- cgit v0.12