Unified Error Reporting for HDF5 and Client Libraries

Quincey Koziol
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:


  6. Changes to Existing API:

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

    Prints the specified error stack.

    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.

    Clears the specified error stack.

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

    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:

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

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

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

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

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

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

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

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

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

    Returns the number of error messages in an error stack.

    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: