Author: Quincey Koziol

# Unified Error Reporting for HDF5 and Client Libraries

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

1. ### Document's Audience:

   - Current H5 library designers and knowledgable external developers.

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:

   - Register Client Library

   Push client library error onto error stack use case scenario:

   - Push Error

   Switch error stack use case scenario:

   - Switch Error Stack

   Display error stack use case scenario:

   - Display Error Stack

   Unregister client library error information use case scenario:

   - Unregister Client Library

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:

    - Register Client Library

    Push client library error onto error stack:

    - Push Error

    Swich error stack:

    - Switch Error Stack

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

    - Display Error Stack

    Unregister client library error information:

    - Unregister Client Library