750856c53a
Added link to Tools.html
Clean up formatting.
Added RM_H5R.html, Ragged Arrays, but link is commented out for Beta.
RM_H5.html
H5version Removed patch number parameter.
H5check_version Removed patch number parameter.
Corrected datatype to unsigned (was unsigned *).
Added missing "Purpose:" statement.
RM_H5A.html
H5Aread/write Added reference to data conversion limitations.
RM_H5D.html
H5Dwrite Added "Writing to an external dataset will fail
if the HDF5 file is not open for writing."
H5Dread/write Added reference to data conversion limitations.
RM_H5F.html
H5Fflush Added H5Fflush.
RM_H5G.html
H5Gget_stat Fixed formatting error.
Added mtime to the description of the data structure.
Added the following "Note:", per Robb's checkin mesage:
"Some systems will be able to record the time
accurately but unable to retrieve the correct time;
such systems (e.g., Irix64) will report an mtime
value of 0 (zero)."
Corrected successful return value.
H5Gset_comment Added the following statement to "Description:"
"Comments can be attached to any object that
has an object header, e.g., data sets, groups,
named data types, and data spaces,
but not symbolic links.
RM_H5P.html
Cleaned up file formatting.
H5Pset_filter Added these three functions.
H5Pget_nfilters
H5Pget_filter
H5Pget_deflate Removed these three functions. (Actually,
H5Pset_compression they are commented out, in case they should
H5Pget_compression be reinstated.)
RM_H5R.html
Intial version of H5R reference manual entry, but still largely
just a template.
Not yet ready for distribution.
Links to this document are currently commented out.
RM_H5S.html
H5S_set_extent_simple Changed name to H5Sselect_extent_simple.
now: H5Sselect_extent_simpl
H5Sselect_npoints Corrected return value.
Now: H5Sget_select_npoints
H5Sget_class Reinstated to RM. Changed name.
now: H5Sget_space_type
H5Soffset_simple Added these 6 functions. The there is a
H5Sextent_copy link to Dataspaces.html for the 10 "not yet
H5Sset_extent_none implemented (NYI)" functions.
H5Sselect_all
H5Sselect_none
H5Sselect_valid
RM_H5T.html
Added the following datatypes (though the list of native datatypes
is commented out):
H5T_NATIVE_HSIZE
H5T_NATIVE_HSSIZE
H5T_NATIVE_HERR
H5T_NATIVE_HBOOL
Tools.html
Corrected h5ls and h5repart sections.
Glossary.html
Unlinked for Beta.
Copyright.html
New file.
Copyright statement, linked into User's Guide and Reference Manual.
General
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
And associated "template" -> "property list" edits.
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
Added links to Tools.html and RM_H5R.html (Ragged Arrays),
though link to RM_H5R.html is commented out for now.
368 lines
13 KiB
HTML
368 lines
13 KiB
HTML
<html>
|
|
<head><title>
|
|
HDF5/H5E Draft API Specification
|
|
</title></head>
|
|
|
|
<body>
|
|
|
|
<hr>
|
|
<center>
|
|
<a href="RM_H5Front.html">HDF5 Reference Manual</a>
|
|
<a href="RM_H5.html">H5</a>
|
|
<a href="RM_H5A.html">H5A</a>
|
|
<a href="RM_H5D.html">H5D</a>
|
|
H5E
|
|
<a href="RM_H5F.html">H5F</a>
|
|
<a href="RM_H5G.html">H5G</a>
|
|
<a href="RM_H5P.html">H5P</a>
|
|
<a href="RM_H5S.html">H5S</a>
|
|
<a href="RM_H5T.html">H5T</a>
|
|
<a href="RM_H5Z.html">H5Z</a>
|
|
<a href="Tools.html">Tools</a>
|
|
<!--
|
|
<a href="Glossary.html">Glossary</a>
|
|
-->
|
|
</center>
|
|
<hr>
|
|
|
|
<center>
|
|
<h1>H5E: Error Interface</h1>
|
|
</center>
|
|
|
|
<h2>Error API Functions</h2>
|
|
|
|
These functions provide error handling capabilities in the HDF5 environment.
|
|
|
|
<table border=0>
|
|
<tr><td valign=top>
|
|
<ul>
|
|
<li><a href="#Error-SetAuto">H5Eset_auto</a>
|
|
<li><a href="#Error-GetAuto">H5Eget_auto</a>
|
|
<li><a href="#Error-Clear">H5Eclear</a>
|
|
</ul>
|
|
</td><td> </td><td valign=top>
|
|
<ul>
|
|
<li><a href="#Error-Print">H5Eprint</a>
|
|
<li><a href="#Error-Walk">H5Ewalk</a>
|
|
<li><a href="#Error-WalkCB">H5Ewalk_cb</a>
|
|
</ul>
|
|
</td><td> </td><td valign=top>
|
|
<ul>
|
|
<li><a href="#Error-GetMajor">H5Eget_major</a>
|
|
<li><a href="#Error-GetMinor">H5Eget_minor</a>
|
|
</ul>
|
|
</td></tr>
|
|
</table>
|
|
|
|
<p>
|
|
The Error interface provides error handling in the form of a stack.
|
|
The <code>FUNC_ENTER()</code> macro clears the error stack whenever
|
|
an interface function is entered.
|
|
When an error is detected, an entry is pushed onto the stack.
|
|
As the functions unwind, additional entries are pushed onto the stack.
|
|
The API function will return some indication that an error occurred and
|
|
the application can print the error stack.
|
|
<p>
|
|
Certain API functions in the H5E package, such as <code>H5Eprint()</code>,
|
|
do not clear the error stack. Otherwise, any function which
|
|
does not have an underscore immediately after the package name
|
|
will clear the error stack. For instance, <code>H5Fopen()</code>
|
|
clears the error stack while <code>H5F_open()</code> does not.
|
|
<p>
|
|
An error stack has a fixed maximum size.
|
|
If this size is exceeded then the stack will be truncated and only the
|
|
inner-most functions will have entries on the stack.
|
|
This is expected to be a rare condition.
|
|
<p>
|
|
Each thread has its own error stack, but since
|
|
multi-threading has not been added to the library yet, this
|
|
package maintains a single error stack. The error stack is
|
|
statically allocated to reduce the complexity of handling
|
|
errors within the H5E package.
|
|
|
|
|
|
<hr>
|
|
<dl>
|
|
<dt><strong>Name:</strong> <a name="Error-SetAuto">H5Eset_auto</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>herr_t</em> <code>H5Eset_auto</code>(<em>H5E_auto_t</em> <code>func</code>,
|
|
<em>void *</em><code>client_data</code>
|
|
)
|
|
<dt><strong>Purpose:</strong>
|
|
<dd>Turns automatic error printing on or off.
|
|
<dt><strong>Description:</strong>
|
|
<dd><code>H5Eset_auto</code> turns on or off automatic printing of
|
|
errors. When turned on (non-null <code>func</code> pointer),
|
|
any API function which returns an error indication will
|
|
first call <code>func</code>, passing it <code>client_data</code>
|
|
as an argument.
|
|
<p>
|
|
When the library is first initialized the auto printing function
|
|
is set to <code>H5Eprint()</code> (cast appropriately) and
|
|
<code>client_data</code> is the standard error stream pointer,
|
|
<code>stderr</code>.
|
|
<p>
|
|
Automatic stack traversal is always in the
|
|
<code>H5E_WALK_DOWNWARD</code> direction.
|
|
<dt><strong>Parameters:</strong>
|
|
<dl>
|
|
<dt><em>H5E_auto_t</em> <code>func</code>
|
|
<dd>Function to be called upon an error condition.
|
|
<dt><em>void *</em><code>client_data</code>
|
|
<dd>Data passed to the error function.
|
|
</dl>
|
|
<dt><strong>Returns:</strong>
|
|
<dd>Returns SUCCEED (0) if successful;
|
|
otherwise FAIL (-1).
|
|
</dl>
|
|
|
|
|
|
<hr>
|
|
<dl>
|
|
<dt><strong>Name:</strong> <a name="Error-GetAuto">H5Eget_auto</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>herr_t</em> <code>H5Eget_auto</code>(<em>H5E_auto_t *</em> <code>func</code>,
|
|
<em>void **</em><code>client_data</code>
|
|
)
|
|
<dt><strong>Purpose:</strong>
|
|
<dd>Returns the current settings for the automatic error stack
|
|
traversal function and its data.
|
|
<dt><strong>Description:</strong>
|
|
<dd><code>H5Eget_auto</code> returns the current settings for the
|
|
automatic error stack traversal function, <code>func</code>,
|
|
and its data, <code>client_data</code>. Either (or both)
|
|
arguments may be null in which case the value is not returned.
|
|
<dt><strong>Parameters:</strong>
|
|
<dl>
|
|
<dt><em>H5E_auto_t *</em> <code>func</code>
|
|
<dd>Current setting for the function to be called upon an
|
|
error condition.
|
|
<dt><em>void **</em><code>client_data</code>
|
|
<dd>Current setting for the data passed to the error function.
|
|
</dl>
|
|
<dt><strong>Returns:</strong>
|
|
<dd>Returns SUCCEED (0) if successful;
|
|
otherwise FAIL (-1).
|
|
</dl>
|
|
|
|
|
|
<hr>
|
|
<dl>
|
|
<dt><strong>Name:</strong> <a name="Error-Clear">H5Eclear</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>herr_t</em> <code>H5Eclear</code>(<code>void</code>)
|
|
<dt><strong>Purpose:</strong>
|
|
<dd>Clears the error stack for the current thread.
|
|
<dt><strong>Description:</strong>
|
|
<dd><code>H5Eclear</code> clears the error stack for the current thread.
|
|
<p>
|
|
The stack is also cleared whenever an API function is called,
|
|
with certain exceptions (for instance, <code>H5Eprint()</code>).
|
|
<p>
|
|
<code>H5Eclear</code> can fail if there are problems initializing
|
|
the library.
|
|
<dt><strong>Parameters:</strong>
|
|
<dl>
|
|
<dt>None
|
|
</dl>
|
|
<dt><strong>Returns:</strong>
|
|
<dd>Returns SUCCEED (0) if successful;
|
|
otherwise FAIL (-1).
|
|
</dl>
|
|
|
|
|
|
<hr>
|
|
<dl>
|
|
<dt><strong>Name:</strong> <a name="Error-Print">H5Eprint</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>herr_t</em> <code>H5Eprint</code>(<em>FILE *</em> <code>stream</code>)
|
|
<dt><strong>Purpose:</strong>
|
|
<dd>Prints the error stack in a default manner.
|
|
<dt><strong>Description:</strong>
|
|
<dd><code>H5Eprint</code> prints the error stack on the specified
|
|
stream, <code>stream</code>.
|
|
Even if the error stack is empty, a one-line message will be printed:
|
|
<br>
|
|
<code>HDF5-DIAG: Error detected in thread 0.</code>
|
|
<p>
|
|
<code>H5Eprint</code> is a convenience function for
|
|
<code>H5Ewalk()</code> with a function that prints error messages.
|
|
Users are encouraged to write there own more specific error handlers.
|
|
<dt><strong>Parameters:</strong>
|
|
<dl>
|
|
<dt><em>FILE *</em> <code>stream</code>
|
|
<dd>File pointer, or stderr if NULL.
|
|
</dl>
|
|
<dt><strong>Returns:</strong>
|
|
<dd>Returns SUCCEED (0) if successful;
|
|
otherwise FAIL (-1).
|
|
</dl>
|
|
|
|
|
|
<hr>
|
|
<dl>
|
|
<dt><strong>Name:</strong> <a name="Error-Walk">H5Ewalk</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>herr_t</em> <code>H5Ewalk</code>(<em>H5E_direction_t</em> <code>direction</code>,
|
|
<em>H5E_walk_t</em> <code>func</code>,
|
|
<em>void *</em> <code>client_data</code>
|
|
)
|
|
<dt><strong>Purpose:</strong>
|
|
<dd>Walks the error stack for the current thread, calling a specified
|
|
function.
|
|
<dt><strong>Description:</strong>
|
|
<dd><code>H5Ewalk</code> walks the error stack for the current thread
|
|
and calls the specified function for each error along the way.
|
|
<p>
|
|
<code>direction</code> determines whether the stack is walked
|
|
from the inside out or the outside in.
|
|
A value of <code>H5E_WALK_UPWARD</code> means begin with the
|
|
most specific error and end at the API;
|
|
a value of <code>H5E_WALK_DOWNWARD</code> means to start at the
|
|
API and end at the inner-most function where the error was first
|
|
detected.
|
|
<p>
|
|
<code>func</code> will be called for each error in the error stack.
|
|
Its arguments will include an index number (beginning at zero
|
|
regardless of stack traversal direction), an error stack entry,
|
|
and the <code>client_data</code> pointer passed to
|
|
<code>H5E_print</code>.
|
|
<p>
|
|
<code>H5Ewalk</code> can fail if there are problems initializing
|
|
the library.
|
|
<dt><strong>Parameters:</strong>
|
|
<dl>
|
|
<dt><em>H5E_direction_t</em> <code>direction</code>
|
|
<dd>Direction in which the error stack is to be walked.
|
|
<dt><em>H5E_walk_t</em> <code>func</code>
|
|
<dd>Function to be called for each error encountered.
|
|
<dt><em>void *</em> <code>client_data</code>
|
|
<dd>Data to be passed with <code>func</code>.
|
|
</dl>
|
|
<dt><strong>Returns:</strong>
|
|
<dd>Returns SUCCEED (0) if successful;
|
|
otherwise FAIL (-1).
|
|
</dl>
|
|
|
|
|
|
<hr>
|
|
<dl>
|
|
<dt><strong>Name:</strong> <a name="Error-WalkCB">H5Ewalk_cb</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>herr_t</em> <code>H5Ewalk_cb</code>(<em>int</em> <code>n</code>,
|
|
<em>H5E_error_t *</em><code>err_desc</code>,
|
|
<em>void</em> <code>*client_data</code>
|
|
)
|
|
<dt><strong>Purpose:</strong>
|
|
<dd>Default error stack traversal callback function
|
|
that prints error messages to the specified output stream.
|
|
<dt><strong>Description:</strong>
|
|
<dd><code>H5Ewalk_cb</code> is a default error stack traversal callback
|
|
function that prints error messages to the specified output stream.
|
|
It is not meant to be called directly but rather as an
|
|
argument to the <code>H5Ewalk()</code> function.
|
|
This function is called also by <code>H5Eprint()</code>.
|
|
Application writers are encouraged to use this function as a
|
|
model for their own error stack walking functions.
|
|
<p>
|
|
<code>n</code> is a counter for how many times this function
|
|
has been called for this particular traversal of the stack.
|
|
It always begins at zero for the first error on the stack
|
|
(either the top or bottom error, or even both, depending on
|
|
the traversal direction and the size of the stack).
|
|
<p>
|
|
<code>err_desc</code> is an error description. It contains all the
|
|
information about a particular error.
|
|
<p>
|
|
<code>client_data</code> is the same pointer that was passed as the
|
|
<code>client_data</code> argument of <code>H5Ewalk()</code>.
|
|
It is expected to be a file pointer (or stderr if null).
|
|
<dt><strong>Parameters:</strong>
|
|
<dl>
|
|
<dt><em>int</em> <code>n</code>
|
|
<dd>Number of times this function has been called
|
|
for this traversal of the stack.
|
|
<dt><em>H5E_error_t *</em><code>err_desc</code>
|
|
<dd>Error description.
|
|
<dt><em>void</em> <code>*client_data</code>
|
|
<dd>A file pointer, or stderr if null.
|
|
</dl>
|
|
<dt><strong>Returns:</strong>
|
|
<dd>Returns SUCCEED (0) if successful;
|
|
otherwise FAIL (-1).
|
|
</dl>
|
|
|
|
|
|
<hr>
|
|
<dl>
|
|
<dt><strong>Name:</strong> <a name="Error-GetMajor">H5Eget_major</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>const char *</em> <code>H5Eget_major</code>(<em>H5E_major_t</em> <code>n</code>)
|
|
<dt><strong>Purpose:</strong>
|
|
<dd>Returns a character string describing an error specified by a
|
|
major error number.
|
|
<dt><strong>Description:</strong>
|
|
<dd>Given a major error number, <code>H5Eget_major</code> returns a
|
|
constant character string that describes the error.
|
|
<dt><strong>Parameters:</strong>
|
|
<dl>
|
|
<dt><em>H5E_major_t</em> <code>n</code>
|
|
<dd>Major error number.
|
|
</dl>
|
|
<dt><strong>Returns:</strong>
|
|
<dd> Returns a character string describing the error if successful.
|
|
Otherwise returns "Invalid major error number."
|
|
</dl>
|
|
|
|
|
|
<hr>
|
|
<dl>
|
|
<dt><strong>Name:</strong> <a name="Error-GetMinor">H5Eget_minor</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>const char *</em> <code>H5Eget_minor</code>(<em>H5E_minor_t</em> <code>n</code>)
|
|
<dt><strong>Purpose:</strong>
|
|
<dd>Returns a character string describing an error specified by a
|
|
minor error number.
|
|
<dt><strong>Description:</strong>
|
|
<dd>Given a minor error number, <code>H5Eget_minor</code> returns a
|
|
constant character string that describes the error.
|
|
<dt><strong>Parameters:</strong>
|
|
<dl>
|
|
<dt><em>H5E_minor_t</em> <code>n</code>
|
|
<dd>Minor error number.
|
|
</dl>
|
|
<dt><strong>Returns:</strong>
|
|
<dd> Returns a character string describing the error if successful.
|
|
Otherwise returns "Invalid minor error number."
|
|
</dl>
|
|
|
|
|
|
<hr>
|
|
<center>
|
|
<a href="RM_H5Front.html">HDF5 Reference Manual</a>
|
|
<a href="RM_H5.html">H5</a>
|
|
<a href="RM_H5A.html">H5A</a>
|
|
<a href="RM_H5D.html">H5D</a>
|
|
H5E
|
|
<a href="RM_H5F.html">H5F</a>
|
|
<a href="RM_H5G.html">H5G</a>
|
|
<a href="RM_H5P.html">H5P</a>
|
|
<a href="RM_H5S.html">H5S</a>
|
|
<a href="RM_H5T.html">H5T</a>
|
|
<a href="RM_H5Z.html">H5Z</a>
|
|
<a href="Tools.html">Tools</a>
|
|
<!--
|
|
<a href="Glossary.html">Glossary</a>
|
|
-->
|
|
</center>
|
|
<hr>
|
|
|
|
<address>
|
|
<a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a>
|
|
|
|
<br>
|
|
Last modified: 14 July 1998
|
|
|
|
</body>
|
|
</html>
|