mirror of
https://github.com/HDFGroup/hdf5.git
synced 2024-12-09 07:32:32 +08:00
dd99ecc1bc
A little editorial cleanup. Added link to Ragged.html, Ragged Arrays. Added link to Environment.html, Environmental Variables and Configuration Parameters. Added link to Copyright.html. Ragged.html Added "Use at your own risk" notice. Environment.html New file for environmental variables and configuration parameters. Datatypes.html Added the following datatypes: H5T_NATIVE_HSIZE H5T_NATIVE_HSSIZE H5T_NATIVE_HERR H5T_NATIVE_HBOOL Section 8, "Data Conversions" Added named link tag to catch hyperlink from RM. Revised "Note:" to emphasize limited inate data-conversion capability. Copyright.html New file. Copyright statement, linked into User's Guide and Reference Manual. Glossary.html Unlinked for Beta. General Changed email link at bottom of "user guide level documents" (as contrasted with "developer guide level documents" listed on the lower half of the User's Guide front page) to HDF Help Desk, hdfhelp@ncsa.uiuc.edu. Changed the following function names: From: To: H5version H5get_libversion H5vers_check H5check_version H5Anum_attrs H5Aget_num_attrs H5Fget_create_template() H5Fget_create_plist() H5Fget_access_template() H5Fget_access_plist() H5Gstat H5Gget_stat H5Sextent_npoints H5Sget_simple_extent_npoints H5Sextent_ndims H5Sget_simple_extent_ndims H5Sextent_dims H5Sget_simple_extent_dims H5Sget_class H5Sget_simple_extent_type H5Sselect_npoints H5Sget_select_npoints
294 lines
9.4 KiB
HTML
294 lines
9.4 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
|
|
<html>
|
|
<head>
|
|
<title>The Error Handling Interface (H5E)</title>
|
|
</head>
|
|
|
|
<body>
|
|
<h1>The Error Handling Interface (H5E)</h1>
|
|
|
|
<h2>1. Introduction</h2>
|
|
|
|
<p>When an error occurs deep within the HDF5 library a 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 application-called API function returns a
|
|
failure indication (a negative integer or null pointer). The
|
|
next API function which is called (with a few exceptions) resets
|
|
the stack.
|
|
|
|
<p>In normal circumstances, an error causes the stack to be
|
|
printed on the standard error stream. The first item, number
|
|
"#000" is produced by the API function itself and is usually
|
|
sufficient to indicate to the application programmer what went
|
|
wrong.
|
|
|
|
<p>
|
|
<center>
|
|
<table border align=center width="100%">
|
|
<caption align=top><h4>Example: An Error Message</h4></caption>
|
|
<tr>
|
|
<td>
|
|
<p>If an application calls <code>H5Tclose</code> on a
|
|
predefined data type 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.
|
|
|
|
<p><code><pre>
|
|
HDF5-DIAG: Error detected in thread 0. Back trace follows.
|
|
#000: H5T.c line 462 in H5Tclose(): predefined data type
|
|
major(01): Function argument
|
|
minor(05): Bad value
|
|
</code></pre>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</center>
|
|
|
|
<p>The error stack can also be printed and manipulated by these
|
|
functions, but if an application wishes make explicit calls to
|
|
<code>H5Eprint()</code> then the automatic printing should be
|
|
turned off to prevent error messages from being displayed twice
|
|
(see <code>H5Eset_auto()</code> below).
|
|
|
|
<dl>
|
|
<dt><code>herr_t H5Eprint (FILE *<em>stream</em>)</code>
|
|
<dd>The error stack is printed on the specified stream. Even if
|
|
the error stack is empty a one-line message will be printed:
|
|
<code>HDF5-DIAG: Error detected in thread 0.</code>
|
|
|
|
<br><br>
|
|
<dt><code>herr_t H5Eclear (void)</code>
|
|
<dd>The error stack can be explicitly cleared by calling this
|
|
function. The stack is also cleared whenever an API function
|
|
is called, with certain exceptions (for instance,
|
|
<code>H5Eprint()</code>).
|
|
</dl>
|
|
|
|
<p>Sometimes an application will call a function for the sake of
|
|
its return value, fully expecting the function to fail. Under
|
|
these conditions, it would be misleading if an error message
|
|
were automatically printed. Automatic printing of messages is
|
|
controlled by the <code>H5Eset_auto()</code> function:
|
|
|
|
<dl>
|
|
<dt><code>herr_t H5Eset_auto (herr_t(*<em>func</em>)(void*),
|
|
void *<em>client_data</em>)</code>
|
|
<dd>If <em>func</em> is not a null pointer, then the function to
|
|
which it points will be called automatically when an API
|
|
function is about to return an indication of failure. The
|
|
function is called with a single argument, the
|
|
<em>client_data</em> pointer. When the library is first
|
|
initialized the auto printing function is set to
|
|
<code>H5Eprint()</code> (cast appropriately) and
|
|
<em>client_data</em> is the standard error stream pointer,
|
|
<code>stderr</code>.
|
|
|
|
<br><br>
|
|
<dt><code>herr_t H5Eget_auto (herr_t(**<em>func</em>)(void*),
|
|
void **<em>client_data</em>)</code>
|
|
<dd>This function returns the current automatic error traversal
|
|
settings through the <em>func</em> and <em>client_data</em>
|
|
arguments. Either (or both) arguments may be null pointers in
|
|
which case the corresponding information is not returned.
|
|
</dl>
|
|
|
|
<p>
|
|
<center>
|
|
<table border align=center width="100%">
|
|
<caption align=top><h4>Example: Error Control</h4></caption>
|
|
<tr>
|
|
<td>
|
|
<p>An application can temporarily turn off error
|
|
messages while "probing" a function.
|
|
|
|
<p><code><pre>
|
|
/* Save old error handler */
|
|
herr_t (*old_func)(void*);
|
|
void *old_client_data;
|
|
H5Eget_auto(&old_func, &old_client_data);
|
|
|
|
/* Turn off error handling */
|
|
H5Eset_auto(NULL, NULL);
|
|
|
|
/* Probe. Likely to fail, but that's okay */
|
|
status = H5Fopen (......);
|
|
|
|
/* Restore previous error handler */
|
|
H5Eset_auto(old_func, old_client_data);
|
|
</code></pre>
|
|
|
|
<p>Or automatic printing can be disabled altogether and
|
|
error messages can be explicitly printed.
|
|
|
|
<p><code><pre>
|
|
/* Turn off error handling permanently */
|
|
H5Eset_auto (NULL, NULL);
|
|
|
|
/* If failure, print error message */
|
|
if (H5Fopen (....)<0) {
|
|
H5Eprint (stderr);
|
|
exit (1);
|
|
}
|
|
</code></pre>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</center>
|
|
|
|
<p>The application is allowed to define an automatic error
|
|
traversal function other than the default
|
|
<code>H5Eprint()</code>. For instance, one could define a
|
|
function that prints a simple, one-line error message to the
|
|
standard error stream and then exits.
|
|
|
|
<p>
|
|
<center>
|
|
<table border align=center width="100%">
|
|
<caption align=top><h4>Example: Simple Messages</h4></caption>
|
|
<tr>
|
|
<td>
|
|
<p>The application defines a function to print a simple
|
|
error message to the standard error stream.
|
|
|
|
<p><code><pre>
|
|
herr_t
|
|
my_hdf5_error_handler (void *unused)
|
|
{
|
|
fprintf (stderr, "An HDF5 error was detected. Bye.\n");
|
|
exit (1);
|
|
}
|
|
</code></pre>
|
|
|
|
<p>The function is installed as the error handler by
|
|
saying
|
|
|
|
<p><code><pre>
|
|
H5Eset_auto (my_hdf5_error_handler, NULL);
|
|
</code></pre>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</center>
|
|
|
|
<p>The <code>H5Eprint()</code> function is actually just a wrapper
|
|
around the more complex <code>H5Ewalk()</code> function which
|
|
traverses an error stack and calls a user-defined function for
|
|
each member of the stack.
|
|
|
|
<dl>
|
|
<dt><code>herr_t H5Ewalk (H5E_direction_t <em>direction</em>,
|
|
H5E_walk_t <em>func</em>, void *<em>client_data</em>)</code>
|
|
<dd>The error stack is traversed and <em>func</em> is called for
|
|
each member of the stack. Its arguments are an integer
|
|
sequence number beginning at zero (regardless of
|
|
<em>direction</em>), a pointer to an error description record,
|
|
and the <em>client_data</em> pointer. If <em>direction</em>
|
|
is <code>H5E_WALK_UPWARD</em> then traversal begins at the
|
|
inner-most function that detected the error and concludes with
|
|
the API function. The opposite order is
|
|
<code>H5E_WALK_DOWNWARD</code>.
|
|
|
|
<br><br>
|
|
<dt><code>typedef herr_t (*H5E_walk_t)(int <em>n</em>,
|
|
H5E_error_t *<em>eptr</em>, void
|
|
*<em>client_data</em>)</code>
|
|
<dd>An error stack traversal callback function takes three
|
|
arguments: <em>n</em> is a sequence number beginning at zero
|
|
for each traversal, <em>eptr</em> is a pointer to an error
|
|
stack member, and <em>client_data</em> is the same pointer
|
|
passed to <code>H5Ewalk()</code>.
|
|
|
|
<br><br>
|
|
<dt><pre><code>typedef struct {
|
|
H5E_major_t <em>maj_num</em>;
|
|
H5E_minor_t <em>min_num</em>;
|
|
const char *<em>func_name</em>;
|
|
const char *<em>file_name</em>;
|
|
unsigned <em>line</em>;
|
|
const char *<em>desc</em>;
|
|
} H5E_error_t;</code></pre>
|
|
<dd>The <em>maj_num</em> and <em>min_num</em> are major
|
|
and minor error numbers, <em>func_name</em> is the name of
|
|
the function where the error was detected,
|
|
<em>file_name</em> and <em>line</em> locate the error
|
|
within the HDF5 library source code, and <em>desc</em>
|
|
points to a description of the error.
|
|
|
|
<br><br>
|
|
<dt><code>const char *H5Eget_major (H5E_major_t <em>num</em>)</code>
|
|
<dt><code>const char *H5Eget_minor (H5E_minor_t <em>num</em>)</code>
|
|
<dd>These functions take a major or minor error number and
|
|
return a constant string which describes the error. If
|
|
<em>num</em> is out of range than a string like "Invalid major
|
|
error number" is returned.
|
|
</dl>
|
|
|
|
<p>
|
|
<center>
|
|
<table border align=center width="100%">
|
|
<caption align=top><h4>Example: H5Ewalk_cb</h4></caption>
|
|
<tr>
|
|
<td>
|
|
<p>This is the implementation of the default error stack
|
|
traversal callback.
|
|
|
|
<p><code><pre>
|
|
herr_t
|
|
H5Ewalk_cb(int n, H5E_error_t *err_desc, void *client_data)
|
|
{
|
|
FILE *stream = (FILE *)client_data;
|
|
const char *maj_str = NULL;
|
|
const char *min_str = NULL;
|
|
const int indent = 2;
|
|
|
|
/* Check arguments */
|
|
assert (err_desc);
|
|
if (!client_data) client_data = stderr;
|
|
|
|
/* Get descriptions for the major and minor error numbers */
|
|
maj_str = H5Eget_major (err_desc->maj_num);
|
|
min_str = H5Eget_minor (err_desc->min_num);
|
|
|
|
/* Print error message */
|
|
fprintf (stream, "%*s#%03d: %s line %u in %s(): %s\n",
|
|
indent, "", n, err_desc->file_name, err_desc->line,
|
|
err_desc->func_name, err_desc->desc);
|
|
fprintf (stream, "%*smajor(%02d): %s\n",
|
|
indent*2, "", err_desc->maj_num, maj_str);
|
|
fprintf (stream, "%*sminor(%02d): %s\n",
|
|
indent*2, "", err_desc->min_num, min_str);
|
|
|
|
return 0;
|
|
}
|
|
</code></pre>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</center>
|
|
|
|
|
|
|
|
<!--
|
|
<hr>
|
|
<address><a href="mailto:hdf5dev@ncsa.uiuc.edu">Robb Matzke</a></address>
|
|
-->
|
|
<!-- Created: Fri Feb 27 23:42:52 EST 1998 -->
|
|
<!-- hhmts start -->
|
|
<!--
|
|
Last modified: Wed Mar 4 10:06:17 EST 1998
|
|
-->
|
|
<!-- hhmts end -->
|
|
|
|
<hr>
|
|
<address>
|
|
<a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a>
|
|
</address>
|
|
|
|
Last modified: 9 September 1998
|
|
|
|
</body>
|
|
</html>
|