HDF5 C++ API Reference Manual

 

 

 

H5::Exception Class Reference

#include <H5Exception.h>

Inheritance diagram for H5::Exception:

List of all members.

Public Member Functions
	Exception (const H5std_string &func_name, const H5std_string &message=DEFAULT_MSG)
	Creates an exception with the name of the function, in which the failure occurs, and an optional detailed message.
H5std_string	getMajorString (H5E_major_t major_num) const
	Returns a text string that describes the error specified by a major error number.
H5std_string	getMinorString (H5E_minor_t minor_num) const
	Returns a text string that describes the error specified by a minor error number.
H5std_string	getDetailMsg () const
	Returns the detailed message set at the time the exception is thrown.
const char *	getCDetailMsg () const
	Returns the detailed message set at the time the exception is thrown.
H5std_string	getFuncName () const
	Returns the name of the function, where the exception is thrown.
const char *	getCFuncName () const
	Returns the name of the function, where the exception is thrown.
virtual void	printError (FILE *stream=NULL) const
	Prints the error stack in a default manner.
	Exception ()
	Default constructor.
	Exception (const Exception &orig)
	Copy constructor: makes a copy of the original Exception object.
virtual	~Exception ()
	Noop destructor.
Static Public Member Functions
static void	setAutoPrint (H5E_auto_t &func, void *client_data)
	Turns on the automatic error printing.
static void	dontPrint ()
	Turns off the automatic error printing from the C library.
static void	getAutoPrint (H5E_auto_t &func, void **client_data)
	Retrieves the current settings for the automatic error stack traversal function and its data.
static void	clearErrorStack ()
	Clears the error stack for the current thread.
static void	walkErrorStack (H5E_direction_t direction, H5E_walk_t func, void *client_data)
	Walks the error stack for the current thread, calling the specified function.
Static Protected Attributes
static const H5std_string	DEFAULT_MSG

---

Constructor & Destructor Documentation

H5::Exception::Exception	(	const H5std_string &	func_name,
		const H5std_string &	message = DEFAULT_MSG
	)

Creates an exception with the name of the function, in which the failure occurs, and an optional detailed message.

Parameters:

	func_name	- IN: Name of the function where failure occurs
	message	- IN: Message on the failure

H5::Exception::Exception

(

)

Default constructor.

H5::Exception::Exception

(

const Exception &

orig

)

Copy constructor: makes a copy of the original Exception object.

Parameters:

orig

- IN: Exception instance to copy

H5::Exception::~Exception

(

)

[virtual]

Noop destructor.

---

Member Function Documentation

H5std_string H5::Exception::getMajorString

(

H5E_major_t

err_major

)

const

Returns a text string that describes the error specified by a major error number.

Parameters:

err_major

- IN: Major error number

Returns:

Major error string

Description

In the failure case, the string "Invalid major error number" will be returned.

H5std_string H5::Exception::getMinorString

(

H5E_minor_t

err_minor

)

const

Returns a text string that describes the error specified by a minor error number.

Parameters:

err_minor

- IN: Minor error number

Returns:

Minor error string

Description

In the failure case, the string "Invalid minor error number" will be returned.

H5std_string H5::Exception::getDetailMsg

(

)

const

Returns the detailed message set at the time the exception is thrown.

Returns:

Text message - H5std_string

const char * H5::Exception::getCDetailMsg

(

)

const

Returns the detailed message set at the time the exception is thrown.

Returns:

Text message - char pointer

H5std_string H5::Exception::getFuncName

(

)

const

Returns the name of the function, where the exception is thrown.

Returns:

Text message - H5std_string

const char * H5::Exception::getCFuncName

(

)

const

Returns the name of the function, where the exception is thrown.

Returns:

Text message - char pointer

void H5::Exception::setAutoPrint	(	H5E_auto_t &	func,
		void *	client_data
	)			[static]

Turns on the automatic error printing.

Parameters:

	func	- IN: Function to be called upon an error condition
	client_data	- IN: Data passed to the error function

Description

When the library is first initialized the auto printing function, func, is set to the C API H5Eprint and client_data is the standard error stream pointer, stderr. Automatic stack traversal is always in the H5E_WALK_DOWNWARD direction.

Users are encouraged to write their own more specific error handlers

void H5::Exception::dontPrint

(

)

[static]

Turns off the automatic error printing from the C library.

void H5::Exception::getAutoPrint	(	H5E_auto_t &	func,
		void **	client_data
	)			[static]

Retrieves the current settings for the automatic error stack traversal function and its data.

Parameters:

	func	- OUT: Current setting for the function to be called upon an error condition
	client_data	- OUT: Current setting for the data passed to the error function

void H5::Exception::clearErrorStack

(

)

[static]

Clears the error stack for the current thread.

Description

The stack is also cleared whenever a C API function is called, with certain exceptions (for instance, H5Eprint).

void H5::Exception::walkErrorStack	(	H5E_direction_t	direction,
		H5E_walk_t	func,
		void *	client_data
	)			[static]

Walks the error stack for the current thread, calling the specified function.

Parameters:

	direction	- IN: Direction in which the error stack is to be walked
	func	- IN: Function to be called for each error encountered
	client_data	- IN: Data passed to the error function

Description

Valid values for direction include:

• H5E_WALK_UPWARD - begin with the most specific error and end at the API
• H5E_WALK_DOWNWARD - begin at the API and end at the inner-most function where the error was first detected

The function specified by func will be called for each error in the error stack. The H5E_walk_t prototype is as follows:

    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.

Data structure to describe the error:

    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;

void H5::Exception::printError

(

FILE *

stream = NULL

)

const [virtual]

Prints the error stack in a default manner.

Parameters:

stream

- IN: File pointer

Examples:

chunks.cpp, compound.cpp, create.cpp, extend_ds.cpp, h5group.cpp, readdata.cpp, and writedata.cpp.

---

Member Data Documentation

const H5std_string H5::Exception::DEFAULT_MSG [static, protected]

---