From 2399650d6429cb6c8320adf022ea621ccc6a4a0e Mon Sep 17 00:00:00 2001 From: Frank Baker Date: Wed, 18 May 2005 17:16:08 -0500 Subject: [svn-r10752] Purpose: Added new H5Error APIs. Description: Added C entries for H5Eregister_class H5Eunregister_class H5Eget_class_name H5auto_is_stack H5Ecreate_msg H5Eget_msg H5Eclose_msg H5Eget_num H5Epop H5Eget_current_stack H5Eclose_stack Still missing -- 6 APIs that match existing APIs except that they include a 'stack' parameter. Those APIs will be added shortly. Platforms tested: Firefox --- doc/html/RM_H5E.html | 483 +++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 454 insertions(+), 29 deletions(-) diff --git a/doc/html/RM_H5E.html b/doc/html/RM_H5E.html index 250302f..d84f556 100644 --- a/doc/html/RM_H5E.html +++ b/doc/html/RM_H5E.html @@ -43,6 +43,11 @@ HDF5/H5E API Specification And in this document, the HDF5 Reference Manual  
+H5IM   +H5LT   +H5PT   +H5TB   +
H5   H5A   H5D   @@ -78,18 +83,29 @@ These functions provide error handling capabilities in the HDF5 environment.
  • H5Eclear
  • H5Eprint
  • H5Epush - -       -        +       + @@ -101,9 +117,13 @@ These functions provide error handling capabilities in the HDF5 environment. @@ -111,9 +131,13 @@ These functions provide error handling capabilities in the HDF5 environment. @@ -121,7 +145,11 @@ These functions provide error handling capabilities in the HDF5 environment. @@ -186,6 +214,41 @@ errors within the H5E package. + +
    +
    +
    Name: H5Eauto_is_stack +
    Signature: +
    herr_t H5Eauto_is_stack(hid_t + estack_id, unsigned *is_stack) +
    Purpose: +
    Determines type of error stack. +
    Description: +
    H5Eauto_is_stack determines whether the error auto + reporting function for an error stack conforms to the + H5E_auto_stack_t typedef or the + H5E_auto_t typedef. +

    + The is_stack parameter is set to 11 + if the error stack conforms to H5E_auto_stack_t + and 0 for if H5E_auto_t. +

    Parameters: +
      + + + + + + +
      hid_t estack_idThe error stack identifier
      unsigned* is_stack    A flag indicating which error stack typedef + the specified error stack conforms to.
    +
    Returns: +
    Returns a non-negative value if successful; + otherwise returns a negative value. +
    Fortran90 Interface: +
    + +
    @@ -228,6 +291,97 @@ END SUBROUTINE h5eclear_f
    + +
    +
    +
    Name: H5Eclose_msg +
    Signature: +
    herr_t H5Eclose_msg(hid_t + mesg_id) +
    Purpose: +
    Closes an error message identifier. +
    Description: +
    H5Eclose_msg closes an error message identifier., + which can be either a major or minor message. +
    Parameters: +
      + + + +
      hid_t mesg_id    IN: Error message identifier.
    +
    Returns: +
    Returns a non-negative value on success; + otherwise returns a negative value. +
    Fortran90 Interface: +
    None. +
    + + + +
    +
    +
    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 identifier.
    +
    Returns: +
    Returns a non-negative value on success; + otherwise returns a negative value. +
    Fortran90 Interface: +
    None. +
    + + + +
    +
    +
    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: Error class identifier.
      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 message identifier on success; + otherwise returns a negative value. +
    Fortran90 Interface: +
    None. +
    + +
    @@ -247,11 +401,11 @@ END SUBROUTINE h5eclear_f
    Parameters:
      - + - +
      H5E_auto_t * funcH5E_auto_t * func OUT: Current setting for the function to be called upon an error condition.
      void **client_data    void **client_data     OUT: Current setting for the data passed to the error function.
    Returns: @@ -264,7 +418,7 @@ END SUBROUTINE h5eclear_f 
     SUBROUTINE
    ---> +--> + +
    +
    +
    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 identifier. + 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: Error class identifier.
      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 on success; + otherwise returns negative value. +
    Fortran90 Interface: +
    None. +
    + + + +
    +
    +
    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 identifier, and clears the current error stack. + An empty error stack will also be assigned an identifier. +
    Parameters: +
      + +
      None.
    +
    Returns: +
    Returns the identifier of the current error stack on success; + otherwise returns a negative value. +
    Fortran90 Interface: +
    None. +
    + +
    @@ -290,7 +509,7 @@ SUBROUTINE
    Parameters:
      - +
      H5E_major_t n    H5E_major_t n     IN: Major error number.
    Returns: @@ -331,7 +550,7 @@ END SUBROUTINE h5eget_major_f
    Parameters:
      - +
      H5E_minor_t n    H5E_minor_t n     IN: Minor error number.
    Returns: @@ -357,6 +576,113 @@ END SUBROUTINE h5eget_minor_f
    + +
    +
    +
    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: Idenfier for 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 the size of the error message in bytes on success; + otherwise returns a negative value. +
    Fortran90 Interface: +
    None. +
    + + + +
    +
    +
    Name: H5Eget_num +
    Signature: +
    size_t H5Eget_num(hid_t error_stack) +
    Purpose: +
    Retrieves the number of error messages in an error stack. +
    Description: +
    H5Eget_num retrieves the number of error records + in the error stack specified by error_stack + (including major, minor messages and description). +
    Parameters: +
      + + + +
      hid_t error_stack +     IN: Error stack identifier.
    +
    Returns: +
    Returns a non-negative value on success; + otherwise returns a negative value. +
    Fortran90 Interface: +
    None. +
    + + + +
    +
    +
    Name: H5Epop +
    Signature: +
    herr_t H5Epop(hid_t + error_stack, size_t count) +
    Purpose: +
    Deletes specified number of error messages from the error stack. +
    Description: +
    H5Epop deletes the number of error records specified + in count from the top of the error stack + specified by error_stack + (including major, minor messages and description). + The number of error messages to be deleted is specified by count. +
    Parameters: +
      + + + + + + +
      hid_t error_stack +     IN: Error stack identifier.
      size_t countIN: The number of error messages to be deleted + from the top of error stack.
    +
    Returns: +
    Returns a non-negative value on success; + otherwise returns a negative value. +
    Fortran90 Interface: +
    None. +
    + +
    @@ -378,7 +704,7 @@ END SUBROUTINE h5eget_minor_f
    Parameters:
      - +
      FILE * stream    FILE * stream     IN: File pointer, or stderr if NULL.
    Returns: @@ -434,22 +760,22 @@ END SUBROUTINE h5eprint_f
    Parameters:
      - + - + - + - + - + - +
      const char *file,const char *file, IN: Name of the file in which the error was detected.
      const char *func,const char *func, IN: Name of the function in which the error was detected.
      unsigned line,unsigned line, IN: Line within the file at which the error was detected.
      H5E_major_t maj_num,    H5E_major_t maj_num,     IN: Major error number.
      H5E_minor_t min_num,H5E_minor_t min_num, IN: Minor error number.
      const char *strconst char *str IN: Error description string.
    Returns: @@ -473,6 +799,46 @@ SUBROUTINE
    + +
    +
    +
    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 identifier 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 client library or application + to which the error class belongs.
      const char* version,IN: Version of the client library or application + to which the error class belongs. + A NULL can be passed in.
    +
    Returns: +
    Returns a class identifier on success; + otherwise returns a negative value. +
    Fortran90 Interface: +
    None. +
    + +
    @@ -500,10 +866,10 @@ SUBROUTINE
    Parameters:
      - + - +
      H5E_auto_t funcH5E_auto_t func IN: Function to be called upon an error condition.
      void *client_data    void *client_data     IN: Data passed to the error function.
    Returns: @@ -532,6 +898,60 @@ END SUBROUTINE h5eset_auto_f
    + +
    +
    +
    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 content of + the current error stack with a copy of the content of error stack + specified by error_stack. +
    Parameters: +
      + + + +
      hid_t error_stack,    IN: Error stack identifier.
    +
    Returns: +
    Returns a non-negative value on success; + otherwise returns a negative value. +
    Fortran90 Interface: +
    None. +
    + + + +
    +
    +
    Name: H5Eunregister_class +
    Signature: +
    herr_t H5Eunregister_class(hid_t + class_id) +
    Purpose: +
    Removes an error class. +
    Description: +
    H5Eunregister_class removes the error class specified + by class_id. + All the major and minor errors in this class will also be closed. +
    Parameters: +
      + + + +
      hid_t class_id,    IN: Error class identifier.
    +
    Returns: +
    Returns a non-negative value on success; + otherwise returns a negative value. +
    Fortran90 Interface: +
    None. +
    + +
    @@ -591,13 +1011,13 @@ END SUBROUTINE h5eset_auto_f
    Parameters:
      - + - + - +
      H5E_direction_t direction    H5E_direction_t direction     IN: Direction in which the error stack is to be walked.
      H5E_walk_t funcH5E_walk_t func IN: Function to be called for each error encountered.
      void * client_datavoid * client_data IN: Data to be passed with func.
    Returns: @@ -657,14 +1077,14 @@ SUBROUTINE
    Parameters:
      - + - + - +
      int nint n IN/OUT: Number of times this function has been called for this traversal of the stack.
      H5E_error_t *err_desc    H5E_error_t *err_desc     OUT: Error description.
      void *client_datavoid *client_data IN: A file pointer, or stderr if NULL.
    Returns: @@ -702,6 +1122,11 @@ SUBROUTINE And in this document, the HDF5 Reference Manual  
    +H5IM   +H5LT   +H5PT   +H5TB   +
    H5   H5A   H5D   @@ -726,7 +1151,7 @@ And in this document, the Describes HDF5 Release 1.7, the unreleased development branch; working toward HDF5 Release 1.8.0 -- cgit v0.12