mirror of
https://github.com/HDFGroup/hdf5.git
synced 2024-11-27 02:10:55 +08:00
fd05f98e9e
Purpose:
Marking files for "Release 1.4, February 2001."
Description:
Across doc files
Updating "Describes HDF5 Release..." entry to "Describes
HDF5 Release 1.4, February 2001."
Copyright.html: Added 2001 to years copyrighted.
index.html: Changed header to Release 1.4 (from 1.4 Beta)
Platforms tested:
IE 5
375 lines
12 KiB
HTML
375 lines
12 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
|
|
<html>
|
|
<head>
|
|
<title>Error Handling Interface (H5E)</title>
|
|
</head>
|
|
|
|
<body bgcolor="#FFFFFF">
|
|
|
|
|
|
<hr>
|
|
<center>
|
|
<table border=0 width=98%>
|
|
<tr><td valign=top align=left>
|
|
<a href="H5.intro.html">Introduction to HDF5</a> <br>
|
|
<a href="RM_H5Front.html">HDF5 Reference Manual</a> <br>
|
|
<a href="index.html">Other HDF5 documents and links</a> <br>
|
|
<!--
|
|
<a href="Glossary.html">Glossary</a><br>
|
|
-->
|
|
</td>
|
|
<td valign=top align=right>
|
|
And in this document, the
|
|
<a href="H5.user.html"><strong>HDF5 User's Guide:</strong></a>
|
|
<br>
|
|
<a href="Files.html">Files</a>
|
|
<a href="Datasets.html">Datasets</a>
|
|
<a href="Datatypes.html">Datatypes</a>
|
|
<a href="Dataspaces.html">Dataspaces</a>
|
|
<a href="Groups.html">Groups</a>
|
|
<br>
|
|
<a href="References.html">References</a>
|
|
<a href="Attributes.html">Attributes</a>
|
|
<a href="Properties.html">Property Lists</a>
|
|
Error Handling
|
|
<br>
|
|
<a href="Filters.html">Filters</a>
|
|
<a href="Caching.html">Caching</a>
|
|
<a href="Chunking.html">Chunking</a>
|
|
<a href="MountingFiles.html">Mounting Files</a>
|
|
<br>
|
|
<a href="Performance.html">Performance</a>
|
|
<a href="Debugging.html">Debugging</a>
|
|
<a href="Environment.html">Environment</a>
|
|
<a href="ddl.html">DDL</a>
|
|
</td></tr>
|
|
</table>
|
|
</center>
|
|
<hr>
|
|
|
|
|
|
<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.
|
|
|
|
<h2>2. Error Handling Operations</h2>
|
|
|
|
<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 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.
|
|
|
|
<p><code><pre>
|
|
HDF5-DIAG: Error detected in thread 0. Back trace follows.
|
|
#000: H5T.c line 462 in H5Tclose(): predefined datatype
|
|
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</code> 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>
|
|
<center>
|
|
<table border=0 width=98%>
|
|
<tr><td valign=top align=left>
|
|
<a href="H5.intro.html">Introduction to HDF5</a> <br>
|
|
<a href="RM_H5Front.html">HDF5 Reference Manual</a> <br>
|
|
<a href="index.html">Other HDF5 documents and links</a> <br>
|
|
<!--
|
|
<a href="Glossary.html">Glossary</a><br>
|
|
-->
|
|
</td>
|
|
<td valign=top align=right>
|
|
And in this document, the
|
|
<a href="H5.user.html"><strong>HDF5 User's Guide:</strong></a>
|
|
<br>
|
|
<a href="Files.html">Files</a>
|
|
<a href="Datasets.html">Datasets</a>
|
|
<a href="Datatypes.html">Datatypes</a>
|
|
<a href="Dataspaces.html">Dataspaces</a>
|
|
<a href="Groups.html">Groups</a>
|
|
<br>
|
|
<a href="References.html">References</a>
|
|
<a href="Attributes.html">Attributes</a>
|
|
<a href="Properties.html">Property Lists</a>
|
|
Error Handling
|
|
<br>
|
|
<a href="Filters.html">Filters</a>
|
|
<a href="Caching.html">Caching</a>
|
|
<a href="Chunking.html">Chunking</a>
|
|
<a href="MountingFiles.html">Mounting Files</a>
|
|
<br>
|
|
<a href="Performance.html">Performance</a>
|
|
<a href="Debugging.html">Debugging</a>
|
|
<a href="Environment.html">Environment</a>
|
|
<a href="ddl.html">DDL</a>
|
|
</td></tr>
|
|
</table>
|
|
</center>
|
|
|
|
|
|
|
|
<hr>
|
|
<address>
|
|
<a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a>
|
|
</address>
|
|
|
|
<!-- Created: Fri Feb 27 23:42:52 EST 1998 -->
|
|
<!-- hhmts start -->
|
|
Last modified: 13 December 1999
|
|
<!-- hhmts end -->
|
|
|
|
<br>
|
|
Describes HDF5 Release 1.4, February 2001
|
|
|
|
|
|
</body>
|
|
</html>
|