New Error API Specifications

Name: H5Eregister_class

Signature:

hid_t H5Eregister_class(const char* cls_name, const char* lib_name,

const char* version)

Purpose:

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

Description:

H5Eregister_class registers a client library or application program to HDF5 error API so that the client library or application program can report error together with HDF5 library. It receives an ID for this error class for further error operations. The library name and version number will be printed out in the error message as preamble.

Parameters:

const char* cls_name,

IN: Name of the error class.

const char* lib_name,

IN: Name of the library to which the error class belongs.

const char* version,

IN: Version of the library to which the error class belongs. A NULL can

be passed in.

Returns:

Returns a non-negative value if succeeds; otherwise returns a negative value.

Name: H5Ecreate_msg

Signature:

hid_t H5Ecreate_msg(hid_t class, H5E_type_t msg_type, const char* mesg)

Purpose:

Add major error message to an error class.

Description:

H5Ecreate_msg adds an error message to an error class defined by client

library or application program. The error message can be either major or minor which is indicated by parameter msg_type.

Parameters:

hid_t class

IN: ID of error class.

H5E_type_t msg_type,

IN: the type of the error message. Valid values are H5E_MAJOR and

H5E_MINOR.

const char* mesg

IN: major error message

Returns:

Returns a non-negative value if succeeds; otherwise returns a negative value.

Name: H5Eget_class_name

Signature:

ssize_t H5Eget_class_name(hid_t class_id, char* name, size_t size)

Purpose:

Retrieves error class name.

Description:

H5Eget_class_name retrieves the name of the error class specified by the class ID. If non-NULL pointer is passed in for name and size is greater than zero, the class name of size long is returned. The length of the error class name is also returned. If NULL is passed in as name, only the length of class name is returned. If zero is returned, it means no name. User is responsible for allocated enough buffer for the name.

Parameters:

hid_t class_id,

IN: the ID of the error class.

char* name,

OUT: the name of the class to be queried.

size_t size,

IN: the length of class name to be returned by this function.

Returns:

Returns non-negative value as if succeeds; otherwise returns negative value.

Name: H5Eget_msg

Signature:

ssize_t H5Eget_msg(hid_t mesg_id, H5E_type_t* mesg_type, char* mesg,

size_t size)

Purpose:

Retrieves an error message.

Description:

H5Eget_msg retrieves the error message including its length and type. The error message is specified by mesg_id. User is responsible for passing in enough buffer for the message. If mesg is not NULL and size is greater than zero, the error message of size long is returned. The length of the message is also returned. If NULL is passed in as mesg, only the length and type of the message is returned. If the return value is zero, it means no message.

Parameters:

hid_t mesg_id,

IN: ID of error message to be queried.

H5E_type_t* mesg_type,

OUT: the type of the error message. Valid values are H5E_MAJOR and

H5E_MINOR.

char* mesg,

OUT: error message buffer.

size_t size,

IN: the length of error message to be returned by this function.

Returns:

Returns non-negative value if succeeds; otherwise returns a negative value.

Name: H5Epop

Signature:

herr_t H5Epop(hid_t error_stack, size_t count)

Purpose:

Deletes some error messages from the error stack.

Description:

H5Epop deletes some error record (including major, minor messages and description) from the top of an error stack specified by error_stack. The number of error messages to be deleted is specified by count.

Parameters:

hid_t error_stack,

IN: the ID of error stack.

size_t count,

IN: the number of error messages to be deleted from the top of error stack.

Returns:

Returns a non-negative value if succeeds; otherwise returns a negative value.

Name: H5Eget_num

Signature:

int H5Eget_num(hid_t error_stack)

Purpose:

Retrieves the number of error messages.

Description:

H5Eget_num retrieves the number of error records (including major, minor messages and description) from an error stack specified by error_stack.

Parameters:

hid_t error_stack,

IN: the ID of error stack.

Returns:

Returns a non-negative value if succeeds; otherwise returns a negative value.

Name: H5Eclose_msg

Signature:

herr_t H5Eclose_msg(hid_t mesg_id)

Purpose:

Closes an error message ID

Description:

H5Eclose_msg closes an error message ID, which can be either major or minor message.

Parameters:

hid_t mesg_id,

IN: error message ID.

Returns:

Returns a non-negative value if succeeds; otherwise returns a negative value.

Name: H5Eunregister_class

Signature:

herr_t H5Eunregister_class(hid_t class_id)

Purpose:

Removes an error class from the error API.

Description:

H5Eunregister_class removes an error class from the error API. All the major

And minor errors in this class will also be closed.

Parameters:

hid_t class_id,

IN: error class ID.

Returns:

Returns a non-negative value if succeeds; otherwise returns a negative value.

Name: H5Eget_current_stack

Signature:

hid_t H5Eget_current_stack(void)

Purpose:

Registers the current error stack.

Description:

H5Eget_current_stack registers the current error stack, returns an object handle, and clears the current error stack. An empty error stack will also be assigned an ID.

Parameter:

None.

Returns:

Returns a non-negative value if succeeds; otherwise returns a negative value.

Name: H5Eset_current_stack

Signature:

herr_t H5Eset_current_stack(hid_t error_stack)

Purpose:

Replaces the current error stack.

Description:

H5Eset_current_stack replaces the current error stack with another error stack specified by error_stack, clears the current error stack. The object handle error_stack is closed after this function call.

Parameter:

hid_t error_stack,

IN: ID of the error stack.

Returns:

Returns a non-negative value if succeeds; otherwise returns a negative value.

Name: H5Eclose_stack

Signature:

herr_t H5Eclose_stack(hid_t error_stack)

Purpose:

Closes object handle for error stack.

Description:

H5Eclose_stack closes the object handle for an error stack and releases its resources. H5E_DEFAULT cannot be closed.

Parameters:

hid_t error_stack,

IN: Error stack ID.

Returns:

Returns a non-negative value if succeeds; otherwise returns a negative value.