From edecc60b50455a42102cee189ccdac5c1bc2104e Mon Sep 17 00:00:00 2001 From: Frank Baker Date: Mon, 23 May 2005 11:21:28 -0500 Subject: [svn-r10784] Purpose: Complete H5Error API changes -- Changed and deprecated functions. Description: Added H5Eclear_stack, H5Eprint_stack, H5Epush_stack, H5Eget_auto_stack, H5Eset_auto_stack, H5Ewalk_stack. Added "deprecated function" notes to H5Eclear, H5Eprint, H5Epush, H5Eget_auto, H5Eset_auto, H5Ewalk, H5Eget_major, H5Eget_minor. Platforms tested: Firefox --- doc/html/RM_H5E.html | 624 +++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 577 insertions(+), 47 deletions(-) diff --git a/doc/html/RM_H5E.html b/doc/html/RM_H5E.html index c117396..3678b18 100644 --- a/doc/html/RM_H5E.html +++ b/doc/html/RM_H5E.html @@ -42,11 +42,13 @@ HDF5/H5E API Specification And in this document, the HDF5 Reference Manual   +
H5   H5A   @@ -81,28 +83,35 @@ These functions provide error handling capabilities in the HDF5 environment.               @@ -145,12 +158,14 @@ These functions provide error handling capabilities in the HDF5 environment. @@ -248,12 +263,13 @@ errors within the H5E package.
Fortran90 Interface: +
Name: H5Eclear -
Signature: +
Signature (deprecated):
herr_t H5Eclear(void)
Purpose:
Clears the error stack for the current thread. @@ -265,6 +281,12 @@ errors within the H5E package.

H5Eclear can fail if there are problems initializing the library. +

+ Note: + As of HDF5 Release 1.8, H5Eclear_stack + replaces H5Eclear and H5Eclear is designated + a deprecated function. H5Eclear may be removed + from the library at a future release.

Parameters:
    @@ -290,6 +312,59 @@ END SUBROUTINE h5eclear_f --> + + + +
    +
    +
    Name: H5Eclear_stack +
    Signature: +
    herr_t H5Eclear_stack(hid_t estack_id) +
    Purpose: +
    Clears the error stack for the current thread. +
    Description: +
    H5Eclear_stack clears the error stack specified + by estack_id for the current thread. +

    + If the value of estack_id is H5E_DEFAULT, + the current current error stack will be cleared. +

    + The current error stack is also cleared whenever an API function + is called, with certain exceptions + (for instance, H5Eprint). +

    + H5Eclear_stack can fail if there are problems initializing + the library. +

    Parameters: +
      None
      + + + +
      hid_t mesg_id    IN: Error message identifier.
    +
    Returns: +
    Returns a non-negative value if successful; + otherwise returns a negative value. +
    Fortran90 Interface: +
    None. + + +
    + +
    @@ -323,7 +398,7 @@ END SUBROUTINE h5eclear_f
    Name: H5Eclose_stack
    Signature:
    herr_t H5Eclose_stack(hid_t - error_stack) + estack_id)
    Purpose:
    Closes object handle for error stack.
    Description: @@ -333,7 +408,7 @@ END SUBROUTINE h5eclear_f
    Parameters:
    Returns: @@ -381,12 +456,13 @@ END SUBROUTINE h5eclear_f
    None. +
    Name: H5Eget_auto -
    Signature: +
    Signature (deprecated):
    herr_t H5Eget_auto(H5E_auto_t * func, void **client_data ) @@ -398,6 +474,12 @@ END SUBROUTINE h5eclear_f automatic error stack traversal function, func, and its data, client_data. Either (or both) arguments may be null in which case the value is not returned. +

    + Note: + As of HDF5 Release 1.8, H5Eget_auto_stack + replaces H5Eget_auto and H5Eget_auto is designated + a deprecated function. H5Eget_auto may be removed + from the library at a future release.

    Parameters:
      @@ -428,6 +510,66 @@ SUBROUTINE --> + + + +
      +
      +
      Name: H5Eget_auto_stack +
      Signature: +
      herr_t H5Eget_auto_stack( + hid_t estack_id, + H5E_auto_stack_t * func, + void **client_data + ) +
      Purpose: +
      Returns the current settings for the automatic error stack + traversal function and its data. +
      Description: +
      H5Eget_auto_stack returns the current settings for the + automatic error stack traversal function, func, + and its data, client_data, that are associated with + the error stack specified by estack_id. +

      + Either or both of the func and client_data + arguments may be null, in which case the value is not returned. +

      Parameters: +
        + + + + + + + + + +
        hid_t estack_id +     IN: Error stack identifier. + H5E_DEFAULT indicates the current stack.
        H5E_auto_stack_t * funcOUT: The function currently set to be + called upon an error condition.
        void **client_data    OUT: Data currently set to be passed + to the error function.
      +
      Returns: +
      Returns a non-negative value if successful; + otherwise returns a negative value. +
      Fortran90 Interface: +
      None. + + + + +
      + +
      @@ -498,7 +640,7 @@ SUBROUTINE
      Name: H5Eget_major -
      Signature: +
      Signature (deprecated):
      const char * H5Eget_major(H5E_major_t n)
      Purpose:
      Returns a character string describing an error specified by a @@ -506,6 +648,12 @@ SUBROUTINE
      Description:
      Given a major error number, H5Eget_major returns a constant character string that describes the error. +

      + Note: + As of HDF5 Release 1.8, H5Eget_msg + replaces H5Eget_major and H5Eget_major is designated + a deprecated function. H5Eget_major may be removed + from the library at a future release.

      Parameters:
        @@ -539,7 +687,7 @@ END SUBROUTINE h5eget_major_f
        Name: H5Eget_minor -
        Signature: +
        Signature (deprecated):
        const char * H5Eget_minor(H5E_minor_t n)
        Purpose:
        Returns a character string describing an error specified by a @@ -547,6 +695,12 @@ END SUBROUTINE h5eget_major_f
        Description:
        Given a minor error number, H5Eget_minor returns a constant character string that describes the error. +

        + Note: + As of HDF5 Release 1.8, H5Eget_msg + replaces H5Eget_minor and H5Eget_minor is designated + a deprecated function. H5Eget_minor may be removed + from the library at a future release.

        Parameters:
          @@ -627,17 +781,17 @@ END SUBROUTINE h5eget_minor_f
          Name: H5Eget_num
          Signature: -
          ssize_t H5Eget_num(hid_t error_stack) +
          ssize_t H5Eget_num(hid_t estack_id)
          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 + in the error stack specified by estack_id (including major, minor messages and description).
          Parameters:
            -
            hid_t error_stack + hid_t estack_id      IN: Error stack identifier.
          @@ -655,19 +809,19 @@ END SUBROUTINE h5eget_minor_f
          Name: H5Epop
          Signature:
          herr_t H5Epop(hid_t - error_stack, size_t count) + estack_id, 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 + specified by estack_id (including major, minor messages and description). The number of error messages to be deleted is specified by count.
          Parameters:
            - @@ -682,12 +836,13 @@ END SUBROUTINE h5eget_minor_f
            None. +
            Name: H5Eprint -
            Signature: +
            Signature (deprecated):
            herr_t H5Eprint(FILE * stream)
            Purpose:
            Prints the error stack in a default manner. @@ -701,6 +856,12 @@ END SUBROUTINE h5eget_minor_f H5Eprint is a convenience function for H5Ewalk with a function that prints error messages. Users are encouraged to write their own more specific error handlers. +

            + Note: + As of HDF5 Release 1.8, H5Eprint_stack + replaces H5Eprint and H5Eprint is designated + a deprecated function. H5Eprint may be removed + from the library at a future release.

            Parameters:
              hid_t error_stack + hid_t estack_id      IN: Error stack identifier.
              @@ -728,12 +889,80 @@ END SUBROUTINE h5eprint_f --> + + + +
              +
              +
              Name: H5Eprint_stack +
              Signature: +
              herr_t H5Eprint( + hid_t estack_id, + FILE * stream) +
              Purpose: +
              Prints the error stack in a default manner. +
              Description: +
              H5Eprint_stack prints the error stack specified by + estack_id on the specified stream, stream. + Even if the error stack is empty, a one-line message of the + following form will be printed: +
                   + HDF5-DIAG: Error detected in HDF5 library version: 1.5.62 + thread 0. +

              + A similar line will appear before the error messages of each + error class stating the library name, library version number, and + thread identifier. +

              + If estack_id is H5E_DEFAULT, + the current error stack will be printed. +

              + H5Eprint_stack is a convenience function for + H5Ewalk_stack with a function that prints error messages. + Users are encouraged to write their own more specific error handlers. +

              Parameters: +
                + + + + + + +
                hid_t estack_idIN: Identifier of the error stack to be printed. + If the identifier is H5E_DEFAULT, + the current error stack will be printed.
                FILE * stream    IN: File pointer, or stderr if NULL.
              +
              Returns: +
              Returns a non-negative value if successful; + otherwise returns a negative value. +
              Fortran90 Interface: +
              None. + + + +
              + +
              Name: H5Epush -
              Signature: +
              Signature (deprecated):
              herr_t H5Epush( const char *file, const char *func, @@ -755,24 +984,33 @@ END SUBROUTINE h5eprint_f the line line within that file, and an error description string str.

              - The function name, file name, and error description strings + The function name, filename, and error description strings must be statically allocated. -

              Parameters: +

              + Note: + As of HDF5 Release 1.8, H5Epush_stack + replaces H5Epush and H5Epush is designated + a deprecated function. H5Epush may be removed + from the library at a future release. +

              Parameters, H5Epush:
                - - + + - - + + - - + + - + - + @@ -799,6 +1037,99 @@ SUBROUTINE + +
                +
                +
                Name: H5Epush_stack +
                Signature: +
                herr_t H5Epush_stack( + hid_t estack_id, + const char *file, + const char *func, + unsigned line, + hid_t class_id, + hid_t major_id, + hid_t minor_id, + const char *msg, + ...) +
                Purpose: +
                Pushes new error record onto error stack. +
                Description: +
                H5Epush_stack pushes a new error record onto the + error stack for the current thread. +

                + The error record contains + the error class identifier class_id, + the major and minor message identifiers major_id and + minor_id, + the function name func where the error was detected, + the filename file and line number line + within that file where the error was detected, and + an error description msg. +

                + The major and minor errors must be in the same error class. +

                + The function name, filename, and error description strings + must be statically allocated. +

                + msg can be a format control string with + additional arguments. This design of appending additional arguments + is similar to the system and C functions printf and + fprintf. +

                Parameters: +
                  const char *file,IN: Name of the file in which the error was detected.
                  const char *fileIN: Name of the file in which the error + was detected.
                  const char *func,IN: Name of the function in which the error was detected.
                  const char *funcIN: Name of the function in which the error + was detected.
                  unsigned line,IN: Line within the file at which the error was detected.
                  unsigned lineIN: 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 *str
                  + + + + + + + + + + + + + + + + + + + + + + + + +
                  hid_t estack_idIN: Identifier of the error stack to which + the error record is to be pushed. + If the identifier is H5E_DEFAULT, the error record + will be pushed to the current stack.
                  const char *fileIN: Name of the file in which the error was + detected.
                  const char *funcIN: Name of the function in which the error was + detected.
                  unsigned lineIN: Line number within the file at which the + error was detected.
                  hid_t class_idIN: Error class identifier.
                  hid_t major_id    IN: Major error identifier.
                  hid_t minor_idIN: Minor error identifier.
                  const char *msgIN: Error description string.
                +
                Returns: +
                Returns a non-negative value if successful; + otherwise returns a negative value. +
                Fortran90 Interface: +
                None. + + + + +
                + +
                @@ -819,14 +1150,14 @@ SUBROUTINE
                Parameters:
                  - + - + - + @@ -838,12 +1169,13 @@ SUBROUTINE
                  None. +
                  Name: H5Eset_auto -
                  Signature: +
                  Signature (deprecated):
                  herr_t H5Eset_auto(H5E_auto_t func, void *client_data ) @@ -863,6 +1195,12 @@ SUBROUTINE

                  Automatic stack traversal is always in the H5E_WALK_DOWNWARD direction. +

                  + Note: + As of HDF5 Release 1.8, H5Eset_auto_stack + replaces H5Eset_auto and H5Eset_auto is designated + a deprecated function. H5Eset_auto may be removed + from the library at a future release.

                  Parameters:
                    const char* cls_name,    const char* cls_name     IN: Name of the error class.
                    const char* lib_name,const char* lib_name IN: Name of the client library or application to which the error class belongs.
                    const char* version,const char* version IN: Version of the client library or application to which the error class belongs. A NULL can be passed in.
                    @@ -897,6 +1235,85 @@ END SUBROUTINE h5eset_auto_f --> + + + + +
                    +
                    +
                    Name: H5Eset_auto_stack +
                    Signature: +
                    herr_t H5Eset_auto_stack( + hid_t estack_id, + H5E_auto_stack_t func, + void *client_data + ) +
                    Purpose: +
                    Turns automatic error printing on or off. +
                    Description: +
                    H5Eset_auto_stack turns on or off automatic printing of + errors for the error stack specified with estack_id. + An estack_id value of H5E_DEFAULT + indicates the current stack. +

                    + When automatic printing is turned on, + by the use of a non-null func pointer, + any API function which returns an error indication will + first call func, passing it client_data + as an argument. +

                    + When the library is first initialized, the auto printing function + is set to H5Eprint_stack (cast appropriately) and + client_data is the standard error stream pointer, + stderr. +

                    + Automatic stack traversal is always in the + H5E_WALK_DOWNWARD direction. +

                    + Automatic error printing is turned off with a + H5Eset_auto_stack call with a NULL + func pointer. +

                    Parameters: +
                      + + + + + + + + + +
                      hid_t estack_id    IN: Error stack identifier.
                      H5E_auto_stack_t funcIN: Function to be called upon an error + condition.
                      void *client_data    IN: Data passed to the error function.
                    +
                    Returns: +
                    Returns a non-negative value if successful; + otherwise returns a negative value. +
                    Fortran90 Interface: h5eset_auto_f +
                    None. + + + +
                    + +
                    @@ -904,17 +1321,17 @@ END SUBROUTINE h5eset_auto_f
                    Name: H5Eset_current_stack
                    Signature:
                    herr_t H5Eset_current_stack(hid_t - error_stack) + estack_id)
                    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. + specified by estack_id.
                    Parameters:
                    Returns: @@ -941,7 +1358,7 @@ END SUBROUTINE h5eset_auto_f
                    Parameters:
                    Returns: @@ -951,12 +1368,13 @@ END SUBROUTINE h5eset_auto_f
                    None. +
                    Name: H5Ewalk -
                    Signature: +
                    Signature (deprecated):
                    herr_t H5Ewalk(H5E_direction_t direction, H5E_walk_t func, void * client_data @@ -1008,6 +1426,12 @@ END SUBROUTINE h5eset_auto_f

                    H5Ewalk can fail if there are problems initializing the library. +

                    + Note: + As of HDF5 Release 1.8, H5Ewalk_stack + replaces H5Ewalk and H5Ewalk is designated + a deprecated function. H5Ewalk may be removed + from the library at a future release.

                    Parameters:
                      @@ -1040,6 +1464,112 @@ SUBROUTINE --> + + + +
                      +
                      +
                      Name: H5Ewalk_stack +
                      Signature: +
                      herr_t H5Ewalk_stack( + hid_t estack_id, + H5E_direction_t direction, + H5E_walk_t func, + void * client_data + ) +
                      Purpose: +
                      Walks the error stack for the current thread, calling a specified + function. +
                      Description: +
                      H5Ewalk_stack walks the error stack specified by + estack_id for the current thread and calls the function + specified in func for each error along the way. +

                      + If the value of estack_id is H5E_DEFAULT, + then H5Ewalk_stack walks the current error stack. +

                      + direction specifies whether the stack is walked + from the inside out or the outside in. + A value of H5E_WALK_UPWARD means to begin with the + most specific error and end at the API; + a value of H5E_WALK_DOWNWARD means to start at the + API and end at the innermost function where the error was first + detected. +

                      + func, a function compliant with the + H5E_walk_t prototype, will be called for each error + in the error stack. + Its arguments will include an index number n + (beginning at zero regardless of stack traversal direction), + an error stack entry err_desc, + and the client_data pointer passed to + H5E_print. + The H5E_walk_t prototype is as follows: +

                      +

                      + typedef herr_t (*H5E_walk_t)(int n, + H5E_error_t *err_desc, + void *client_data) +

                      + where the parameters have the following meanings: +

                      +
                      int n +
                      Indexed position of the error in the stack. +
                      H5E_error_t *err_desc +
                      Pointer to a data structure describing the error. + (This structure is currently described only in the source + code file hdf5/src/H5Epublic.h. + That file also contains the definitive list of major + and minor error codes; that information will + eventually be presented as an appendix to this + HDF5 Reference Manual.) +
                      void *client_data +
                      Pointer to client data in the format expected by + the user-defined function. +
                      +                       +

                      + H5Ewalk_stack can fail if there are problems initializing + the library. +

                      Parameters: +
                        + + + + + + + + + + + + +
                        hid_t estack_idIN: Error stack identifier.
                        H5E_direction_t direction    IN: Direction in which the error stack is + to be walked.
                        H5E_walk_t funcIN: Function to be called for each error + encountered.
                        void * client_dataIN: Data to be passed with func. +
                      +
                      Returns: +
                      Returns a non-negative value if successful; + otherwise returns a negative value. +
                      Fortran90 Interface: +
                      None. + + + + +
                      + +
                      @@ -1151,7 +1681,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