From 02a1c32b1f0a135f64795f7afec0157c18fa5a41 Mon Sep 17 00:00:00 2001 From: Binh-Minh Ribler Date: Sun, 23 May 2004 23:02:58 -0500 Subject: [svn-r8569] Purpose: Add/Correct documentation Description: Added doxygen documentation to: Exception.cpp H5CompType.cpp H5FcreatProp.cpp and corrected some typos in comments for: H5AbstractDs.cpp H5EnumType.cpp H5File.cpp Platforms: SunOS 5.7 (arabica) Linux 2.4 (eirene) --- c++/src/H5AbstractDs.cpp | 1 - c++/src/H5CompType.cpp | 215 ++++++++++++++++++++------- c++/src/H5EnumType.cpp | 2 +- c++/src/H5Exception.cpp | 377 ++++++++++++++++++++++++++++++++++++++++++++--- c++/src/H5FcreatProp.cpp | 124 +++++++++++++++- c++/src/H5FcreatProp.h | 2 +- c++/src/H5File.cpp | 1 + 7 files changed, 640 insertions(+), 82 deletions(-) diff --git a/c++/src/H5AbstractDs.cpp b/c++/src/H5AbstractDs.cpp index 108a847..70b2963 100644 --- a/c++/src/H5AbstractDs.cpp +++ b/c++/src/H5AbstractDs.cpp @@ -94,7 +94,6 @@ DataType AbstractDs::getDataType() const return( datatype ); } -// can be a dataset or an attribute. //-------------------------------------------------------------------------- // Function: AbstractDs::getEnumType ///\brief Returns the enumeration datatype of this abstract dataset which diff --git a/c++/src/H5CompType.cpp b/c++/src/H5CompType.cpp index 05a214e..cbfafb6 100644 --- a/c++/src/H5CompType.cpp +++ b/c++/src/H5CompType.cpp @@ -31,19 +31,49 @@ namespace H5 { #endif -// Creates a new compound datatype -CompType::CompType( size_t size ) : DataType( H5T_COMPOUND, size ) {} - -// Creates a compound datatype using an existing id -CompType::CompType( const hid_t existing_id ) : DataType( existing_id ) {} - -// Default constructor +//-------------------------------------------------------------------------- +// Function: CompType default constructor +///\brief Default constructor: Creates a stub compound datatype +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- CompType::CompType() : DataType() {} -// Copy constructor: makes copy of the original CompType object +//-------------------------------------------------------------------------- +// Function: CompType copy constructor +///\brief Copy constructor: makes copy of the original CompType object +///\param original - IN: Original CompType instance +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- CompType::CompType( const CompType& original ) : DataType( original ) {} -// Gets the compound datatype of the specified dataset - reimplement this +//-------------------------------------------------------------------------- +// Function: CompType overloaded constructor +///\brief Creates a CompType object using the id of an existing datatype. +///\param existing_id - IN: Id of an existing compound datatype +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- +CompType::CompType( const hid_t existing_id ) : DataType( existing_id ) {} + +//-------------------------------------------------------------------------- +// Function: CompType overloaded constructor +///\brief Creates an empty compound datatype given a size, in bytes. +///\param size - IN: Number of bytes in the datatype to create +///\exception H5::DataTypeIException +// Description +// The DataType constructor calls the C API H5Tcreate to create +// the compound datatype. +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- +CompType::CompType( size_t size ) : DataType( H5T_COMPOUND, size ) {} + +//-------------------------------------------------------------------------- +// Function: CompType overloaded constructor +///\brief Gets the compound datatype of the specified dataset. +///\param dataset - IN: Dataset that this enum datatype associates with +///\return CompType instance +///\exception H5::DataTypeIException +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- CompType::CompType( const DataSet& dataset ) : DataType() { // Calls C function H5Dget_type to get the id of the datatype @@ -56,7 +86,13 @@ CompType::CompType( const DataSet& dataset ) : DataType() } } -// Retrieves the number of members in this compound datatype. +//-------------------------------------------------------------------------- +// Function: CompType::getNmembers +///\brief Returns the number of members in this compound datatype. +///\return Number of members +///\exception H5::DataTypeIException +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- int CompType::getNmembers() const { int num_members = H5Tget_nmembers( id ); @@ -68,7 +104,14 @@ int CompType::getNmembers() const return( num_members ); } -// Retrieves the name of a member of this compound datatype. +//-------------------------------------------------------------------------- +// Function: CompType::getMemberName +///\brief Returns the name of a member in this compound datatype. +///\param member_num - IN: Zero-based index of the member +///\return Name of member +///\exception H5::DataTypeIException +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- string CompType::getMemberName( int member_num ) const { char* member_name_C = H5Tget_member_name( id, member_num ); @@ -82,20 +125,18 @@ string CompType::getMemberName( int member_num ) const return( member_name ); // return the member name string } -/*------------------------------------------------------------------------- - * Function: getMemberIndex - * - * Purpose: Returns the index of a member in a compound data type. - * Members are stored in no particular order with numbers 0 - * through N-1, where N is the value returned by the member - * function getNmembers. - * - * Return: Success: index of the member if exists. - * Failure: DataTypeIException - * - * BMR - May 16, 2002 - *------------------------------------------------------------------------- - */ +//-------------------------------------------------------------------------- +// Function: CompType::getMemberIndex +///\brief Returns the index of a member in this compound datatype. +///\param name - IN: Name of the member +///\return Index of member +///\exception H5::DataTypeIException +///\par Description +/// Members are stored in no particular order with numbers 0 +/// through N-1, where N is the value returned by the member +/// function \c CompType::getNmembers. +// Programmer Binh-Minh Ribler - May 16, 2002 +//-------------------------------------------------------------------------- int CompType::getMemberIndex(const char* name) const { int member_index = H5Tget_member_index(id, name); @@ -111,29 +152,25 @@ int CompType::getMemberIndex(const string& name) const return(getMemberIndex(name.c_str())); } -/*------------------------------------------------------------------------- - * Function: getMemberOffset - * - * Purpose: Returns the byte offset of the beginning of a member with - * respect to the beginning of the compound data type datum. - * Members are stored in no particular order with numbers 0 - * through N-1, where N is the value returned by the member - * function getNmembers. - * - * Return: Success: Byte offset. - * Failure: Quincey: for now, 0 is not a failure - * - * BMR - 2000 - *------------------------------------------------------------------------- - */ +//-------------------------------------------------------------------------- +// Function: CompType::getMemberOffset +///\brief Returns the byte offset of the beginning of a member with +/// respect to the beginning of the compound data type datum. +///\param member_num - IN: Zero-based index of the member +///\return Byte offset +///\exception H5::DataTypeIException +// Programmer Binh-Minh Ribler - 2000 +// Description +/// Members are stored in no particular order with numbers 0 +/// through N-1, where N is the value returned by the member +/// function \c CompType::getNmembers. +// +// Note that byte offset being returned as 0 doesn't indicate +// a failure. (According to Quincey) +//-------------------------------------------------------------------------- size_t CompType::getMemberOffset( int member_num ) const { size_t offset = H5Tget_member_offset( id, member_num ); - //if( offset == 0 ) - //{ - //throw DataTypeIException("CompType::getMemberOffset", - //"H5Tget_member_offset failed"); - //} return( offset ); } @@ -145,7 +182,14 @@ int CompType::getMemberDims( int member_num, size_t* dims, int* perm ) const // will complain } -// Gets the type class of the specified member. +//-------------------------------------------------------------------------- +// Function: CompType::getMemberClass +///\brief Gets the type class of the specified member. +///\param member_num - IN: Zero-based index of the member +///\return Type class of the member +///\exception H5::DataTypeIException +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- H5T_class_t CompType::getMemberClass( int member_num ) const { // get the member datatype first @@ -184,37 +228,90 @@ hid_t CompType::p_getMemberType( int member_num ) const } } -// Returns the datatype of the specified member in this compound datatype. +//-------------------------------------------------------------------------- +// Function: CompType::getMemberDataType +///\brief Returns the generic datatype of the specified member in this +/// compound datatype. +///\param member_num - IN: Zero-based index of the member +///\return DataType instance +///\exception H5::DataTypeIException +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- DataType CompType::getMemberDataType( int member_num ) const { DataType datatype( p_getMemberType( member_num )); return( datatype ); } +//-------------------------------------------------------------------------- +// Function: CompType::getMemberDataType +///\brief Returns the enumeration datatype of the specified member in +/// this compound datatype. +///\param member_num - IN: Zero-based index of the member +///\return EnumType instance +///\exception H5::DataTypeIException +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- EnumType CompType::getMemberEnumType( int member_num ) const { EnumType enumtype( p_getMemberType( member_num )); return( enumtype ); } +//-------------------------------------------------------------------------- +// Function: CompType::getMemberDataType +///\brief Returns the compound datatype of the specified member in this +/// compound datatype. +///\param member_num - IN: Zero-based index of the member +///\return CompType instance +///\exception H5::DataTypeIException +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- CompType CompType::getMemberCompType( int member_num ) const { CompType comptype( p_getMemberType( member_num )); return( comptype ); } +//-------------------------------------------------------------------------- +// Function: CompType::getMemberDataType +///\brief Returns the integer datatype of the specified member in this +/// compound datatype. +///\param member_num - IN: Zero-based index of the member +///\return IntType instance +///\exception H5::DataTypeIException +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- IntType CompType::getMemberIntType( int member_num ) const { IntType inttype( p_getMemberType( member_num )); return( inttype ); } +//-------------------------------------------------------------------------- +// Function: CompType::getMemberDataType +///\brief Returns the floating-point datatype of the specified member +/// in this compound datatype. +///\param member_num - IN: Zero-based index of the member +///\return FloatType instance +///\exception H5::DataTypeIException +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- FloatType CompType::getMemberFloatType( int member_num ) const { FloatType floatype( p_getMemberType( member_num )); return( floatype ); } +//-------------------------------------------------------------------------- +// Function: CompType::getMemberDataType +///\brief Returns the string datatype of the specified member in this +/// compound datatype. +///\param member_num - IN: Zero-based index of the member +///\return StrType instance +///\exception H5::DataTypeIException +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- StrType CompType::getMemberStrType( int member_num ) const { StrType strtype( p_getMemberType( member_num )); @@ -224,6 +321,7 @@ StrType CompType::getMemberStrType( int member_num ) const /* old style of getMemberType - using overloads; new style above returns the appropriate datatypes but has different named functions. In the old style, a datatype must be passed into the function. + May, 2004: These should be reconsidered to provide more convenience. // Returns the datatype of the specified member in this compound datatype. // Several overloading of getMemberType are for different datatypes void CompType::getMemberType( int member_num, EnumType& enumtype ) const @@ -253,7 +351,15 @@ void CompType::getMemberType( int member_num, StrType& strtype ) const // end of overloading of getMemberType */ -// Adds a new member to a compound datatype +//-------------------------------------------------------------------------- +// Function: CompType::insertMember +///\brief Inserts a new member to this compound datatype. +///\param name - IN: Name of the new member +///\param offset - IN: Offset in memory structure of the field to insert +///\param new_member - IN: New member to be inserted +///\exception H5::DataTypeIException +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- void CompType::insertMember( const string& name, size_t offset, const DataType& new_member ) const { // Convert string to C-string @@ -270,7 +376,12 @@ void CompType::insertMember( const string& name, size_t offset, const DataType& } } -// Recursively removes padding from within a compound datatype. +//-------------------------------------------------------------------------- +// Function: CompType::pack +///\brief Recursively removes padding from within a compound datatype. +///\exception H5::DataTypeIException +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- void CompType::pack() const { // Calls C routine H5Tpack to remove padding @@ -281,7 +392,11 @@ void CompType::pack() const } } -// This destructor just invokes the base-class' destructor +//-------------------------------------------------------------------------- +// Function: CompType destructor +///\brief Properly terminates access to this compound datatype. +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- CompType::~CompType() {} #ifndef H5_NO_NAMESPACE diff --git a/c++/src/H5EnumType.cpp b/c++/src/H5EnumType.cpp index dae2447..8567a6d 100644 --- a/c++/src/H5EnumType.cpp +++ b/c++/src/H5EnumType.cpp @@ -246,7 +246,7 @@ int EnumType::getNmembers() const } //-------------------------------------------------------------------------- -// Function: EnumType::getMemberIndex +// Function: EnumType::getMemberValue ///\brief Retrieves the value of a member in this enumeration datatype, /// given the member's index. ///\param memb_no - IN: Index of the queried member diff --git a/c++/src/H5Exception.cpp b/c++/src/H5Exception.cpp index 04dca00..0c9c4d7 100644 --- a/c++/src/H5Exception.cpp +++ b/c++/src/H5Exception.cpp @@ -24,45 +24,90 @@ namespace H5 { const string Exception::DEFAULT_MSG("No detailed information provided"); -// Default constructor +//-------------------------------------------------------------------------- +// Function: Exception default constructor +///\brief Default constructor. +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- Exception::Exception() : detailMessage(""), funcName("") {} -// Constructor taking a function name and a detailed message as string objects +//-------------------------------------------------------------------------- +// Function: Exception overloaded constructor +///\brief Creates an exception with a function name where the failure +/// occurs and an optional detailed message +///\param func_name - IN: Name of the function where failure occurs +///\param message - IN: Message on the failure +///\exception H5::DataTypeIException +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- Exception::Exception(const string func_name, const string message) : detailMessage(message), funcName(func_name) {} -// copy constructor +//-------------------------------------------------------------------------- +// Function: Exception copy constructor +///\brief Copy constructor: makes a copy of the original Exception object. +///\param orig - IN: Exception instance to copy +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- Exception::Exception( const Exception& orig ) { detailMessage = orig.detailMessage; funcName = orig.funcName; } -// Returns the character string that describes an error specified by -// a major error number. +//-------------------------------------------------------------------------- +// Function: Exception::getMajorString +///\brief Returns the text string that describes an error +/// specified by a major error number. +///\param err_major - IN: Major error number +///\par Description +/// In the failure case, the string "Invalid major error number" +/// will be returned. +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- string Exception::getMajorString( hid_t err_major ) const { - // calls the C API routine to get the major string - Note: in the - // failure case, the string "Invalid major error number" will be returned. + // calls the C API routine to get the major string char msg[H5E_LEN]; H5Eget_msg(err_major, NULL, msg, H5E_LEN); string major_str(msg); return( major_str ); } -// Returns the character string that describes an error specified by -// a minor error number. +//-------------------------------------------------------------------------- +// Function: Exception::getMinorString +///\brief Returns the text string that describes an error +/// specified by a minor error number. +///\param err_minor - IN: Minor error number +///\par Description +/// In the failure case, the string "Invalid minor error number" +/// will be returned. +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- string Exception::getMinorString( hid_t err_minor ) const { - // calls the C API routine to get the minor string - Note: in the - // failure case, the string "Invalid minor error number" will be returned. + // calls the C API routine to get the minor string char msg[H5E_LEN]; H5Eget_msg(err_minor, NULL, msg, H5E_LEN); string minor_str(msg); return( minor_str ); } -// Turns on the automatic error printing. -void Exception::setAutoPrint( H5E_auto_t func, void* client_data ) +//-------------------------------------------------------------------------- +// Function: Exception::setAutoPrint +///\brief Turns on the automatic error printing. +///\param func - IN: Function to be called upon an error condition +///\param client_data - IN: Data passed to the error function +///\par Description +/// When the library is first initialized the auto printing +/// function is set to the C API \c H5Eprint and \a client_data is +/// the standard error stream pointer, \c stderr. Automatic stack +/// traversal is always in the \c H5E_WALK_DOWNWARD direction. +///\par +/// Users are encouraged to write their own more specific error +/// handlers +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- +void Exception::setAutoPrint( H5E_auto_t& func, void* client_data ) { // calls the C API routine H5Eset_auto to set the auto printing to // the specified function. @@ -71,7 +116,11 @@ void Exception::setAutoPrint( H5E_auto_t func, void* client_data ) throw Exception( "Exception::setAutoPrint", "H5Eset_auto failed" ); } -// Turns off the automatic error printing. +//-------------------------------------------------------------------------- +// Function: Exception::dontPrint +///\brief Turns off the automatic error printing. +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- void Exception::dontPrint() { // calls the C API routine H5Eset_auto with NULL parameters to turn @@ -81,8 +130,22 @@ void Exception::dontPrint() throw Exception( "Exception::dontPrint", "H5Eset_auto failed" ); } -// Retrieves the current settings for the automatic error stack traversal -// function and its data. +//-------------------------------------------------------------------------- +// Function: Exception::getAutoPrint +///\brief Retrieves the current settings for the automatic error +/// stack traversal function and its data. +///\param func - IN: Function to be called upon an error condition +///\param client_data - IN: Data passed to the error function +///\par Description +/// When the library is first initialized the auto printing +/// function is set to the C API \c H5Eprint and \a client_data is +/// the standard error stream pointer, \c stderr. Automatic stack +/// traversal is always in the \c H5E_WALK_DOWNWARD direction. +///\par +/// Users are encouraged to write their own more specific error +/// handlers +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- void Exception::getAutoPrint( H5E_auto_t& func, void** client_data ) { // calls the C API routine H5Eget_auto to get the current setting of @@ -92,7 +155,14 @@ void Exception::getAutoPrint( H5E_auto_t& func, void** client_data ) throw Exception( "Exception::getAutoPrint", "H5Eget_auto failed" ); } -// Clears the error stack for the current thread. +//-------------------------------------------------------------------------- +// Function: Exception::clearErrorStack +///\brief Clears the error stack for the current thread. +///\par Description +/// The stack is also cleared whenever a C API function is +/// called, with certain exceptions (for instance, H5Eprint). +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- void Exception::clearErrorStack() { // calls the C API routine H5Eclear to clear the error stack @@ -101,7 +171,47 @@ void Exception::clearErrorStack() throw Exception( "Exception::clearErrorStack", "H5Eclear failed" ); } -// Walks the error stack for the current thread, calling the specified function. +//-------------------------------------------------------------------------- +// Function: Exception::walkErrorStack +///\brief Walks the error stack for the current thread, calling the +/// specified function. +///\param direction - IN: Direction in which the error stack is to be walked +///\param func - IN: Function to be called for each error encountered +///\param client_data - IN: Data passed to the error function +///\par Description +/// Valid values for \a direction include: +/// \li \c H5E_WALK_UPWARD - begin with the most specific error +/// and end at the API +/// \li \c H5E_WALK_DOWNWARD - begin at the API and end at the +/// inner-most function where the error was first detected +///\par +/// The function specified by \a func will be called for each +/// error in the error stack. The \c H5E_walk_t prototype is as +/// follows: +///\code +/// typedef herr_t (*H5E_walk_t)(int n, H5E_error_t *err_desc, void *client_data) +/// int n - Indexed position of the error in the stack; it begins at zero +/// regardless of stack traversal direction +/// H5E_error_t *err_desc - Pointer to a data structure describing the +/// error. This structure is listed below. +/// void *client_data - Pointer to client data in the format expected by +/// the user-defined function. +///\endcode +///\par +/// Data structure to describe the error: +///\code +/// typedef struct H5E_error_t { +/// hid_t cls_id; //class ID +/// hid_t maj_num; //major error ID +/// hid_t min_num; //minor error number +/// const char *func_name; //function in which error occurred +/// const char *file_name; //file in which error occurred +/// unsigned line; //line in file where error occurs +/// const char *desc; //optional supplied description +/// } H5E_error_t; +///\endcode +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- void Exception::walkErrorStack( H5E_direction_t direction, H5E_walk_t func, void* client_data ) { // calls the C API routine H5Ewalk to walk the error stack @@ -110,28 +220,58 @@ void Exception::walkErrorStack( H5E_direction_t direction, H5E_walk_t func, void throw Exception( "Exception::walkErrorStack", "H5Ewalk failed" ); } -// Returns the detailed message set at the time the exception is thrown +//-------------------------------------------------------------------------- +// Function: Exception::getDetailMsg +///\brief Returns the detailed message set at the time the exception +/// is thrown. +///\return Text message - \c std::string +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- string Exception::getDetailMsg() const { return(detailMessage); } +//-------------------------------------------------------------------------- +// Function: Exception::getCDetailMsg +///\brief Returns the detailed message set at the time the exception +/// is thrown. +///\return Text message - \c char pointer +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- const char* Exception::getCDetailMsg() const { return(detailMessage.c_str()); } -// Returns the function name where the exception is thrown +//-------------------------------------------------------------------------- +// Function: Exception::getFuncName +///\brief Returns the name of the function, where the exception is thrown. +///\return Text message - \c std::string +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- string Exception::getFuncName() const { return(funcName); } + +//-------------------------------------------------------------------------- +// Function: Exception::getCFuncName +///\brief Returns the name of the function, where the exception is thrown. +///\return Text message - \c char pointer +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- const char* Exception::getCFuncName() const { return(funcName.c_str()); } -// Prints the error stack in a default manner. +//-------------------------------------------------------------------------- +// Function: Exception::getCDetailMsg +///\brief Prints the error stack in a default manner. +///\param stream - IN: File pointer +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- void Exception::printError( FILE* stream ) const { herr_t ret_value = H5Eprint( H5E_DEFAULT, stream ); // print to stderr @@ -139,46 +279,241 @@ void Exception::printError( FILE* stream ) const throw Exception( "Exception::printError", "H5Eprint failed" ); } +//-------------------------------------------------------------------------- +// Function: Exception destructor +///\brief Noop destructor +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- Exception::~Exception() {} +//-------------------------------------------------------------------------- +// Subclasses: FileIException +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- +//-------------------------------------------------------------------------- +// Function: FileIException default constructor +///\brief Default constructor. +//-------------------------------------------------------------------------- FileIException::FileIException():Exception(){} +//-------------------------------------------------------------------------- +// Function: FileIException overloaded constructor +///\brief Creates a FileIException with a function name where the failure +/// occurs and an optional detailed message. +///\param func_name - IN: Name of the function where failure occurs +///\param message - IN: Message on the failure +//-------------------------------------------------------------------------- FileIException::FileIException(const string func_name, const string message) : Exception(func_name, message) {} +//-------------------------------------------------------------------------- +// Function: FileIException destructor +///\brief Noop destructor. +//-------------------------------------------------------------------------- FileIException::~FileIException() {} +//-------------------------------------------------------------------------- +// Subclasses: GroupIException +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- +//-------------------------------------------------------------------------- +// Function: GroupIException default constructor +///\brief Default constructor. +//-------------------------------------------------------------------------- GroupIException::GroupIException():Exception(){} +//-------------------------------------------------------------------------- +// Function: GroupIException overloaded constructor +///\brief Creates a GroupIException with a function name where the +/// failure occurs and an optional detailed message. +///\param func_name - IN: Name of the function where failure occurs +///\param message - IN: Message on the failure +//-------------------------------------------------------------------------- GroupIException::GroupIException(const string func_name, const string message) : Exception(func_name, message) {} +//-------------------------------------------------------------------------- +// Function: GroupIException destructor +///\brief Noop destructor. +//-------------------------------------------------------------------------- GroupIException::~GroupIException() {} +//-------------------------------------------------------------------------- +// Subclasses: DataSpaceIException +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- +//-------------------------------------------------------------------------- +// Function: DataSpaceIException default constructor +///\brief Default constructor. +//-------------------------------------------------------------------------- DataSpaceIException::DataSpaceIException():Exception(){} +//-------------------------------------------------------------------------- +// Function: DataSpaceIException overloaded constructor +///\brief Creates a DataSpaceIException with a function name where +/// the failure occurs and an optional detailed message. +///\param func_name - IN: Name of the function where failure occurs +///\param message - IN: Message on the failure +//-------------------------------------------------------------------------- DataSpaceIException::DataSpaceIException(const string func_name, const string message) : Exception(func_name, message) {} +//-------------------------------------------------------------------------- +// Function: DataSpaceIException destructor +///\brief Noop destructor. +//-------------------------------------------------------------------------- DataSpaceIException::~DataSpaceIException() {} +//-------------------------------------------------------------------------- +// Subclasses: DataTypeIException +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- +//-------------------------------------------------------------------------- +// Function: DataTypeIException default constructor +///\brief Default constructor. +//-------------------------------------------------------------------------- DataTypeIException::DataTypeIException():Exception(){} +//-------------------------------------------------------------------------- +// Function: DataTypeIException overloaded constructor +///\brief Creates a DataTypeIException with a function name where the +/// failure occurs and an optional detailed message. +///\param func_name - IN: Name of the function where failure occurs +///\param message - IN: Message on the failure +//-------------------------------------------------------------------------- DataTypeIException::DataTypeIException(const string func_name, const string message) : Exception(func_name, message) {} +//-------------------------------------------------------------------------- +// Function: DataTypeIException destructor +///\brief Noop destructor. +//-------------------------------------------------------------------------- DataTypeIException::~DataTypeIException() {} +//-------------------------------------------------------------------------- +// Subclasses: PropListIException +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- +//-------------------------------------------------------------------------- +// Function: PropListIException default constructor +///\brief Default constructor. +//-------------------------------------------------------------------------- PropListIException::PropListIException():Exception(){} +//-------------------------------------------------------------------------- +// Function: PropListIException overloaded constructor +///\brief Creates a PropListIException with a function name where +/// the failure occurs and an optional detailed message. +///\param func_name - IN: Name of the function where failure occurs +///\param message - IN: Message on the failure +//-------------------------------------------------------------------------- PropListIException::PropListIException(const string func_name, const string message) : Exception(func_name, message) {} +//-------------------------------------------------------------------------- +// Function: PropListIException destructor +///\brief Noop destructor. +//-------------------------------------------------------------------------- PropListIException::~PropListIException() {} +//-------------------------------------------------------------------------- +// Subclasses: DataSetIException +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- +//-------------------------------------------------------------------------- +// Function: DataSetIException default constructor +///\brief Default constructor. +//-------------------------------------------------------------------------- DataSetIException::DataSetIException():Exception(){} +//-------------------------------------------------------------------------- +// Function: DataSetIException overloaded constructor +///\brief Creates a DataSetIException with a function name where +/// the failure occurs and an optional detailed message. +///\param func_name - IN: Name of the function where failure occurs +///\param message - IN: Message on the failure +//-------------------------------------------------------------------------- DataSetIException::DataSetIException(const string func_name, const string message) : Exception(func_name, message) {} +//-------------------------------------------------------------------------- +// Function: DataSetIException destructor +///\brief Noop destructor. +//-------------------------------------------------------------------------- DataSetIException::~DataSetIException() {} +//-------------------------------------------------------------------------- +// Subclasses: AttributeIException +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- +//-------------------------------------------------------------------------- +// Function: AttributeIException default constructor +///\brief Default constructor. +//-------------------------------------------------------------------------- AttributeIException::AttributeIException():Exception(){} +//-------------------------------------------------------------------------- +// Function: AttributeIException overloaded constructor +///\brief Creates a AttributeIException with a function name where +/// the failure occurs and an optional detailed message. +///\param func_name - IN: Name of the function where failure occurs +///\param message - IN: Message on the failure +//-------------------------------------------------------------------------- AttributeIException::AttributeIException(const string func_name, const string message) : Exception(func_name, message) {} +//-------------------------------------------------------------------------- +// Function: AttributeIException destructor +///\brief Noop destructor. +//-------------------------------------------------------------------------- AttributeIException::~AttributeIException() {} +//-------------------------------------------------------------------------- +// Subclasses: ReferenceException +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- +//-------------------------------------------------------------------------- +// Function: ReferenceException default constructor +///\brief Default constructor. +//-------------------------------------------------------------------------- ReferenceException::ReferenceException():Exception(){} +//-------------------------------------------------------------------------- +// Function: ReferenceException overloaded constructor +///\brief Creates a ReferenceException with a function name where +/// the failure occurs and an optional detailed message. +///\param func_name - IN: Name of the function where failure occurs +///\param message - IN: Message on the failure +//-------------------------------------------------------------------------- ReferenceException::ReferenceException(const string func_name, const string message) : Exception(func_name, message) {} +//-------------------------------------------------------------------------- +// Function: ReferenceException destructor +///\brief Noop destructor. +//-------------------------------------------------------------------------- ReferenceException::~ReferenceException() {} +//-------------------------------------------------------------------------- +// Subclasses: LibraryIException +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- +//-------------------------------------------------------------------------- +// Function: LibraryIException default constructor +///\brief Default constructor. +//-------------------------------------------------------------------------- LibraryIException::LibraryIException():Exception(){} +//-------------------------------------------------------------------------- +// Function: LibraryIException overloaded constructor +///\brief Creates a LibraryIException with a function name where +/// the failure occurs and an optional detailed message. +///\param func_name - IN: Name of the function where failure occurs +///\param message - IN: Message on the failure +//-------------------------------------------------------------------------- LibraryIException::LibraryIException(const string func_name, const string message) : Exception(func_name, message) {} +//-------------------------------------------------------------------------- +// Function: LibraryIException destructor +///\brief Noop destructor. +//-------------------------------------------------------------------------- LibraryIException::~LibraryIException() {} +//-------------------------------------------------------------------------- +// Subclasses: IdComponentException +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- +//-------------------------------------------------------------------------- +// Function: IdComponentException default constructor +///\brief Default constructor. +//-------------------------------------------------------------------------- IdComponentException::IdComponentException(): Exception() {} +//-------------------------------------------------------------------------- +// Function: IdComponentException overloaded constructor +///\brief Creates a IdComponentException with a function name where +/// the failure occurs and an optional detailed message. +///\param func_name - IN: Name of the function where failure occurs +///\param message - IN: Message on the failure +//-------------------------------------------------------------------------- IdComponentException::IdComponentException(const string func_name, const string message) : Exception(func_name, message) {} +//-------------------------------------------------------------------------- +// Function: IdComponentException destructor +///\brief Noop destructor. +//-------------------------------------------------------------------------- IdComponentException::~IdComponentException() {} #ifndef H5_NO_NAMESPACE diff --git a/c++/src/H5FcreatProp.cpp b/c++/src/H5FcreatProp.cpp index 6c95905..fe0950e 100644 --- a/c++/src/H5FcreatProp.cpp +++ b/c++/src/H5FcreatProp.cpp @@ -25,18 +25,41 @@ namespace H5 { #endif +//-------------------------------------------------------------------------- +///\brief Constant for default property +//-------------------------------------------------------------------------- const FileCreatPropList FileCreatPropList::DEFAULT( H5P_DEFAULT ); -// Creates a file create property list +//-------------------------------------------------------------------------- +// Function: FileCreatPropList default constructor +///\brief Default constructor: Creates a file create property list +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- FileCreatPropList::FileCreatPropList() : PropList( H5P_FILE_CREATE ) {} -// Copy constructor: makes a copy of the original FileCreatPropList object; -FileCreatPropList::FileCreatPropList( const FileCreatPropList& orig ) : PropList( orig ) {} - -void FileCreatPropList::getVersion( - unsigned& boot, unsigned& freelist, unsigned& stab, unsigned& shhdr ) const +//-------------------------------------------------------------------------- +// Function: FileCreatPropList copy constructor +///\brief Copy constructor: makes a copy of the original FileCreatPropList object. +///\param original - IN: FileCreatPropList instance to copy +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- +FileCreatPropList::FileCreatPropList( const FileCreatPropList& original ) : PropList( original ) {} + +//-------------------------------------------------------------------------- +// Function: FileCreatPropList::getVersion +///\brief Retrieves version information for various parts of a file. +///\param super - OUT: The file super block. +///\param freelist - OUT: The global free list. +///\param stab - OUT: The root symbol table entry. +///\param shhdr - OUT: Shared object headers. +///\exception H5::PropListIException +///\par Description +/// Any (or even all) of the output arguments can be null pointers. +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- +void FileCreatPropList::getVersion(unsigned& super, unsigned& freelist, unsigned& stab, unsigned& shhdr) const { - herr_t ret_value = H5Pget_version( id, &boot, &freelist, &stab, &shhdr ); + herr_t ret_value = H5Pget_version( id, &super, &freelist, &stab, &shhdr ); if( ret_value < 0 ) { throw PropListIException("FileCreatPropList::getVersion", @@ -44,6 +67,16 @@ void FileCreatPropList::getVersion( } } +//-------------------------------------------------------------------------- +// Function: FileCreatPropList::setUserblock +///\brief Sets the user block size field of this file creation property list. +///\param size - IN: User block size to be set, in bytes +///\exception H5::PropListIException +///\par Description +/// The default user block size is 0; it may be set to any power +/// of 2 equal to 512 or greater (512, 1024, 2048, etc.) +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- void FileCreatPropList::setUserblock( hsize_t size ) const { herr_t ret_value = H5Pset_userblock( id, size); @@ -54,6 +87,13 @@ void FileCreatPropList::setUserblock( hsize_t size ) const } } +//-------------------------------------------------------------------------- +// Function: FileCreatPropList::getUserblock +///\brief Returns the user block size of this file creation property list. +///\return User block size +///\exception H5::PropListIException +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- hsize_t FileCreatPropList::getUserblock() const { hsize_t userblock_size; @@ -66,6 +106,19 @@ hsize_t FileCreatPropList::getUserblock() const return( userblock_size ); } +//-------------------------------------------------------------------------- +// Function: FileCreatPropList::setSizes +///\brief Sets the byte size of the offsets and lengths used to +/// address objects in an HDF5 file. +///\param sizeof_addr - IN: Size of an object offset in bytes +///\param sizeof_size - IN: Size of an object length in bytes. +///\exception H5::PropListIException +///\par Description +/// For information on setting sizes, please refer to the +/// C layer Reference Manual at: +/// http://hdf.ncsa.uiuc.edu/HDF5/doc/RM_H5P.html#Property-SetSizes +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- void FileCreatPropList::setSizes( size_t sizeof_addr, size_t sizeof_size ) const { herr_t ret_value = H5Pset_sizes( id, sizeof_addr, sizeof_size ); @@ -76,6 +129,13 @@ void FileCreatPropList::setSizes( size_t sizeof_addr, size_t sizeof_size ) const } } +//-------------------------------------------------------------------------- +// Function: FileCreatPropList::getSizes +///\brief Retrieves the size of the offsets and lengths used in an +/// HDF5 file. +///\exception H5::PropListIException +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- void FileCreatPropList::getSizes( size_t& sizeof_addr, size_t& sizeof_size ) const { herr_t ret_value = H5Pget_sizes( id, &sizeof_addr, &sizeof_size ); @@ -86,6 +146,18 @@ void FileCreatPropList::getSizes( size_t& sizeof_addr, size_t& sizeof_size ) con } } +//-------------------------------------------------------------------------- +// Function: FileCreatPropList::setSymk +///\brief Sets the size of parameters used to control the symbol table +/// nodes. +///\param ik - IN: Symbol table tree rank +///\param lk - IN: Symbol table node size +///\exception H5::PropListIException +///\par Description +/// For information, please see the C layer Reference Manual at: +/// http://hdf.ncsa.uiuc.edu/HDF5/doc/RM_H5P.html#Property-SetSymK +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- void FileCreatPropList::setSymk( unsigned ik, unsigned lk ) const { herr_t ret_value = H5Pset_sym_k( id, ik, lk ); @@ -96,6 +168,16 @@ void FileCreatPropList::setSymk( unsigned ik, unsigned lk ) const } } +//-------------------------------------------------------------------------- +// Function: FileCreatPropList::getSymk +///\brief Retrieves the size of the symbol table B-tree 1/2 rank and +/// the symbol table leaf node 1/2 size. +///\exception H5::PropListIException +///\par Description +/// For information, please see +/// http://hdf.ncsa.uiuc.edu/HDF5/doc/RM_H5P.html#Property-SetSymK +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- void FileCreatPropList::getSymk( unsigned& ik, unsigned& lk ) const { herr_t ret_value = H5Pget_sym_k( id, &ik, &lk ); @@ -106,6 +188,17 @@ void FileCreatPropList::getSymk( unsigned& ik, unsigned& lk ) const } } +//-------------------------------------------------------------------------- +// Function: FileCreatPropList::setIstorek +///\brief Sets the size of the parameter used to control the B-trees +/// for indexing chunked datasets. +///\param ik - IN: 1/2 rank of chunked storage B-tree +///\exception H5::PropListIException +///\par Description +/// For information, please see the C layer Reference Manual at: +/// http://hdf.ncsa.uiuc.edu/HDF5/doc/RM_H5P.html#Property-SetIstoreK +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- void FileCreatPropList::setIstorek( unsigned ik ) const { herr_t ret_value = H5Pset_istore_k( id, ik ); @@ -115,6 +208,17 @@ void FileCreatPropList::setIstorek( unsigned ik ) const "H5Pset_istore_k failed"); } } + +//-------------------------------------------------------------------------- +// Function: FileCreatPropList::getIstorek +///\brief Returns the 1/2 rank of an indexed storage B-tree. +///\return 1/2 rank of chunked storage B-tree +///\exception H5::PropListIException +///\par Description +/// For information, please see +/// http://hdf.ncsa.uiuc.edu/HDF5/doc/RM_H5P.html#Property-SetIstoreK +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- unsigned FileCreatPropList::getIstorek() const { unsigned ik; @@ -127,7 +231,11 @@ unsigned FileCreatPropList::getIstorek() const return( ik ); } -// Default destructor +//-------------------------------------------------------------------------- +// Function: FileCreatPropList destructor +///\brief Properly terminates access to this file creation property list. +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- FileCreatPropList::~FileCreatPropList() {} #ifndef H5_NO_NAMESPACE diff --git a/c++/src/H5FcreatProp.h b/c++/src/H5FcreatProp.h index bd6a413..4ac4b10 100644 --- a/c++/src/H5FcreatProp.h +++ b/c++/src/H5FcreatProp.h @@ -32,7 +32,7 @@ class H5_DLLCPP FileCreatPropList : public PropList { FileCreatPropList( const FileCreatPropList& orig ); // Retrieves version information for various parts of a file. - void getVersion( unsigned& boot, unsigned& freelist, unsigned& stab, unsigned& shhdr ) const; + void getVersion( unsigned& super, unsigned& freelist, unsigned& stab, unsigned& shhdr ) const; // Sets the userblock size field of a file creation property list. void setUserblock( hsize_t size ) const; diff --git a/c++/src/H5File.cpp b/c++/src/H5File.cpp index fdf7561..b87dd33 100644 --- a/c++/src/H5File.cpp +++ b/c++/src/H5File.cpp @@ -138,6 +138,7 @@ void H5File::getFile( const char* name, unsigned int flags, const FileCreatPropL // Function: Copy Constructor ///\brief Copy Constructor: Makes a copy of the original /// H5File object +///\param original - IN: H5File instance to copy // Programmer Binh-Minh Ribler - 2000 //-------------------------------------------------------------------------- H5File::H5File( const H5File& original ) : IdComponent( original ) {} -- cgit v0.12