Unified Error Reporting for HDF5 and Client Libraries

Quincey Koziol
koziol@ncsa.uiuc.edu
March 26, 2003

  1. Document's Audience:

  2. Background Reading:

    HDF5 Error API
    This explains the current error API in HDF5.

  3. Introduction:

    What is this document about?
    This document describes ideas for extending the HDF5 Error API to allow libraries built on top of the HDF5 library (called "client libraries") to participate in a unified error reporting method.

    What is currently implemented?
    Currently the HDF5 library's error reporting information is tightly bound to the library at compile time, requiring modification of the library source code to add each major or minor error code and its description. This prohibits client libraries from easily adding their own error codes to extend the set of errors able to be reported.

    What areas do we want to expand error reporting support in?
    We would like to allow client libraries to add their own major and minor error codes at run-time. Additionally, they must be able to "chain" into the HDF5 error stack to seamlessly report errors at their layer in a software stack through the HDF5 error reporting mechanisms.

    Why do we want to expand error reporting support?
    Our customers would like to be able to provide a unified error report to user's applications, using a single error reporting API.

  4. Use Cases:

    Adding support for extending error reporting in HDF5 breaks down into a few simple use cases. Note that these use cases only discuss new features, the existing HDF5 error API should be used to iterate over the HDF5 error stack, etc.

    Register client library with error API use case scenario:

    Push client library error onto error stack use case scenario:

    Switch error stack use case scenario:

    Display error stack use case scenario:

    Unregister client library error information use case scenario:

  5. Potential Problems:

    None?

  6. Changes to Existing API:

    H5Epush
    Pushes major error ID, minor error ID, and specified error stack. It can take additional message for format control like printf and fprintf.

    H5Eprint
    Prints the specified error stack.

    H5Ewalk
    Walks through the specified error stack. It can traverse the major error ID, minor error ID, and the class ID in the modified H5E_error_t struct.

    H5Eclear
    Clears the specified error stack.

    H5Eset_auto
    Turns automatic error printing on or off for the specified error stack.

    H5Eget_auto
    Returns the settings for the specified error stack traversal.

    A list of existing API specifications.

  7. Removed API Functions:

    Both H5Eget_major and H5Eget_minor are replaced by a single function H5Eget_mesg.

  8. New API Functions:

    H5Eregister_class
    Registers a client library with the error API and returns an error class ID for future use with the error API.

    H5Eget_class_name
    Returns a character string and its length describing the error class. (This is the string passed in for registering the class with H5Eregister_class).

    H5Eunregister_class
    Removes an error class from the error API, closing all major and minor error codes in that class.

    H5Ecreate_mesg
    Add either "major" or "minor" error code to an error class.

    H5Eget_mesg
    Returns the error code and its type("major" or "minor") specified by the ID.

    H5Eclose_mesg
    close either "major" or "minor" error code to an error class.

    H5Eget_current_stack
    Turns current error stack into an object handle and clears the current error stack.

    H5Eset_current_stack
    Replaces current error stack with another error stack specified by its object handle.

    H5Eclose_stack
    Closes the object handle for an error stack and releases its resources.

    H5Eget_num
    Returns the number of error messages in an error stack.

    H5Epop
    Deletes some error messages from the error stack.

    A list of new API specifications.

  9. Possible New API Functions:

    We can provide macros similar to our internal macros, HGOTO_ERROR, HGOTO_DONE. They will reduce the length of codes.

  10. Example Programs:

    Example programs corresponding to use cases:

    Register client library with error API example:

    Push client library error onto error stack:

    Swich error stack:

    Display error stack with error class IDs, and dynamicly added major and minor error code.

    Unregister client library error information: