/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Copyright by The HDF Group. * * All rights reserved. * * * * This file is part of HDF5. The full HDF5 copyright notice, including * * terms governing use, modification, and redistribution, is contained in * * the COPYING file, which can be found at the root of the source code * * distribution tree, or in https://www.hdfgroup.org/licenses. * * If you do not have access to either file, you may request a copy from * * help@hdfgroup.org. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ /* * Programmer: Quincey Koziol * Saturday, September 12, 2015 * * Purpose: This file contains declarations which define macros for the * H5E package. Including this header means that the source file * is part of the H5E package. */ #ifndef H5Emodule_H #define H5Emodule_H /* Define the proper control macros for the generic FUNC_ENTER/LEAVE and error * reporting macros. */ #define H5E_MODULE #define H5_MY_PKG H5E #define H5_MY_PKG_ERR H5E_ERROR #define H5_MY_PKG_INIT YES /** \page H5E_UG HDF5 Error Handling * * \section sec_error HDF5 Error Handling * * The HDF5 library provides an error reporting mechanism for both the library itself and for user * application programs. It can trace errors through function stack and error information like file * name, function name, line number, and error description. * * \subsection subsec_error_intro Introduction * The HDF5 Library provides an error reporting mechanism for both the library itself and for user application * programs. It can trace errors through function stack and error information like file name, function name, * line number, and error description. * * \ref subsec_error_ops discusses the basic error concepts such as error stack, error record, and error * message and describes the related API functions. These concepts and functions are sufficient for * application programs to trace errors inside the HDF5 Library. * * \ref subsec_error_adv talks about the advanced concepts of error * class and error stack handle and talks about the related functions. With these concepts and functions, an * application library or program using the HDF5 Library can have its own error report blended with HDF5’s * error report. * * Starting with Release 1.8, we have a new set of Error Handling API functions. For the purpose of backward * compatibility with version 1.6 and before, we still keep the old API functions, \ref H5Epush1, * \ref H5Eprint1, \ref H5Ewalk1, \ref H5Eclear1, \ref H5Eget_auto1, \ref H5Eset_auto1. These functions do * not have the error stack as a parameter. The library allows them to operate on the default error stack. * (The H5E compatibility macros will choose the correct function based on the parameters) * * The old API is similar to functionality discussed in \ref subsec_error_ops. The functionality discussed in * \ref subsec_error_adv,the ability of allowing applications to add their own error records, is the new * design for the Error Handling API. * * \subsection subsec_error_H5E Error Handling Function Summaries * @see H5E reference manual * * \subsection subsec_error_program Programming Model for Error Handling * This section is under construction. * * \subsection subsec_error_ops Basic Error Handling Operations * Let us first try to understand the error stack. An error stack is a collection of error records. Error * records can be pushed onto or popped off the error stack. By default, when an error occurs deep within * the HDF5 Library, an error record is pushed onto an error stack and that function returns a failure * indication. * Its caller detects the failure, pushes another record onto the stack, and returns a failure indication. * This continues until the API function called by the application returns a failure indication. The next * API function being called will reset the error stack. All HDF5 Library error records belong to the same * error class. For more information, see \ref subsec_error_adv. * * \subsubsection subsubsec_error_ops_stack Error Stack and Error Message * In normal circumstances, an error causes the stack to be printed on the standard error stream * automatically. * This automatic error stack is the library’s default stack. For all the functions in this section, whenever * an error stack ID is needed as a parameter, \ref H5E_DEFAULT can be used to indicate the library’s default * stack. The first error record of the error stack, number #000, is produced by the API function itself and * is usually sufficient to indicate to the application what went wrong. *
* If an application calls \ref H5Tclose on a * predefined datatype then the following message is * printed on the standard error stream. This is a * simple error that has only one component, the API * function; other errors may have many components. *
|
*
* An application can temporarily turn off error messages while “probing” a function. See the * example below. *
|
*
* Or automatic printing can be disabled altogether and error messages can be explicitly printed. *
|
*
*
|
*
*
|
*
* The following example shows a user‐defined callback function. *
|
*
* An error report shows both the library’s error record and the application’s error records. * See the example below. *
|
*
*
|
*
* The example below shows how an application creates an error class and error messages. *
|
*
* The example below shows how an application closes error messages and unregisters the error * class. *
|
*
* The example below shows how an application pushes an error record onto the default error stack. *
|
*
* The example below shows how an application registers the current error stack and * creates an object handle to avoid another HDF5 function from clearing the error stack. *
|
*