summaryrefslogtreecommitdiffstats
path: root/c++/src
diff options
context:
space:
mode:
authorBinh-Minh Ribler <bmribler@hdfgroup.org>2004-05-24 04:02:58 (GMT)
committerBinh-Minh Ribler <bmribler@hdfgroup.org>2004-05-24 04:02:58 (GMT)
commit02a1c32b1f0a135f64795f7afec0157c18fa5a41 (patch)
tree707525f6e3efa32b777a59559cd857e2c2d1ff79 /c++/src
parent53114fe05593c5ec19858759724ddfed5b4f9310 (diff)
downloadhdf5-02a1c32b1f0a135f64795f7afec0157c18fa5a41.zip
hdf5-02a1c32b1f0a135f64795f7afec0157c18fa5a41.tar.gz
hdf5-02a1c32b1f0a135f64795f7afec0157c18fa5a41.tar.bz2
[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)
Diffstat (limited to 'c++/src')
-rw-r--r--c++/src/H5AbstractDs.cpp1
-rw-r--r--c++/src/H5CompType.cpp215
-rw-r--r--c++/src/H5EnumType.cpp2
-rw-r--r--c++/src/H5Exception.cpp377
-rw-r--r--c++/src/H5FcreatProp.cpp124
-rw-r--r--c++/src/H5FcreatProp.h2
-rw-r--r--c++/src/H5File.cpp1
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 ) {}