diff options
Diffstat (limited to 'c++/src/H5DcreatProp.cpp')
| -rw-r--r-- | c++/src/H5DcreatProp.cpp | 467 |
1 files changed, 430 insertions, 37 deletions
diff --git a/c++/src/H5DcreatProp.cpp b/c++/src/H5DcreatProp.cpp index efaf30d..6fc445f 100644 --- a/c++/src/H5DcreatProp.cpp +++ b/c++/src/H5DcreatProp.cpp @@ -29,13 +29,33 @@ namespace H5 { const DSetCreatPropList DSetCreatPropList::DEFAULT( H5P_DEFAULT ); -// Creates a dataset creation property list +//-------------------------------------------------------------------------- +// Function: Default Constructor +///\brief Default Constructor: Creates a dataset creation property list +//-------------------------------------------------------------------------- DSetCreatPropList::DSetCreatPropList() : PropList( H5P_DATASET_CREATE) {} -// Copy constructor: makes a copy of the original DSetCreatPropList object; +//-------------------------------------------------------------------------- +// Function: Copy Constructor +///\brief Copy Constructor: Makes a copy of the original +/// DSetCreatPropList object +//-------------------------------------------------------------------------- DSetCreatPropList::DSetCreatPropList( const DSetCreatPropList& orig ) : PropList( orig ) {} -// Sets the size of the chunks used to store a chunked layout dataset. +//-------------------------------------------------------------------------- +// Function: DSetCreatPropList::setChunk +///\brief Sets the size of the chunks used to store a chunked layout +/// dataset. +///\param ndims - IN: Number of dimensions of each chunk +///\param dim - IN: Array containing the size of each chunk +///\exception H5::PropListIException +///\par Description +/// The \a ndims parameter currently must have the same value as +/// the rank of the dataset. The values of the \a dim array +/// define the size of the chunks to store the dataset's raw +/// data. As a side-effect, the layout of the dataset will be +/// changed to \c H5D_CHUNKED, if it is not so already. +//-------------------------------------------------------------------------- void DSetCreatPropList::setChunk( int ndims, const hsize_t* dim ) const { herr_t ret_value = H5Pset_chunk( id, ndims, dim ); @@ -45,20 +65,14 @@ void DSetCreatPropList::setChunk( int ndims, const hsize_t* dim ) const } } -// Gets the layout of the raw data storage of the data that uses this -// property list -H5D_layout_t DSetCreatPropList::getLayout() const -{ - H5D_layout_t layout = H5Pget_layout( id ); - if( layout == H5D_LAYOUT_ERROR ) - { - throw PropListIException("DSetCreatPropList::getLayout", - "H5Pget_layout returns H5D_LAYOUT_ERROR"); - } - return( layout ); -} - -// Retrieves the size of the chunks used to store a chunked layout dataset. +//-------------------------------------------------------------------------- +// Function: DSetCreatPropList::getChunk +///\brief Retrieves the size of the chunks used to store a chunked +/// layout dataset. +///\param max_ndims - IN: Size of \a dim array +///\param dim - OUT: Array to store the chunk dimensions +///\exception H5::PropListIException +//-------------------------------------------------------------------------- int DSetCreatPropList::getChunk( int max_ndims, hsize_t* dim ) const { int chunk_size = H5Pget_chunk( id, max_ndims, dim ); @@ -70,7 +84,16 @@ int DSetCreatPropList::getChunk( int max_ndims, hsize_t* dim ) const return( chunk_size ); } -// Sets the type of storage used store the raw data for a dataset. +//-------------------------------------------------------------------------- +// Function: DSetCreatPropList::setLayout +///\brief Sets the type of storage used store the raw data for a dataset. +///\param plist - IN: Property list id, here by mistake, should be removed +///\param layout - IN: Type of storage layout for raw data +///\exception H5::PropListIException +///\par Description +/// For information on setting layout type, please refer to +/// http://hdf.ncsa.uiuc.edu/HDF5/doc/RM_H5P.html#Property-SetLayout +//-------------------------------------------------------------------------- void DSetCreatPropList::setLayout(hid_t plist, H5D_layout_t layout ) const { herr_t ret_value = H5Pset_layout( id, layout ); @@ -81,7 +104,43 @@ void DSetCreatPropList::setLayout(hid_t plist, H5D_layout_t layout ) const } } -// Sets compression method and compression level +//-------------------------------------------------------------------------- +// Function: DSetCreatPropList::getLayout +///\brief Retrieves the layout type of this property list +///\return Layout type, which can be: +/// \li \c H5D_COMPACT - raw data is stored in the object +/// header in the file. +/// \li \c H5D_CONTIGUOUS - raw data is stored separately from the +/// object header in one contiguous chunk in +/// the file. +/// \li \c H5D_CHUNKED - raw data is stored separately from the +/// object header in chunks in separate locations +/// in the file. +///\exception H5::PropListIException +///\par Description +//-------------------------------------------------------------------------- +H5D_layout_t DSetCreatPropList::getLayout() const +{ + H5D_layout_t layout = H5Pget_layout( id ); + if( layout == H5D_LAYOUT_ERROR ) + { + throw PropListIException("DSetCreatPropList::getLayout", + "H5Pget_layout returns H5D_LAYOUT_ERROR"); + } + return( layout ); +} + +//-------------------------------------------------------------------------- +// Function: DSetCreatPropList::setDeflate +///\brief Sets compression method and compression level +///\param level - IN: Compression level, should [0..9], inclusive +///\exception H5::PropListIException +///\par Description +/// The function sets the compression method for this property +/// list to \c H5D_COMPRESS_DEFLATE and the compression level to +/// \a level. Lower compression levels are faster but result in +/// less compression. +//-------------------------------------------------------------------------- void DSetCreatPropList::setDeflate( int level ) const { herr_t ret_value = H5Pset_deflate( id, level ); @@ -92,7 +151,23 @@ void DSetCreatPropList::setDeflate( int level ) const } } -// Sets a dataset fill value +//-------------------------------------------------------------------------- +// 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 +///\exception H5::PropListIException +///\par Description +/// The datatype may differ from that of the dataset, but it must +/// be one that the HDF5 library is able to convert \a value to +/// the dataset datatype when the dataset is created. +/// The default fill value is 0 (zero,) which is interpreted +/// according to the actual dataset datatype. +///\par +/// For information on setting fill value, please refer to the +/// C layer Reference Manual at: +/// http://hdf.ncsa.uiuc.edu/HDF5/doc/RM_H5P.html#Property-SetFillValue +//-------------------------------------------------------------------------- void DSetCreatPropList::setFillValue( const DataType& fvalue_type, const void* value ) const { herr_t ret_value = H5Pset_fill_value( id, fvalue_type.getId(), value ); @@ -103,7 +178,18 @@ void DSetCreatPropList::setFillValue( const DataType& fvalue_type, const void* v } } -// Retrieves a dataset fill value +//-------------------------------------------------------------------------- +// 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 +///\exception H5::PropListIException +///\par Description +/// The fill value is returned through \a value pointer +/// and the memory is allocated by the caller. The fill +/// value will be converted from its current data type to the +/// specified by \a fvalue_type. +//-------------------------------------------------------------------------- void DSetCreatPropList::getFillValue( const DataType& fvalue_type, void* value ) const { herr_t ret_value = H5Pget_fill_value( id, fvalue_type.getId(), value ); @@ -114,10 +200,50 @@ void DSetCreatPropList::getFillValue( const DataType& fvalue_type, void* value ) } } -// Adds a filter to the filter pipeline -void DSetCreatPropList::setFilter( H5Z_filter_t filter, unsigned int flags, size_t cd_nelmts, const unsigned int cd_values[] ) const +//-------------------------------------------------------------------------- +// Function: DSetCreatPropList::isFillValueDefined +///\brief Check if fill value has been defined for this property +///\return +/// \li \c H5D_FILL_VALUE_UNDEFINED =0, +/// \li \c H5D_FILL_VALUE_DEFAULT =1, +/// \li \c H5D_FILL_VALUE_USER_DEFINED =2 +///\exception H5::PropListIException +//-------------------------------------------------------------------------- +H5D_fill_value_t DSetCreatPropList::isFillValueDefined() { - herr_t ret_value = H5Pset_filter( id, filter, flags, cd_nelmts, cd_values ); + H5D_fill_value_t status; + herr_t ret_value = H5Pfill_value_defined(id, &status); + if( ret_value < 0 ) + { + throw PropListIException("DSetCreatPropList::isFillValueDefined", + "H5Pfill_value_defined returned H5D_FILL_VALUE_ERROR (-1)"); + } + else + return (status); +} + +//-------------------------------------------------------------------------- +// Function: DSetCreatPropList::setFilter +///\brief Adds a filter to the filter pipeline +///\param filter_id - IN: Filter to add +///\param flags - IN: Specifies general properties of the filter +///\param cd_nelmts - IN: Number of elements in cd_values +///\param cd_values - IN: Auxiliary data for the filter +///\exception H5::PropListIException +///\par Description +/// The \a flags argument is a bit vector of the field: +/// \c H5Z_FLAG_OPTIONAL(0x0001) +///\par +/// If this bit is set then the filter is optional. If the filter +/// fails during a \c DataSet::write() operation then the filter +/// is just excluded from the pipeline for the chunk for which it +/// failed; the filter will not participate in the pipeline +/// during a \c DataSet::read() of the chunk. If this bit is clear +/// and the filter fails then the entire I/O operation fails. +//-------------------------------------------------------------------------- +void DSetCreatPropList::setFilter( H5Z_filter_t filter_id, unsigned int flags, size_t cd_nelmts, const unsigned int cd_values[] ) const +{ + herr_t ret_value = H5Pset_filter( id, filter_id, flags, cd_nelmts, cd_values ); if( ret_value < 0 ) { throw PropListIException("DSetCreatPropList::setFilter", @@ -125,10 +251,18 @@ void DSetCreatPropList::setFilter( H5Z_filter_t filter, unsigned int flags, size } } -// Removes one or more filters to the filter pipeline -void DSetCreatPropList::removeFilter( H5Z_filter_t filter) const +//-------------------------------------------------------------------------- +// Function: DSetCreatPropList::removeFilter +///\brief Removes one or more filters +///\param filter_id - IN: Filter to remove +///\exception H5::PropListIException +///\par Description +/// Deletes a filter from the dataset creation property list; +/// deletes all filters if \a filter_id is \c H5Z_FILTER_NONE. +//-------------------------------------------------------------------------- +void DSetCreatPropList::removeFilter(H5Z_filter_t filter_id) const { - herr_t ret_value = H5Premove_filter( id, filter); + herr_t ret_value = H5Premove_filter( id, filter_id); if( ret_value < 0 ) { throw PropListIException("DSetCreatPropList::removeFilter", @@ -136,7 +270,12 @@ void DSetCreatPropList::removeFilter( H5Z_filter_t filter) const } } -// Returns the number of filters in the pipeline +//-------------------------------------------------------------------------- +// Function: DSetCreatPropList::getNfilters +///\brief Returns the number of filters in the pipeline +///\return Number of filters +///\exception H5::PropListIException +//-------------------------------------------------------------------------- int DSetCreatPropList::getNfilters() const { int num_filters = H5Pget_nfilters( id ); @@ -149,22 +288,251 @@ int DSetCreatPropList::getNfilters() const return( num_filters ); } -// Returns information about a filter in a pipeline -H5Z_filter_t DSetCreatPropList::getFilter( int filter_number, unsigned int& flags, size_t& cd_nelmts, unsigned int* cd_values, size_t namelen, char name[] ) 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 +///\return Filter id +///\exception H5::PropListIException +///\par Description +/// Failure occurs when \a filter_number is out of range. +//-------------------------------------------------------------------------- +H5Z_filter_t DSetCreatPropList::getFilter(int filter_number, unsigned int &flags, size_t &cd_nelmts, unsigned int* cd_values, size_t namelen, char name[]) const { - H5Z_filter_t filter; - filter = H5Pget_filter( id, filter_number, &flags, &cd_nelmts, + H5Z_filter_t filter_id; + filter_id = H5Pget_filter( id, filter_number, &flags, &cd_nelmts, cd_values, namelen, name ); - if( filter == H5Z_FILTER_ERROR ) + if( filter_id == H5Z_FILTER_ERROR ) { throw PropListIException("DSetCreatPropList::getFilter", "H5Pget_filter returned H5Z_FILTER_ERROR"); } else - return( filter ); + return(filter_id); +} + +//-------------------------------------------------------------------------- +// 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 +///\exception H5::PropListIException +//-------------------------------------------------------------------------- +void DSetCreatPropList::getFilterById(H5Z_filter_t filter_id, unsigned int &flags, size_t &cd_nelmts, unsigned int* cd_values, size_t namelen, char name[]) const +{ + herr_t ret_value = H5Pget_filter_by_id(id, filter_id, &flags, &cd_nelmts, + cd_values, namelen, name ); + if (ret_value < 0) + { + throw PropListIException("DSetCreatPropList::getFilterById", + "H5Pget_filter_by_id failed"); + } +} + +//-------------------------------------------------------------------------- +// Function: DSetCreatPropList::modifyFilter +///\brief Modifies the specified filter +///\param filter_id - IN: Filter to get +///\param flags - OUT: General properties of the filter +///\param cd_nelmts - IN: Number of elements in \a cd_values +/// \n OUT: Number of values defined by the filter +///\param cd_values - OUT: Array to hold the data; allocated by the user +///\exception H5::PropListIException +///\par Description +/// The \a flags argument is a bit vector of the field: +/// \c H5Z_FLAG_OPTIONAL(0x0001) +///\par +/// If this bit is set then the filter is optional. If the filter +/// fails during a DataSet::write() operation then the filter +/// is just excluded from the pipeline for the chunk for which it +/// failed; the filter will not participate in the pipeline +/// during a DataSet::read() of the chunk. If this bit is clear +/// and the filter fails then the entire I/O operation fails. +//-------------------------------------------------------------------------- +void DSetCreatPropList::modifyFilter( H5Z_filter_t filter_id, unsigned int flags, size_t cd_nelmts, const unsigned int cd_values[] ) const +{ + herr_t ret_value = H5Pmodify_filter(id, filter_id, flags, cd_nelmts, cd_values); + if( ret_value < 0 ) + { + throw PropListIException("DSetCreatPropList::modifyFilter", + "H5Pmodify_filter failed"); + } +} + +//-------------------------------------------------------------------------- +// Function: DSetCreatPropList::allFiltersAvail +///\brief Queries whether all the filters set in this property list +/// are available currently. +///\return true if all filters available, and false if one or more +/// filters not currently available +///\exception H5::PropListIException +//-------------------------------------------------------------------------- +bool DSetCreatPropList::allFiltersAvail() +{ + htri_t ret_value = H5Pall_filters_avail(id); + if( ret_value > 0 ) + return true; + else if( ret_value == 0 ) + return false; + else // Raise exception when H5Pall_filters_avail returns a negative value + { + throw PropListIException("DSetCreatPropList::allFiltersAvail", "H5Pall_filters_avail returned negative value"); + } +} + +//-------------------------------------------------------------------------- +// Function: DSetCreatPropList::setShuffle +///\brief Sets method of the shuffle filter +///\exception H5::PropListIException +///\par Description +/// Please refer to the Reference Manual of \c H5Pset_shuffle for +/// details. +/// http://hdf.ncsa.uiuc.edu/HDF5/doc/RM_H5P.html#Property-SetShuffle +//-------------------------------------------------------------------------- +void DSetCreatPropList::setShuffle() +{ + herr_t ret_value = H5Pset_shuffle(id); + if( ret_value < 0 ) + { + throw PropListIException("DSetCreatPropList::setShuffle", + "H5Pset_shuffle failed"); + } +} + +//-------------------------------------------------------------------------- +// Function: DSetCreatPropList::getAllocTime +///\brief Get space allocation time for this property. +///\return Space allocation time. +///\exception H5::PropListIException +///\par Description +/// The values of space allocation time can be one of the +/// followings: +/// \li \c H5D_ALLOC_TIME_DEFAULT +/// \li \c H5D_ALLOC_TIME_EARLY +/// \li \c H5D_ALLOC_TIME_LATE +/// \li \c H5D_ALLOC_TIME_INCR +//-------------------------------------------------------------------------- +H5D_alloc_time_t DSetCreatPropList::getAllocTime() +{ + H5D_alloc_time_t alloc_time; + herr_t ret_value = H5Pget_alloc_time(id, &alloc_time); + if( ret_value < 0 ) + { + throw PropListIException("DSetCreatPropList::getAllocTime", + "H5Pget_alloc_time failed"); + } + else + return (alloc_time); +} + +//-------------------------------------------------------------------------- +// Function: DSetCreatPropList::getFillTime +///\brief Gets fill value writing time. +///\return Fill value writing time +///\exception H5::PropListIException +///\par Description +/// Valid values for fill value writing time include +/// \li \c H5D_FILL_TIME_NEVER +/// \li \c H5D_FILL_TIME_ALLOC. +//-------------------------------------------------------------------------- +H5D_fill_time_t DSetCreatPropList::getFillTime() +{ + H5D_fill_time_t fill_time; + herr_t ret_value = H5Pget_fill_time(id, &fill_time); + if( ret_value < 0 ) + { + throw PropListIException("DSetCreatPropList::getFillTime", + "H5Pget_fill_time failed"); + } + else + return (fill_time); +} + +//-------------------------------------------------------------------------- +// Function: DSetCreatPropList::setAllocTime +///\brief Sets space allocation time for dataset during creation. +///\param alloc_time - IN: Allocation time +///\exception H5::PropListIException +///\par Description +/// Valid values for space allocation time include: +/// \li \c H5D_ALLOC_TIME_DEFAULT +/// \li \c H5D_ALLOC_TIME_EARLY +/// \li \c H5D_ALLOC_TIME_LATE +/// \li \c H5D_ALLOC_TIME_INCR +//-------------------------------------------------------------------------- +void DSetCreatPropList::setAllocTime(H5D_alloc_time_t alloc_time) +{ + herr_t ret_value = H5Pset_alloc_time(id, alloc_time); + if( ret_value < 0 ) + { + throw PropListIException("DSetCreatPropList::setAllocTime", + "H5Pset_alloc_time failed"); + } +} + +//-------------------------------------------------------------------------- +// Function: DSetCreatPropList::setFillTime +///\brief Sets fill value writing time for dataset. +///\return Fill value writing time +///\exception H5::PropListIException +///\par Description +/// Valid values for fill value writing time include +/// \li \c H5D_FILL_TIME_NEVER +/// \li \c H5D_FILL_TIME_ALLOC. +//-------------------------------------------------------------------------- +void DSetCreatPropList::setFillTime(H5D_fill_time_t fill_time) +{ + herr_t ret_value = H5Pset_fill_time(id, fill_time); + if( ret_value < 0 ) + { + throw PropListIException("DSetCreatPropList::setFillTime", + "H5Pset_fill_time failed"); + } +} + +//-------------------------------------------------------------------------- +// Function: DSetCreatPropList::setFletcher32 +///\brief Sets Fletcher32 checksum of EDC for this property list. +///\exception H5::PropListIException +//-------------------------------------------------------------------------- +void DSetCreatPropList::setFletcher32() +{ + herr_t ret_value = H5Pset_fletcher32(id); + if( ret_value < 0 ) + { + throw PropListIException("DSetCreatPropList::setFletcher32", + "H5Pset_fletcher32 failed"); + } } -// Adds an external file to the list of external files +//-------------------------------------------------------------------------- +// Function: DSetCreatPropList::setExternal +///\brief Adds an external file to the list of external files +///\param name - IN: Name of the external file +///\param offset - IN: Location where the data starts in the file +///\param size - IN: Number of bytes reserved in the file for the data +///\exception H5::PropListIException +///\par Description +/// If a dataset is splitted across multiple files then the files +/// should be defined in order. The total size of the dataset is +/// the sum of the \a size arguments for all the external files. If +/// the total size is larger than the size of a dataset then the +/// dataset can be extended (provided the data space also allows +/// the extending). +//-------------------------------------------------------------------------- void DSetCreatPropList::setExternal( const char* name, off_t offset, hsize_t size ) const { herr_t ret_value = H5Pset_external( id, name, offset, size ); @@ -175,7 +543,12 @@ void DSetCreatPropList::setExternal( const char* name, off_t offset, hsize_t siz } } -// Returns the number of external files for a dataset +//-------------------------------------------------------------------------- +// Function: DSetCreatPropList::getExternalCount +///\brief Returns the number of external files for a dataset +///\return Number of external files +///\exception H5::PropListIException +//-------------------------------------------------------------------------- int DSetCreatPropList::getExternalCount() const { int num_ext_files = H5Pget_external_count( id ); @@ -188,7 +561,27 @@ int DSetCreatPropList::getExternalCount() const return( num_ext_files ); } -// Returns information about an external file +//-------------------------------------------------------------------------- +// 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 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 +///\exception H5::PropListIException +///\par Description +/// The parameter \a idx ranges [0..N-1] where N is returned by +/// getExternalCount(). At most \a name_size characters are copied +/// into the name array. If the external file name is longer than +/// name_size with the null terminator, the return value is not +/// null terminated (similar to strncpy()). +/// If \a name_size is zero or \a name is a null pointer, the +/// external file name will not be returned. If \a offset or +/// \a size are null pointers then the corresponding information +/// will not be returned. +//-------------------------------------------------------------------------- void DSetCreatPropList::getExternal( int idx, size_t name_size, char* name, off_t& offset, hsize_t& size ) const { herr_t ret_value = H5Pget_external( id, idx, name_size, name, &offset, &size ); |