Fortran Error (H5E) Interface

Detailed Description

See also

Error Handling (H5E), C-API

HDF5 Error Handling, User Guide

Modules
module	h5e
	This module contains Fortran interfaces for H5E functions.

Functions/Subroutines
subroutine	h5eclear_f (hdferr, estack_id)
	Clears the error stack for the current thread.
subroutine	h5eprint_f (hdferr, name)
	Prints the error stack in a default manner.
subroutine	h5eget_major_f (error_no, name, namelen, hdferr)
	Returns a character string describing an error specified by a major error number.
subroutine	h5eget_minor_f (error_no, name, hdferr)
	Returns a character string describing an error specified by a minor error number.
subroutine	h5eset_auto_f (printflag, hdferr, estack_id, func, client_data)
	Returns settings for automatic error stack traversal function and its data.
subroutine	h5epush_f (err_stack, file, func, line, cls_id, maj_id, min_id, msg, hdferr, arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8, arg9, arg10, arg11, arg12, arg13, arg14, arg15, arg16, arg17, arg18, arg19, arg20)
	Pushes a new error record onto an error stack.
subroutine	h5eregister_class_f (cls_name, lib_name, version, class_id, hdferr)
	Registers a client library or application program to the HDF5 error API.
subroutine	h5eunregister_class_f (class_id, hdferr)
	Removes an error class.
subroutine	h5ecreate_msg_f (class_id, msg_type, msg, err_id, hdferr)
	Adds a major or minor error message to an error class.
subroutine	h5eclose_msg_f (err_id, hdferr)
	Closes an error message.
subroutine	h5eget_msg_f (msg_id, msg_type, msg, hdferr, msg_size)
	Retrieves an error message.
subroutine	h5eget_num_f (error_stack_id, count, hdferr)
	Retrieves the number of error messages in an error stack.
subroutine	h5ewalk_f (err_stack, direction, op, op_data, hdferr)
	Walks the specified error stack, calling the specified function.
subroutine	h5eget_class_name_f (class_id, name, hdferr, size)
	Retrieves an error message.
subroutine	h5eappend_stack_f (dst_stack_id, src_stack_id, close_source_stack, hdferr)
	Appends one error stack to another, optionally closing the source stack.
subroutine	h5eget_current_stack_f (err_stack_id, hdferr)
	Returns a copy of the current error stack.
subroutine	h5eset_current_stack_f (err_stack_id, hdferr)
	Replaces the current error stack.
subroutine	h5eclose_stack_f (err_stack_id, hdferr)
	Closes an error stack handle.
subroutine	h5ecreate_stack_f (err_stack_id, hdferr)
	Creates a new, empty error stack.
subroutine	h5epop_f (err_stack_id, count, hdferr)
	Deletes specified number of error messages from the error stack.

Variables
integer(hid_t)	h5e_default_f
	H5E_DEFAULT.
integer	h5e_major_f
	H5E_MAJOR.
integer	h5e_minor_f
	H5E_MINOR.
integer	h5e_walk_upward_f
	H5E_WALK_UPWARD.
integer	h5e_walk_downward_f
	H5E_WALK_DOWNWARD.

Function/Subroutine Documentation

h5eappend_stack_f()

subroutine h5eappend_stack_f	(	integer(hid_t), intent(in)	dst_stack_id,
		integer(hid_t), intent(in)	src_stack_id,
		logical, intent(in)	close_source_stack,
		integer, intent(out)	hdferr
	)

Appends one error stack to another, optionally closing the source stack.

Parameters

dst_stack_id	Error stack identifier
src_stack_id	Error stack identifier
close_source_stack	Flag to indicate whether to close the source stack
hdferr	Returns 0 if successful and -1 if it fails.

See C API: H5Eappend_stack()

h5eclear_f()

subroutine h5eclear_f	(	integer, intent(out)	hdferr,
		integer(hid_t), intent(in), optional	estack_id
	)

Clears the error stack for the current thread.

Parameters

hdferr	Returns 0 if successful and -1 if it fails.
estack_id	Error Stack id

See C API: H5Eclear2()

h5eclose_msg_f()

subroutine h5eclose_msg_f	(	integer(hid_t), intent(in)	err_id,
		integer, intent(out)	hdferr
	)

Closes an error message.

Parameters

err_id	An error message identifier
hdferr	Returns 0 if successful and -1 if it fails.

See C API: H5Eclose_msg()

h5eclose_stack_f()

subroutine h5eclose_stack_f	(	integer(hid_t), intent(in)	err_stack_id,
		integer, intent(out)	hdferr
	)

Closes an error stack handle.

Parameters

err_stack_id	Error stack identifier
hdferr	Returns 0 if successful and -1 if it fails.

See C API: H5Eclose_stack()

h5ecreate_msg_f()

subroutine h5ecreate_msg_f	(	integer(hid_t), intent(in)	class_id,
		integer, intent(in)	msg_type,
		character(len=*), intent(in)	msg,
		integer(hid_t), intent(out)	err_id,
		integer, intent(out)	hdferr
	)

Adds a major or minor error message to an error class.

Parameters

class_id	An error class identifier
msg_type	The type of the error message
msg	Error message
err_id	Error identifier
hdferr	Returns 0 if successful and -1 if it fails.

See C API: H5Ecreate_msg()

h5ecreate_stack_f()

subroutine h5ecreate_stack_f	(	integer(hid_t), intent(out)	err_stack_id,
		integer, intent(out)	hdferr
	)

Creates a new, empty error stack.

Parameters

err_stack_id	Error stack identifier
hdferr	Returns 0 if successful and -1 if it fails.

See C API: H5Ecreate_stack()

h5eget_class_name_f()

subroutine h5eget_class_name_f	(	integer(hid_t), intent(in)	class_id,
		character(len=*)	name,
		integer, intent(out)	hdferr,
		integer(size_t), intent(inout), optional	size
	)

Retrieves an error message.

Parameters

class_id	Error class identifier
name	Buffer for the error class name
hdferr	Returns 0 if successful and -1 if it fails.
size	The maximum number of characters of the class name to be returned by this function in name.

If size is omitted, the API will copy up to the length of name, and it is the application's responsibility to provide a large enough buffer. If size is zero, the required buffer size will be returned, and name is not accessed. If size is greater than zero, the function will copy up to the length of size info name.

See C API: H5Eget_class_name()

h5eget_current_stack_f()

subroutine h5eget_current_stack_f	(	integer(hid_t), intent(out)	err_stack_id,
		integer, intent(out)	hdferr
	)

Returns a copy of the current error stack.

Parameters

err_stack_id	Error stack identifier
hdferr	Returns 0 if successful and -1 if it fails.

See C API: H5Eget_current_stack()

h5eget_major_f()

subroutine h5eget_major_f	(	integer(hid_t), intent(in)	error_no,
		character(len=*), intent(out)	name,
		integer(size_t), intent(inout)	namelen,
		integer, intent(out)	hdferr
	)

Returns a character string describing an error specified by a major error number.

Parameters

error_no	Major error number.
name	Character string describing the error.
namelen	Number of characters in the name buffer.
hdferr	Returns 0 if successful and -1 if it fails.

Attention

Deprecated: use H5Eget_msg_f() instead.

See C API: H5Eget_major()

h5eget_minor_f()

subroutine h5eget_minor_f	(	integer(hid_t), intent(in)	error_no,
		character(len=*), intent(out)	name,
		integer, intent(out)	hdferr
	)

Returns a character string describing an error specified by a minor error number.

Parameters

error_no	Minor error number.
name	Character string describing the error.
hdferr	Returns 0 if successful and -1 if it fails.

Attention

Deprecated: use H5Eget_msg_f() instead.

See C API: H5Eget_minor()

h5eget_msg_f()

subroutine h5eget_msg_f	(	integer(hid_t), intent(in)	msg_id,
		integer, intent(out)	msg_type,
		character(len=*)	msg,
		integer, intent(out)	hdferr,
		integer(size_t), intent(inout), optional	msg_size
	)

Retrieves an error message.

Parameters

msg_id	Error message identifier
msg_type	The type of the error message. Valid values are H5E_MAJOR_F and H5E_MINOR_F.
msg	Error message buffer
hdferr	Returns 0 if successful and -1 if it fails.
msg_size	The length of error message to be returned by this function

If msg_size is omitted, the API will copy up to the length of msg, and it is the application's responsibility to provide a large enough buffer. If msg_size is zero, the required buffer size will be returned, and msg is not accessed. If msg_size is greater than zero, the function will copy up to the length of msg_size info msg.

See C API: H5Eget_msg()

h5eget_num_f()

subroutine h5eget_num_f	(	integer(hid_t), intent(in)	error_stack_id,
		integer(size_t), intent(out)	count,
		integer, intent(out)	hdferr
	)

Retrieves the number of error messages in an error stack.

Parameters

error_stack_id	An error message identifier
count	Number of error messages in err_id
hdferr	Returns 0 if successful and -1 if it fails.

See C API: H5Eget_num()

h5epop_f()

subroutine h5epop_f	(	integer(hid_t), intent(in)	err_stack_id,
		integer(size_t), intent(in)	count,
		integer, intent(out)	hdferr
	)

Deletes specified number of error messages from the error stack.

Parameters

err_stack_id	Error stack identifier
count	The number of error messages to be deleted from the top of error stack
hdferr	Returns 0 if successful and -1 if it fails.

See C API: H5Epop()

h5eprint_f()

subroutine h5eprint_f	(	integer, intent(out)	hdferr,
		character(len=*), intent(in), optional	name
	)

Prints the error stack in a default manner.

Parameters

hdferr	Returns 0 if successful and -1 if it fails.
name	Name of the file that contains print output

Note

If name is not specified, the output will be sent to the standard error (stderr).

Attention

Deprecated.

See C API: H5Eprint1()

h5epush_f()

subroutine h5epush_f	(	integer(hid_t), intent(in)	err_stack,
		character(len=*), intent(in)	file,
		character(len=*), intent(in)	func,
		integer, intent(in)	line,
		integer(hid_t), intent(in)	cls_id,
		integer(hid_t), intent(in)	maj_id,
		integer(hid_t), intent(in)	min_id,
		character(len=*), intent(in)	msg,
		integer, intent(out)	hdferr,
		character(len=*), optional, target	arg1,
		character(len=*), optional, target	arg2,
		character(len=*), optional, target	arg3,
		character(len=*), optional, target	arg4,
		character(len=*), optional, target	arg5,
		character(len=*), optional, target	arg6,
		character(len=*), optional, target	arg7,
		character(len=*), optional, target	arg8,
		character(len=*), optional, target	arg9,
		character(len=*), optional, target	arg10,
		character(len=*), optional, target	arg11,
		character(len=*), optional, target	arg12,
		character(len=*), optional, target	arg13,
		character(len=*), optional, target	arg14,
		character(len=*), optional, target	arg15,
		character(len=*), optional, target	arg16,
		character(len=*), optional, target	arg17,
		character(len=*), optional, target	arg18,
		character(len=*), optional, target	arg19,
		character(len=*), optional, target	arg20
	)

Pushes a new error record onto an error stack.

Parameters

err_stack	Error stack identifier. If the identifier is H5E_DEFAULT_F, the error record will be pushed to the current stack.
file	Name of the file in which the error was detected
func	Name of the function in which the error was detected
line	Line number in the file where the error was detected
cls_id	Error class identifier
maj_id	Major error identifier
min_id	Minor error identifier
msg	Error description string
hdferr	Returns 0 if successful and -1 if it fails.
arg1	C style format control strings
arg2	C style format control strings
arg3	C style format control strings
arg4	C style format control strings
arg5	C style format control strings
arg6	C style format control strings
arg7	C style format control strings
arg8	C style format control strings
arg9	C style format control strings
arg10	C style format control strings
arg11	C style format control strings
arg12	C style format control strings
arg13	C style format control strings
arg14	C style format control strings
arg15	C style format control strings
arg16	C style format control strings
arg17	C style format control strings
arg18	C style format control strings
arg19	C style format control strings
arg20	C style format control strings

Note

arg[1-20] expects C-style format strings, similar to the system and C functions printf() and fprintf(). Furthermore, special characters, such as ANSI escapes, will only be interpreted correctly if the Fortran equivalent is used. For example, to print msg "TEXT" in red would be:

(..., "%s TEXT %s", hdferr, ..., arg1=achar(27)//"[31m"//c_null_char, arg2=achar(27)//"[0m"//c_null_char )

Using "\n" instead of C_NEW_LINE will not be interpereted correctly, and similarly, using "\x1B" instead of ACHAR(27). Also, all arg[1-20] characters strings must be NULL terminated.

See C API: H5Epush2()

h5eregister_class_f()

subroutine h5eregister_class_f	(	character(len=*), intent(in)	cls_name,
		character(len=*), intent(in)	lib_name,
		character(len=*), intent(in)	version,
		integer(hid_t), intent(out)	class_id,
		integer, intent(out)	hdferr
	)

Registers a client library or application program to the HDF5 error API.

Parameters

cls_name	Name of the error class
lib_name	Name of the client library or application to which the error class belongs
version	Version of the client library or application to which the error class belongs. It can be NULL.
class_id	Class identifier
hdferr	Returns 0 if successful and -1 if it fails.

See C API: H5Eregister_class()

h5eset_auto_f()

subroutine h5eset_auto_f	(	integer, intent(in)	printflag,
		integer, intent(out)	hdferr,
		integer(hid_t), intent(in), optional	estack_id,
		type(c_funptr), intent(in), optional	func,
		type(c_ptr), intent(in), optional	client_data
	)

Returns settings for automatic error stack traversal function and its data.

Parameters

printflag	Flag to turn automatic error printing on or off; possible values are: printon (1) printoff(0)
estack_id	Error stack identifier.
func	Function to be called upon an error condition.
client_data	Data passed to the error function.
hdferr	Returns 0 if successful and -1 if it fails.

See C API: H5Eset_auto2()

h5eset_current_stack_f()

subroutine h5eset_current_stack_f	(	integer(hid_t), intent(in)	err_stack_id,
		integer, intent(out)	hdferr
	)

Replaces the current error stack.

Parameters

err_stack_id	Error stack identifier
hdferr	Returns 0 if successful and -1 if it fails.

See C API: H5Eset_current_stack()

h5eunregister_class_f()

subroutine h5eunregister_class_f	(	integer(hid_t), intent(in)	class_id,
		integer, intent(out)	hdferr
	)

Removes an error class.

Parameters

class_id	Class identifier
hdferr	Returns 0 if successful and -1 if it fails.

See C API: H5Eunregister_class()

h5ewalk_f()

subroutine h5ewalk_f	(	integer(hid_t), intent(in)	err_stack,
		integer, intent(in)	direction,
		type(c_funptr), intent(in)	op,
		type(c_ptr), intent(inout)	op_data,
		integer, intent(out)	hdferr
	)

Walks the specified error stack, calling the specified function.

Parameters

err_stack	Error stack identifier
direction	Direction in which the error stack is to be walked
op	Function to be called for each error encountered
op_data	Data to be passed to func
hdferr	Returns 0 if successful and -1 if it fails.

See C API: H5Ewalk2()

Variable Documentation

h5e_default_f

integer(hid_t) h5e_default_f

H5E_DEFAULT.

h5e_major_f

integer h5e_major_f

H5E_MAJOR.

h5e_minor_f

integer h5e_minor_f

H5E_MINOR.

h5e_walk_downward_f

integer h5e_walk_downward_f

H5E_WALK_DOWNWARD.

h5e_walk_upward_f

integer h5e_walk_upward_f

H5E_WALK_UPWARD.