summaryrefslogtreecommitdiffstats
path: root/doxygen/examples
diff options
context:
space:
mode:
authorDana Robinson <43805+derobins@users.noreply.github.com>2021-12-08 17:40:30 (GMT)
committerGitHub <noreply@github.com>2021-12-08 17:40:30 (GMT)
commit0247538fc5226b0899f00c45adab2a454627de02 (patch)
tree2e56201d9a70296920e96e9ba2edb09353ce2d5f /doxygen/examples
parent1ca806a04eb28c1b1307fcc804a45e4722ff8563 (diff)
downloadhdf5-0247538fc5226b0899f00c45adab2a454627de02.zip
hdf5-0247538fc5226b0899f00c45adab2a454627de02.tar.gz
hdf5-0247538fc5226b0899f00c45adab2a454627de02.tar.bz2
VFD SWMR: Normalization with develop (#1270)
Brings many October-November changes from develop
Diffstat (limited to 'doxygen/examples')
-rw-r--r--doxygen/examples/DebuggingHDF5Applications.html392
-rw-r--r--doxygen/examples/FileFormat.html1275
-rw-r--r--doxygen/examples/Filters.html450
-rw-r--r--doxygen/examples/IOFlow.html137
4 files changed, 2254 insertions, 0 deletions
diff --git a/doxygen/examples/DebuggingHDF5Applications.html b/doxygen/examples/DebuggingHDF5Applications.html
new file mode 100644
index 0000000..c6aaf74
--- /dev/null
+++ b/doxygen/examples/DebuggingHDF5Applications.html
@@ -0,0 +1,392 @@
+<html>
+ <head>
+ <title>Debugging HDF5 Applications</title>
+
+ <h2>Introduction</h2>
+
+ <p>The HDF5 library contains a number of debugging features to
+ make programmers' lives easier including the ability to print
+ detailed error messages, check invariant conditions, display
+ timings and other statistics, and trace API function calls and
+ return values.
+
+ </p><dl>
+ <dt><b>Error Messages</b>
+ </dt><dd>Error messages are normally displayed automatically on the
+ standard error stream and include a stack trace of the library
+ including file names, line numbers, and function names. The
+ application has complete control over how error messages are
+ displayed and can disable the display on a permanent or
+ temporary basis. Refer to the documentation for the H5E error
+ handling package.
+
+ <br><br>
+ </dd><dt><b>Invariant Conditions</b>
+ </dt><dd>Unless <code>NDEBUG</code> is defined during compiling, the
+ library will include code to verify that invariant conditions
+ have the expected values. When a problem is detected the
+ library will display the file and line number within the
+ library and the invariant condition that failed. A core dump
+ may be generated for post mortem debugging. The code to
+ perform these checks can be included on a per-package bases.
+
+ <br><br>
+ </dd><dt><b>Timings and Statistics</b>
+ </dt><dd>The library can be configured to accumulate certain
+ statistics about things like cache performance, datatype
+ conversion, data space conversion, and data filters. The code
+ is included on a per-package basis and enabled at runtime by
+ an environment variable.
+
+ <br><br>
+ </dd><dt><b>API Tracing</b>
+ </dt><dd>All API calls made by an application can be displayed and
+ include formal argument names and actual values and the
+ function return value. This code is also conditionally
+ included at compile time and enabled at runtime.
+ </dd></dl>
+
+ <p>The statistics and tracing can be displayed on any output
+ stream (including streams opened by the shell) with output from
+ different packages even going to different streams.
+
+ </p><h2>Error Messages</h2>
+
+ <p>By default any API function that fails will print an error
+ stack to the standard error stream.
+
+ </p><p>
+ </p><center>
+ <table border="" align="center" width="100%">
+ <tbody><tr>
+ <td>
+ <p><code></code></p><pre><code>
+HDF5-DIAG: Error detected in thread 0. Back trace follows.
+ #000: H5F.c line 1245 in H5Fopen(): unable to open file
+ major(04): File interface
+ minor(10): Unable to open file
+ #001: H5F.c line 846 in H5F_open(): file does not exist
+ major(04): File interface
+ minor(10): Unable to open file
+ </code></pre>
+ </td>
+ </tr>
+ </tbody></table>
+ </center>
+
+ <p>The error handling package (H5E) is described
+ <a href="./group___h5_e.html">elsewhere</a>.
+
+ </p><h2>Invariant Conditions</h2>
+
+ <p>To include checks for invariant conditions the library should
+ be configured with <code>--disable-production</code>, the
+ default for versions before 1.2. The library designers have made
+ every attempt to handle error conditions gracefully but an
+ invariant condition assertion may fail in certain cases. The
+ output from a failure usually looks something like this:
+
+ </p><p>
+ </p><center>
+ <table border="" align="center" width="100%">
+ <tbody><tr>
+ <td>
+ <p><code></code></p><pre><code>
+Assertion failed: H5.c:123: i&lt;NELMTS(H5_debug_g)
+IOT Trap, core dumped.
+ </code></pre>
+ </td>
+ </tr>
+ </tbody></table>
+ </center>
+
+ <h2>Timings and Statistics</h2>
+
+ <p>Code to accumulate statistics is included at compile time by
+ using the <code>--enable-debug</code> configure switch. The
+ switch can be followed by an equal sign and a comma-separated
+ list of package names or else a default list is used.
+
+ </p><p>
+ </p><center>
+ <table border="" align="center" width="80%">
+ <tbody><tr>
+ <th>Name</th>
+ <th>Default</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td align="center">a</td>
+ <td align="center">No</td>
+ <td>Attributes</td>
+ </tr>
+ <tr>
+ <td align="center">ac</td>
+ <td align="center">Yes</td>
+ <td>Meta data cache</td>
+ </tr>
+ <tr>
+ <td align="center">b</td>
+ <td align="center">Yes</td>
+ <td>B-Trees</td>
+ </tr>
+ <tr>
+ <td align="center">d</td>
+ <td align="center">Yes</td>
+ <td>Datasets</td>
+ </tr>
+ <tr>
+ <td align="center">e</td>
+ <td align="center">Yes</td>
+ <td>Error handling</td>
+ </tr>
+ <tr>
+ <td align="center">f</td>
+ <td align="center">Yes</td>
+ <td>Files</td>
+ </tr>
+ <tr>
+ <td align="center">g</td>
+ <td align="center">Yes</td>
+ <td>Groups</td>
+ </tr>
+ <tr>
+ <td align="center">hg</td>
+ <td align="center">Yes</td>
+ <td>Global heap</td>
+ </tr>
+ <tr>
+ <td align="center">hl</td>
+ <td align="center">No</td>
+ <td>Local heaps</td>
+ </tr>
+ <tr>
+ <td align="center">i</td>
+ <td align="center">Yes</td>
+ <td>Interface abstraction</td>
+ </tr>
+ <tr>
+ <td align="center">mf</td>
+ <td align="center">No</td>
+ <td>File memory management</td>
+ </tr>
+ <tr>
+ <td align="center">mm</td>
+ <td align="center">Yes</td>
+ <td>Library memory managment</td>
+ </tr>
+ <tr>
+ <td align="center">o</td>
+ <td align="center">No</td>
+ <td>Object headers and messages</td>
+ </tr>
+ <tr>
+ <td align="center">p</td>
+ <td align="center">Yes</td>
+ <td>Property lists</td>
+ </tr>
+ <tr>
+ <td align="center">s</td>
+ <td align="center">Yes</td>
+ <td>Data spaces</td>
+ </tr>
+ <tr>
+ <td align="center">t</td>
+ <td align="center">Yes</td>
+ <td>Datatypes</td>
+ </tr>
+ <tr>
+ <td align="center">v</td>
+ <td align="center">Yes</td>
+ <td>Vectors</td>
+ </tr>
+ <tr>
+ <td align="center">z</td>
+ <td align="center">Yes</td>
+ <td>Raw data filters</td>
+ </tr>
+ </tbody></table>
+ </center>
+
+ <p>In addition to including the code at compile time the
+ application must enable each package at runtime. This is done
+ by listing the package names in the <code>HDF5_DEBUG</code>
+ environment variable. That variable may also contain file
+ descriptor numbers (the default is `2') which control the output
+ for all following packages up to the next file number. The
+ word <code>all</code> refers to all packages. Any word my be
+ preceded by a minus sign to turn debugging off for the package.
+
+ </p><p>
+ </p><center>
+ <table border="" align="center" width="100%">
+ <caption align="top"><b>Sample debug specifications</b></caption>
+ <tbody><tr valign="top">
+ <td><code>all</code></td>
+ <td>This causes debugging output from all packages to be
+ sent to the standard error stream.</td>
+ </tr>
+ <tr valign="top">
+ <td><code>all -t -s</code></td>
+ <td>Debugging output for all packages except datatypes
+ and data spaces will appear on the standard error
+ stream.</td>
+ </tr>
+ <tr valign="top">
+ <td><code>-all ac 255 t,s</code></td>
+ <td>This disables all debugging even if the default was to
+ debug something, then output from the meta data cache is
+ send to the standard error stream and output from data
+ types and spaces is sent to file descriptor 255 which
+ should be redirected by the shell.</td>
+ </tr>
+ </tbody></table>
+ </center>
+
+ <p>The components of the <code>HDF5_DEBUG</code> value may be
+ separated by any non-lowercase letter.
+
+ </p><h2>API Tracing</h2>
+
+ <p>The HDF5 library can trace API calls by printing the
+ function name, the argument names and their values, and the
+ return value. Some people like to see lots of output during
+ program execution instead of using a good symbolic debugger, and
+ this feature is intended for their consumption. For example,
+ the output from <code>h5ls foo</code> after turning on tracing,
+ includes:
+
+ </p><p>
+ </p><center>
+ <table border="" align="center" width="100%">
+ <tbody><tr>
+ <td>
+ <code><pre>
+H5Tcopy(type=184549388) = 184549419 (type);
+H5Tcopy(type=184549392) = 184549424 (type);
+H5Tlock(type=184549424) = SUCCEED;
+H5Tcopy(type=184549393) = 184549425 (type);
+H5Tlock(type=184549425) = SUCCEED;
+H5Fopen(filename="foo", flags=0, access=H5P_DEFAULT) = FAIL;
+HDF5-DIAG: Error detected in thread 0. Back trace follows.
+ #000: H5F.c line 1245 in H5Fopen(): unable to open file
+ major(04): File interface
+ minor(10): Unable to open file
+ #001: H5F.c line 846 in H5F_open(): file does not exist
+ major(04): File interface
+ minor(10): Unable to open file
+ </pre></code>
+ </td>
+ </tr>
+ </tbody></table>
+ </center>
+
+ <p>The code that performs the tracing must be included in the
+ library by specifying the <code>--enable-trace</code>
+ configuration switch (the default for versions before 1.2). Then
+ the word <code>trace</code> must appear in the value of the
+ <code>HDF5_DEBUG</code> variable. The output will appear on the
+ last file descriptor before the word <code>trace</code> or two
+ (standard error) by default.
+
+ </p><p>
+ </p><center>
+ <table border="" align="center" width="100%">
+ <tbody><tr>
+ <td>To display the trace on the standard error stream:
+ <code><pre>$ env HDF5_DEBUG=trace a.out
+ </pre></code>
+ </td>
+ </tr>
+ <tr>
+ <td>To send the trace to a file:
+ <code><pre>$ env HDF5_DEBUG="55 trace" a.out 55&gt;trace-output
+ </pre></code>
+ </td>
+ </tr>
+ </tbody></table>
+ </center>
+
+ <h3>Performance</h3>
+
+ <p>If the library was not configured for tracing then there is no
+ unnecessary overhead since all tracing code is excluded.
+ However, if tracing is enabled but not used there is a small
+ penalty. First, code size is larger because of extra
+ statically-declared character strings used to store argument
+ types and names and extra auto variable pointer in each
+ function. Also, execution is slower because each function sets
+ and tests a local variable and each API function calls the
+ <code>H5_trace()</code> function.
+
+ </p><p>If tracing is enabled and turned on then the penalties from the
+ previous paragraph apply plus the time required to format each
+ line of tracing information. There is also an extra call to
+ H5_trace() for each API function to print the return value.
+
+ </p><h3>Safety</h3>
+
+ <p>The tracing mechanism is invoked for each API function before
+ arguments are checked for validity. If bad arguments are passed
+ to an API function it could result in a segmentation fault.
+ However, the tracing output is line-buffered so all previous
+ output will appear.
+
+ </p><h3>Completeness</h3>
+
+ <p>There are two API functions that don't participate in
+ tracing. They are <code>H5Eprint()</code> and
+ <code>H5Eprint_cb()</code> because their participation would
+ mess up output during automatic error reporting.
+
+ </p><p>On the other hand, a number of API functions are called during
+ library initialization and they print tracing information.
+
+ </p><h3>Implementation</h3>
+
+ <p>For those interested in the implementation here is a
+ description. Each API function should have a call to one of the
+ <code>H5TRACE()</code> macros immediately after the
+ <code>FUNC_ENTER()</code> macro. The first argument is the
+ return type encoded as a string. The second argument is the
+ types of all the function arguments encoded as a string. The
+ remaining arguments are the function arguments. This macro was
+ designed to be as terse and unobtrousive as possible.
+
+ </p><p>In order to keep the <code>H5TRACE()</code> calls synchronized
+ with the source code we've written a perl script which gets
+ called automatically just before Makefile dependencies are
+ calculated for the file. However, this only works when one is
+ using GNU make. To reinstrument the tracing explicitly, invoke
+ the <code>trace</code> program from the hdf5 bin directory with
+ the names of the source files that need to be updated. If any
+ file needs to be modified then a backup is created by appending
+ a tilde to the file name.
+
+ </p><p>
+ </p><center>
+ <table border="" align="center" width="100%">
+ <caption align="top"><b>Explicit Instrumentation</b></caption>
+ <tbody><tr>
+ <td>
+ <code><pre>
+$ ../bin/trace *.c
+H5E.c: in function `H5Ewalk_cb':
+H5E.c:336: warning: trace info was not inserted
+ </pre></code>
+ </td>
+ </tr>
+ </tbody></table>
+ </center>
+
+ <p>Note: The warning message is the result of a comment of the
+ form <code>/*NO TRACE*/</code> somewhere in the function
+ body. Tracing information will not be updated or inserted if
+ such a comment exists.
+
+ </p><p>Error messages have the same format as a compiler so that they
+ can be parsed from program development environments like
+ Emacs. Any function which generates an error will not be
+ modified.</p>
+
+</body></html>
diff --git a/doxygen/examples/FileFormat.html b/doxygen/examples/FileFormat.html
new file mode 100644
index 0000000..fc35357
--- /dev/null
+++ b/doxygen/examples/FileFormat.html
@@ -0,0 +1,1275 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<!-- saved from url=(0072)https://gamma.hdfgroup.org/papers/HISS/030515.FileFormat/FileFormat.html -->
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+ <title>HDF5 File Format Discussion</title>
+
+ <meta name="author" content="Quincey Koziol">
+</head>
+
+<body text="#000000" bgcolor="#FFFFFF">
+
+<style type="text/css">
+OL.loweralpha { list-style-type: lower-alpha }
+OL.upperroman { list-style-type: upper-roman }
+</style>
+
+<style type="text/css">
+TD CAPTION EM { color: red }
+TD EM { color: blue }
+TABLE CAPTION STRONG { font-size: larger }
+</style>
+
+<center><h1>HDF5 File Format Discussion</h1></center>
+<center><h3>Quincey Koziol<br>
+ koziol@ncsa.uiuc.edu<br>
+ May 15, 2003
+</h3></center>
+
+<ol class="upperroman">
+
+<li><h3><u>Document's Audience:</u></h3>
+
+<ul>
+ <li>Current H5 library designers and knowledgable external developers.</li>
+</ul>
+
+</li><li><h3><u>Background Reading:</u></h3>
+
+<dl>
+ <dt><a href="https://docs.hdfgroup.org/hdf5/develop/_s_p_e_c.html">HDF5 File Format Specification</a>
+ </dt><dd>This describes the current HDF5 file format.
+</dd></dl>
+
+</li><li><h3><u>Introduction:</u></h3>
+
+<dl>
+ <dt><strong>What is this document about?</strong></dt>
+ <dd>This document attempts to explain the HDF5 file format
+ specification with a few examples and describes some potential
+ improvements to the format specification.
+ </dd> <br>
+</dl>
+
+</li><li><h3><u>File Format Examples:</u></h3>
+
+<p>This section has several small programs and describes the format of a file
+created with each of them.
+</p>
+
+<p>Example program one - <em>Create an empty file</em>:
+</p><pre> <code>
+#include "hdf5.h"
+#include <assert.h>
+
+int main()
+{
+ hid_t fid; /* File ID */
+ herr_t ret; /* Generic return value */
+
+ /* Create the file */
+ fid=H5Fcreate("example1.h5", H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT);
+ assert(fid&gt;=0);
+
+ /* Close the file */
+ ret=H5Fclose(fid);
+ assert(ret&gt;=0);
+
+ return(0);
+}
+</assert.h></code> </pre>
+
+ <center>
+ <table border="" align="center" cellpadding="4" width="80%">
+ <caption align="top">
+ <strong>Super Block</strong>
+ </caption>
+
+ <tbody><tr align="center">
+ <th width="25%">byte</th>
+ <th width="25%">byte</th>
+ <th width="25%">byte</th>
+ <th width="25%">byte</th>
+ </tr>
+
+ <tr align="center">
+ <td>\211</td>
+ <td>'H'</td>
+ <td>'D'</td>
+ <td>'F'</td>
+ </tr>
+
+ <tr align="center">
+ <td>\r</td>
+ <td>\n</td>
+ <td>\032</td>
+ <td>\n</td>
+ </tr>
+
+ <tr align="center">
+ <td>0</td>
+ <td>0</td>
+ <td>0</td>
+ <td>0</td>
+ </tr>
+
+ <tr align="center">
+ <td>0</td>
+ <td>8</td>
+ <td>8</td>
+ <td>0</td>
+ </tr>
+
+ <tr align="center">
+ <td colspan="2">4</td>
+ <td colspan="2">16</td>
+ </tr>
+
+ <tr align="center">
+ <td colspan="4">0x00000003</td>
+ </tr>
+
+ <tr align="center">
+ <td colspan="4">0</td>
+ </tr>
+
+ <tr align="center">
+ <td colspan="4"><br>0xffffffffffffffff<br><br></td>
+ </tr>
+
+ <tr align="center">
+ <td colspan="4">?</td>
+ </tr>
+
+ <tr align="center">
+ <td colspan="4"><br>0xffffffffffffffff<br><br></td>
+ </tr>
+
+ <tr align="center">
+ <td colspan="4">
+ <table border="" width="100%">
+ <tbody><tr align="center">
+ <td colspan="4">0</td>
+ </tr>
+
+ <tr align="center">
+ <td colspan="4"><br>928<br><br></td>
+ </tr>
+
+ <tr align="center">
+ <td colspan="4">H5G_CACHED_STAB (1)</td>
+ </tr>
+
+ <tr align="center">
+ <td colspan="4">0</td>
+ </tr>
+
+ <tr align="center">
+ <td colspan="4">
+ <table border="" width="100%">
+ <tbody><tr align="center">
+ <td colspan="4"><br>384<br><br></td>
+ </tr>
+ <tr align="center">
+ <td colspan="4"><br>96<br><br></td>
+ </tr>
+ </tbody></table>
+ </td>
+ </tr>
+ </tbody></table>
+ </td>
+ </tr>
+ </tbody></table>
+ </center>
+<br>
+<pre> <code>
+%h5debug example1.h5
+
+Reading signature at address 0 (rel)
+File Super Block...
+File name: example1.h5
+File access flags 0x00000000
+File open reference count: 1
+Address of super block: 0 (abs)
+Size of user block: 0 bytes
+Super block version number: 0
+Free list version number: 0
+Root group symbol table entry version number: 0
+Shared header version number: 0
+Size of file offsets (haddr_t type): 8 bytes
+Size of file lengths (hsize_t type): 8 bytes
+Symbol table leaf node 1/2 rank: 4
+Symbol table internal node 1/2 rank: 16
+File consistency flags: 0x00000003
+Base address: 0 (abs)
+Free list address: UNDEF (rel)
+Address of driver information block: UNDEF (rel)
+Root group symbol table entry:
+ Name offset into private heap: 0
+ Object header address: 928
+ Dirty: Yes
+ Cache info type: Symbol Table
+ Cached information:
+ B-tree address: 384
+ Heap address: 96
+</code> </pre>
+
+
+ <center>
+ <table border="" cellpadding="4" width="80%">
+ <caption align="top">
+ <strong>Root Group Object Header</strong>
+ </caption>
+
+ <tbody><tr align="center">
+ <th width="25%">byte</th>
+ <th width="25%">byte</th>
+ <th width="25%">byte</th>
+ <th width="25%">byte</th>
+ </tr>
+
+ <tr align="center">
+ <td colspan="1" width="25%">1</td>
+ <td colspan="1" width="25%">0</td>
+ <td colspan="2" width="50%">2</td>
+ </tr>
+ <tr align="center">
+ <td colspan="4">1</td>
+ </tr>
+ <tr align="center">
+ <td colspan="4">32</td>
+ </tr>
+ <tr align="center">
+ <td colspan="2">0x0011</td>
+ <td colspan="2">16</td>
+ </tr>
+ <tr align="center">
+ <td>0x01</td>
+ <td colspan="3">0</td>
+ </tr>
+ <tr align="center">
+ <td colspan="4">
+ <table border="" width="100%">
+ <tbody><tr align="center">
+ <td colspan="4"><br>384<br><br></td>
+ </tr>
+ <tr align="center">
+ <td colspan="4"><br>96<br><br></td>
+ </tr>
+ </tbody></table>
+ </td>
+ </tr>
+ <tr align="center">
+ <td colspan="2">0</td>
+ <td colspan="2">0</td>
+ </tr>
+ <tr align="center">
+ <td>0x00</td>
+ <td colspan="3">0</td>
+ </tr>
+ </tbody></table>
+ </center>
+<br>
+<pre> <code>
+%h5debug example1.h5 928
+
+New address: 928
+Reading signature at address 928 (rel)
+Object Header...
+Dirty: 0
+Version: 1
+Header size (in bytes): 16
+Number of links: 1
+Number of messages (allocated): 2 (32)
+Number of chunks (allocated): 1 (8)
+Chunk 0...
+ Dirty: 0
+ Address: 944
+ Size in bytes: 32
+Message 0...
+ Message ID (sequence number): 0x0011 stab(0)
+ Shared message: No
+ Constant: Yes
+ Raw size in obj header: 16 bytes
+ Chunk number: 0
+ Message Information:
+ B-tree address: 384
+ Name heap address: 96
+Message 1...
+ Message ID (sequence number): 0x0000 null(0)
+ Shared message: No
+ Constant: No
+ Raw size in obj header: 0 bytes
+ Chunk number: 0
+ Message Information:
+ <no info="" for="" this="" message="">
+</no></code> </pre>
+
+ <center>
+ <table border="" cellpadding="4" width="80%">
+ <caption align="top">
+ <strong>Root Group Local Heap</strong>
+ </caption>
+
+ <tbody><tr align="center">
+ <th width="25%">byte</th>
+ <th width="25%">byte</th>
+ <th width="25%">byte</th>
+ <th width="25%">byte</th>
+ </tr>
+
+ <tr align="center">
+ <td>'H'</td>
+ <td>'E'</td>
+ <td>'A'</td>
+ <td>'P'</td>
+ </tr>
+
+ <tr align="center">
+ <td colspan="4">0</td>
+ </tr>
+
+ <tr align="center">
+ <td colspan="4">256</td>
+ </tr>
+
+ <tr align="center">
+ <td colspan="4">8</td>
+ </tr>
+
+ <tr align="center">
+ <td colspan="4">128</td>
+ </tr>
+ </tbody></table>
+ </center>
+<br>
+
+<pre> <code>
+%h5debug example1.h5 96
+
+New address: 96
+Reading signature at address 96 (rel)
+Local Heap...
+Dirty: 0
+Header size (in bytes): 32
+Address of heap data: 128
+Data bytes allocated on disk: 256
+Data bytes allocated in core: 256
+Free Blocks (offset, size):
+ Block #0: 8, 248
+Percent of heap used: 3.12%
+Data follows (`__' indicates free region)...
+ 0: 00 00 00 00 00 00 00 00 __ __ __ __ __ __ __ __ ........
+ 16: __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __
+ 32: __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __
+ 48: __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __
+ 64: __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __
+ 80: __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __
+ 96: __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __
+ 112: __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __
+ 128: __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __
+ 144: __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __
+ 160: __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __
+ 176: __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __
+ 192: __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __
+ 208: __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __
+ 224: __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __
+ 240: __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __
+
+</code> </pre>
+
+ <center>
+ <table border="" cellpadding="4" width="80%">
+ <caption align="top">
+ <strong>Root Group B-tree</strong>
+ </caption>
+
+ <tbody><tr align="center">
+ <th width="25%">byte</th>
+ <th width="25%">byte</th>
+ <th width="25%">byte</th>
+ <th width="25%">byte</th>
+
+ </tr><tr align="center">
+ <td>'T'</td>
+ <td>'R'</td>
+ <td>'E'</td>
+ <td>'E'</td>
+
+ </tr><tr align="center">
+ <td>0</td>
+ <td>0</td>
+ <td colspan="2">0</td>
+
+ </tr><tr align="center">
+ <td colspan="4"><br>0xffffffffffffffff<br><br></td>
+
+ </tr><tr align="center">
+ <td colspan="4"><br>0xffffffffffffffff<br><br></td>
+
+ </tr></tbody></table>
+ </center>
+<br>
+<pre> <code>
+%h5debug example1.h5 384 96
+
+New address: 384
+Reading signature at address 384 (rel)
+Tree type ID: H5B_SNODE_ID
+Size of node: 544
+Size of raw (disk) key: 8
+Dirty flag: False
+Number of initial dirty children: 0
+Level: 0
+Address of left sibling: UNDEF
+Address of right sibling: UNDEF
+Number of children (max): 0 (32)
+
+</code> </pre>
+
+<p></p>
+
+<p>Example program two - <em>Create a file with a single dataset in it</em>:
+</p><pre> <code>
+#include "hdf5.h"
+#include <assert.h>
+
+int main()
+{
+ hid_t fid; /* File ID */
+ hid_t sid; /* Dataspace ID */
+ hid_t did; /* Dataset ID */
+ herr_t ret; /* Generic return value */
+
+ /* Create the file */
+ fid=H5Fcreate("example2.h5", H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT);
+ assert(fid&gt;=0);
+
+ /* Create a scalar dataspace for the dataset */
+ sid=H5Screate(H5S_SCALAR);
+ assert(sid&gt;=0);
+
+ /* Create a trivial dataset */
+ did=H5Dcreate(fid, "Dataset", H5T_NATIVE_INT, sid, H5P_DEFAULT);
+ assert(did&gt;=0);
+
+ /* Close the dataset */
+ ret=H5Dclose(did);
+ assert(ret&gt;=0);
+
+ /* Close the dataspace */
+ ret=H5Sclose(sid);
+ assert(ret&gt;=0);
+
+ /* Close the file */
+ ret=H5Fclose(fid);
+ assert(ret&gt;=0);
+
+ return(0);
+}
+</assert.h></code> </pre>
+
+ <center>
+ <table border="" align="center" cellpadding="4" width="80%">
+ <caption align="top">
+ <strong>Super Block</strong>
+ </caption>
+
+ <tbody><tr align="center">
+ <th width="25%">byte</th>
+ <th width="25%">byte</th>
+ <th width="25%">byte</th>
+ <th width="25%">byte</th>
+ </tr>
+
+ <tr align="center">
+ <td>\211</td>
+ <td>'H'</td>
+ <td>'D'</td>
+ <td>'F'</td>
+ </tr>
+
+ <tr align="center">
+ <td>\r</td>
+ <td>\n</td>
+ <td>\032</td>
+ <td>\n</td>
+ </tr>
+
+ <tr align="center">
+ <td>0</td>
+ <td>0</td>
+ <td>0</td>
+ <td>0</td>
+ </tr>
+
+ <tr align="center">
+ <td>0</td>
+ <td>8</td>
+ <td>8</td>
+ <td>0</td>
+ </tr>
+
+ <tr align="center">
+ <td colspan="2">4</td>
+ <td colspan="2">16</td>
+ </tr>
+
+ <tr align="center">
+ <td colspan="4">0x00000003</td>
+ </tr>
+
+ <tr align="center">
+ <td colspan="4">0</td>
+ </tr>
+
+ <tr align="center">
+ <td colspan="4"><br>0xffffffffffffffff<br><br></td>
+ </tr>
+
+ <tr align="center">
+ <td colspan="4">?</td>
+ </tr>
+
+ <tr align="center">
+ <td colspan="4"><br>0xffffffffffffffff<br><br></td>
+ </tr>
+
+ <tr align="center">
+ <td colspan="4">
+ <table border="" width="100%">
+ <tbody><tr align="center">
+ <td colspan="4">0</td>
+ </tr>
+
+ <tr align="center">
+ <td colspan="4"><br>928<br><br></td>
+ </tr>
+
+ <tr align="center">
+ <td colspan="4">H5G_CACHED_STAB (1)</td>
+ </tr>
+
+ <tr align="center">
+ <td colspan="4">0</td>
+ </tr>
+
+ <tr align="center">
+ <td colspan="4">
+ <table border="" width="100%">
+ <tbody><tr align="center">
+ <td colspan="4"><br>384<br><br></td>
+ </tr>
+ <tr align="center">
+ <td colspan="4"><br>96<br><br></td>
+ </tr>
+ </tbody></table>
+ </td>
+ </tr>
+ </tbody></table>
+ </td>
+ </tr>
+ </tbody></table>
+ </center>
+<br>
+<pre> <code>
+%h5debug example2.h5
+
+Reading signature at address 0 (rel)
+File Super Block...
+File name: example2.h5
+File access flags 0x00000000
+File open reference count: 1
+Address of super block: 0 (abs)
+Size of user block: 0 bytes
+Super block version number: 0
+Free list version number: 0
+Root group symbol table entry version number: 0
+Shared header version number: 0
+Size of file offsets (haddr_t type): 8 bytes
+Size of file lengths (hsize_t type): 8 bytes
+Symbol table leaf node 1/2 rank: 4
+Symbol table internal node 1/2 rank: 16
+File consistency flags: 0x00000003
+Base address: 0 (abs)
+Free list address: UNDEF (rel)
+Address of driver information block: UNDEF (rel)
+Root group symbol table entry:
+ Name offset into private heap: 0
+ Object header address: 928
+ Dirty: Yes
+ Cache info type: Symbol Table
+ Cached entry information:
+ B-tree address: 384
+ Heap address: 96
+</code> </pre>
+
+ <center>
+ <table border="" cellpadding="4" width="80%">
+ <caption align="top">
+ <strong>Root Group Object Header</strong>
+ </caption>
+
+ <tbody><tr align="center">
+ <th width="25%">byte</th>
+ <th width="25%">byte</th>
+ <th width="25%">byte</th>
+ <th width="25%">byte</th>
+ </tr>
+
+ <tr align="center">
+ <td colspan="1" width="25%">1</td>
+ <td colspan="1" width="25%">0</td>
+ <td colspan="2" width="50%">2</td>
+ </tr>
+ <tr align="center">
+ <td colspan="4">1</td>
+ </tr>
+ <tr align="center">
+ <td colspan="4">32</td>
+ </tr>
+ <tr align="center">
+ <td colspan="2">0x0011</td>
+ <td colspan="2">16</td>
+ </tr>
+ <tr align="center">
+ <td>0x01</td>
+ <td colspan="3">0</td>
+ </tr>
+ <tr align="center">
+ <td colspan="4">
+ <table border="" width="100%">
+ <tbody><tr align="center">
+ <td colspan="4"><br>384<br><br></td>
+ </tr>
+ <tr align="center">
+ <td colspan="4"><br>96<br><br></td>
+ </tr>
+ </tbody></table>
+ </td>
+ </tr>
+ <tr align="center">
+ <td colspan="2">0</td>
+ <td colspan="2">0</td>
+ </tr>
+ <tr align="center">
+ <td>0x00</td>
+ <td colspan="3">0</td>
+ </tr>
+ </tbody></table>
+ </center>
+<br>
+<pre> <code>
+%h5debug example2.h5 928
+
+New address: 928
+Reading signature at address 928 (rel)
+Object Header...
+Dirty: 0
+Version: 1
+Header size (in bytes): 16
+Number of links: 1
+Number of messages (allocated): 2 (32)
+Number of chunks (allocated): 1 (8)
+Chunk 0...
+ Dirty: 0
+ Address: 944
+ Size in bytes: 32
+Message 0...
+ Message ID: 0x0011 stab(0)
+ Shared message: No
+ Constant: Yes
+ Raw size in obj header: 16 bytes
+ Chunk number: 0
+ Message Information:
+ B-tree address: 384
+ Name heap address: 96
+Message 1...
+ Message ID: 0x0000 null(0)
+ Shared message: No
+ Constant: No
+ Raw size in obj header: 0 bytes
+ Chunk number: 0
+ Message Information:
+ <no info="" for="" this="" message="">
+</no></code> </pre>
+
+ <center>
+ <table border="" cellpadding="4" width="80%">
+ <caption align="top">
+ <strong>Root Group Local Heap</strong>
+ </caption>
+
+ <tbody><tr align="center">
+ <th width="25%">byte</th>
+ <th width="25%">byte</th>
+ <th width="25%">byte</th>
+ <th width="25%">byte</th>
+ </tr>
+
+ <tr align="center">
+ <td>'H'</td>
+ <td>'E'</td>
+ <td>'A'</td>
+ <td>'P'</td>
+ </tr>
+
+ <tr align="center">
+ <td colspan="4">0</td>
+ </tr>
+
+ <tr align="center">
+ <td colspan="4">256</td>
+ </tr>
+
+ <tr align="center">
+ <td colspan="4">16</td>
+ </tr>
+
+ <tr align="center">
+ <td colspan="4">128</td>
+ </tr>
+ </tbody></table>
+ </center>
+<br>
+
+<pre> <code>
+%h5debug example2.h5 96
+
+New address: 96
+Reading signature at address 96 (rel)
+Local Heap...
+Dirty: 0
+Header size (in bytes): 32
+Address of heap data: 128
+Data bytes allocated on disk: 256
+Data bytes allocated in core: 256
+Free Blocks (offset, size):
+ Block #0: 16, 240
+Percent of heap used: 6.25%
+Data follows (`__' indicates free region)...
+ 0: 00 00 00 00 00 00 00 00 44 61 74 61 73 65 74 00 ........Dataset.
+ 16: __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __
+ 32: __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __
+ 48: __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __
+ 64: __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __
+ 80: __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __
+ 96: __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __
+ 112: __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __
+ 128: __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __
+ 144: __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __
+ 160: __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __
+ 176: __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __
+ 192: __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __
+ 208: __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __
+ 224: __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __
+ 240: __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __
+</code> </pre>
+
+ <center>
+ <table border="" cellpadding="4" width="80%">
+ <caption align="top">
+ <strong>Root Group B-tree</strong>
+ </caption>
+
+ <tbody><tr align="center">
+ <th width="25%">byte</th>
+ <th width="25%">byte</th>
+ <th width="25%">byte</th>
+ <th width="25%">byte</th>
+
+ </tr><tr align="center">
+ <td>'T'</td>
+ <td>'R'</td>
+ <td>'E'</td>
+ <td>'E'</td>
+
+ </tr><tr align="center">
+ <td>0</td>
+ <td>0</td>
+ <td colspan="2">1</td>
+
+ </tr><tr align="center">
+ <td colspan="4"><br>0xffffffffffffffff<br><br></td>
+
+ </tr><tr align="center">
+ <td colspan="4"><br>0xffffffffffffffff<br><br></td>
+
+ </tr><tr align="center">
+ <td colspan="4"><br>0<br><br></td>
+
+ </tr><tr align="center">
+ <td colspan="4"><br>1248<br><br></td>
+
+ </tr><tr align="center">
+ <td colspan="4"><br>8<br><br></td>
+
+ </tr></tbody></table>
+ </center>
+<br>
+<pre> <code>
+%h5debug example2.h5 384 96
+
+New address: 384
+Reading signature at address 384 (rel)
+Tree type ID: H5B_SNODE_ID
+Size of node: 544
+Size of raw (disk) key: 8
+Dirty flag: False
+Number of initial dirty children: 0
+Level: 0
+Address of left sibling: UNDEF
+Address of right sibling: UNDEF
+Number of children (max): 1 (32)
+Child 0...
+ Address: 1248
+ Left Key:
+ Heap offset: 0
+ Name :
+ Right Key:
+ Heap offset: 8
+ Name : Dataset
+</code> </pre>
+
+ <center>
+ <table border="" cellpadding="4" width="80%">
+ <caption align="top">
+ <strong>Root Group B-tree Symbol Table Node</strong>
+ </caption>
+
+ <tbody><tr align="center">
+ <th width="25%">byte</th>
+ <th width="25%">byte</th>
+ <th width="25%">byte</th>
+ <th width="25%">byte</th>
+
+ </tr><tr align="center">
+ <td>'S'</td>
+ <td>'N'</td>
+ <td>'O'</td>
+ <td>'D'</td>
+
+ </tr><tr align="center">
+ <td>1</td>
+ <td>0</td>
+ <td colspan="2">1</td>
+
+ </tr><tr align="center">
+ <td colspan="4">
+ <table border="" width="100%">
+ <tbody><tr align="center">
+ <td colspan="4">8</td>
+ </tr>
+
+ <tr align="center">
+ <td colspan="4"><br>976<br><br></td>
+ </tr>
+
+ <tr align="center">
+ <td colspan="4">0</td>
+ </tr>
+
+ <tr align="center">
+ <td colspan="4">0</td>
+ </tr>
+
+ <tr align="center">
+ <td colspan="4"><br><br>0<br><br><br></td>
+ </tr>
+ </tbody></table>
+ </td>
+
+ </tr></tbody></table>
+ </center>
+<br>
+<pre> <code>
+%h5debug example2.h5 1248 96
+
+New address: 1248
+Reading signature at address 1248 (rel)
+Symbol Table Node...
+Dirty: No
+Size of Node (in bytes): 328
+Number of Symbols: 1 of 8
+Symbol 0:
+ Name: `Dataset'
+ Name offset into private heap: 8
+ Object header address: 976
+ Dirty: No
+ Cache info type: Nothing Cached
+</code> </pre>
+
+ <center>
+ <table border="" cellpadding="4" width="90%">
+ <caption align="top">
+ <strong>'/Dataset' Object Header</strong>
+ </caption>
+
+ <tbody><tr align="center">
+ <th width="25%">byte</th>
+ <th width="25%">byte</th>
+ <th width="25%">byte</th>
+ <th width="25%">byte</th>
+ </tr>
+
+ <tr align="center">
+ <td colspan="1"><em>Version:</em> 1</td>
+ <td colspan="1"><em>Reserved:</em> 0</td>
+ <td colspan="2"><em>Number of Header Messages:</em> 6</td>
+ </tr>
+ <tr align="center">
+ <td colspan="4"><em>Object Reference Count:</em> 1</td>
+ </tr>
+ <tr align="center">
+ <td colspan="4"><em>Total Object Header Size:</em> 256</td>
+ </tr>
+<!-- Fill Value Header Message -->
+ <tr align="center">
+ <td colspan="4">
+ <table border="" width="100%">
+ <caption align="top" color="#80FFFF">
+ <em>Fill Value Header Message</em>
+ </caption>
+ <tbody><tr align="center">
+ <th width="25%"></th>
+ <th width="25%"></th>
+ <th width="25%"></th>
+ <th width="25%"></th>
+ </tr>
+
+ <tr align="center">
+ <!-- Object Header Message Type -->
+ <td colspan="2"><em>Message Type:</em> 0x0005</td>
+ <!-- Object Header Message Length -->
+ <td colspan="2"><em>Message Data Size:</em> 8</td>
+ </tr>
+ <tr align="center">
+ <!-- Object Header Message Flags -->
+ <td colspan="1"><em>Flags:</em> 0x01</td>
+ <!-- Reserved -->
+ <td colspan="3"><em>Reserved:</em> 0</td>
+ </tr>
+ <tr align="center">
+ <!-- Version -->
+ <td colspan="1"><em>Version:</em> 1</td>
+ <!-- Space Allocation Time -->
+ <td colspan="1"><em>Space Allocation Time:</em> 2 (Late)</td>
+ <!-- Fill Value Writing Time -->
+ <td colspan="1"><em>Fill Value Writing Time:</em> 0 (At allocation)</td>
+ <!-- Fill Value Defined -->
+ <td colspan="1"><em>Fill Value Defined:</em> 0 (Undefined)</td>
+ </tr>
+ <tr align="center">
+ <!-- Fill Value Datatype Size -->
+ <td colspan="4"><em>Fill Value Datatype Size:</em> 0 (Use dataset's datatype for fill-value datatype)</td>
+ </tr>
+ </tbody></table>
+ </td>
+ </tr>
+<!-- Datatype Header Message -->
+ <tr align="center">
+ <td colspan="4">
+ <table border="" width="100%">
+ <caption align="top">
+ <em>Datatype Header Message</em>
+ </caption>
+ <tbody><tr align="center">
+ <th width="25%"></th>
+ <th width="25%"></th>
+ <th width="25%"></th>
+ <th width="25%"></th>
+ </tr>
+
+ <tr align="center">
+ <!-- Object Header Message Type -->
+ <td colspan="2"><em>Message Type:</em> 0x0003</td>
+ <!-- Object Header Message Length -->
+ <td colspan="2"><em>Message Data Size:</em> 16</td>
+ </tr>
+ <tr align="center">
+ <!-- Object Header Message Flags -->
+ <td colspan="1"><em>Flags:</em> 0x01</td>
+ <!-- Reserved -->
+ <td colspan="3"><em>Reserved:</em> 0</td>
+ </tr>
+ <tr align="center">
+ <!-- Type Class and Version -->
+ <td colspan="1">
+ <table border="" width="100%">
+ <tbody><tr align="center">
+ <td width="50%"><em>Version:</em> 0x1</td>
+ <td><em>Class:</em> 0x0 (Fixed-Point)</td>
+ </tr>
+ </tbody></table>
+ </td>
+ <!-- Class Bit Field -->
+ <td colspan="3"><em>Fixed-Point Bit-Field:</em> 0x08 (Little-endian, No padding, Signed)</td>
+ </tr>
+ <tr align="center">
+ <!-- Type Size (in bytes) -->
+ <td colspan="4"><em>Size:</em> 4</td>
+ </tr>
+ <tr align="center">
+ <!-- Bit Offset -->
+ <td colspan="2"><em>Bit Offset:</em> 0</td>
+ <!-- Bit Precision -->
+ <td colspan="2"><em>Bit Precision:</em> 32</td>
+ </tr>
+ <tr align="center">
+ <!-- Message alignment filler -->
+ <td colspan="4"><em>Message Alignment Filler:</em> -</td>
+ </tr>
+ </tbody></table>
+ </td>
+ </tr>
+<!-- Dataspace Header Message -->
+ <tr align="center">
+ <td colspan="4">
+ <table border="" width="100%">
+ <caption align="top">
+ <em>Dataspace Header Message</em>
+ </caption>
+ <tbody><tr align="center">
+ <th width="25%"></th>
+ <th width="25%"></th>
+ <th width="25%"></th>
+ <th width="25%"></th>
+ </tr>
+
+ <tr align="center">
+ <!-- Object Header Message Type -->
+ <td colspan="2"><em>Message Type:</em> 0x0001</td>
+ <!-- Object Header Message Length -->
+ <td colspan="2"><em>Message Data Size:</em> 8</td>
+ </tr>
+ <tr align="center">
+ <!-- Object Header Message Flags -->
+ <td colspan="1"><em>Flags:</em> 0x00</td>
+ <!-- Reserved -->
+ <td colspan="3"><em>Reserved:</em> 0</td>
+ </tr>
+ <tr align="center">
+ <!-- Version -->
+ <td colspan="1"><em>Version:</em> 1</td>
+ <!-- Rank -->
+ <td colspan="1"><em>Rank:</em> 0 (Scalar)</td>
+ <!-- Flags -->
+ <td colspan="1"><em>Flags:</em> 0x00 (No maximum dimensions, no permutation information)</td>
+ <!-- Reserved -->
+ <td colspan="1"><em>Reserved:</em> 0</td>
+ </tr>
+ <tr align="center">
+ <!-- Reserved -->
+ <td colspan="4"><em>Reserved:</em> 0</td>
+ </tr>
+ </tbody></table>
+ </td>
+ </tr>
+<!-- Layout Header Message -->
+ <tr align="center">
+ <td colspan="4">
+ <table border="" width="100%">
+ <caption align="top">
+ <em>Layout Header Message</em>
+ </caption>
+ <tbody><tr align="center">
+ <th width="25%"></th>
+ <th width="25%"></th>
+ <th width="25%"></th>
+ <th width="25%"></th>
+ </tr>
+
+ <tr align="center">
+ <!-- Object Header Message Type -->
+ <td colspan="2"><em>Message Type:</em> 0x0008</td>
+ <!-- Object Header Message Length -->
+ <td colspan="2"><em>Message Data Size:</em> 24</td>
+ </tr>
+ <tr align="center">
+ <!-- Object Header Message Flags -->
+ <td colspan="1"><em>Flags:</em> 0x00</td>
+ <!-- Reserved -->
+ <td colspan="3"><em>Reserved:</em> 0</td>
+ </tr>
+ <tr align="center">
+ <!-- Version -->
+ <td colspan="1"><em>Version:</em> 1</td>
+ <!-- Rank -->
+ <td colspan="1"><em>Rank:</em> 1 (Dataspace rank+1)</td>
+ <!-- Class -->
+ <td colspan="1"><em>Class:</em> 1 (Contiguous)</td>
+ <!-- Reserved -->
+ <td colspan="1"><em>Reserved:</em> 0</td>
+ </tr>
+ <tr align="center">
+ <!-- Reserved -->
+ <td colspan="4"><em>Reserved:</em> 0</td>
+ </tr>
+ <tr align="center">
+ <!-- Address -->
+ <td colspan="4"><br><em>Address:</em> 0xffffffffffffffff (Undefined)<br><br></td>
+ </tr>
+ <tr align="center">
+ <!-- Layout Dimensions -->
+ <td colspan="4"><em>Dimension 0 Size:</em> 4 (Datatype size)</td>
+ </tr>
+ <tr align="center">
+ <!-- Message alignment filler -->
+ <td colspan="4"><em>Message Alignment Filler:</em> -</td>
+ </tr>
+ </tbody></table>
+ </td>
+ </tr>
+<!-- Modification Date & Time Header Message -->
+ <tr align="center">
+ <td colspan="4">
+ <table border="" width="100%">
+ <caption align="top">
+ <em>Modification Date &amp; Time Header Message</em>
+ </caption>
+ <tbody><tr align="center">
+ <th width="25%"></th>
+ <th width="25%"></th>
+ <th width="25%"></th>
+ <th width="25%"></th>
+ </tr>
+
+ <tr align="center">
+ <!-- Object Header Message Type -->
+ <td colspan="2"><em>Message Type:</em> 0x0012</td>
+ <!-- Object Header Message Length -->
+ <td colspan="2"><em>Message Data Size:</em> 8</td>
+ </tr>
+ <tr align="center">
+ <!-- Object Header Message Flags -->
+ <td colspan="1"><em>Flags:</em> 0x00</td>
+ <!-- Reserved -->
+ <td colspan="3"><em>Reserved:</em> 0</td>
+ </tr>
+ <tr align="center">
+ <!-- Version -->
+ <td colspan="1"><em>Version:</em> 1</td>
+ <!-- Reserved -->
+ <td colspan="3"><em>Reserved:</em> 0</td>
+ </tr>
+ <tr align="center">
+ <!-- Modification time -->
+ <td colspan="4"><em>Seconds Since Epoch:</em> 1052401700 (2003-05-08 08:48:20 CDT)</td>
+ </tr>
+ </tbody></table>
+ </td>
+ </tr>
+<!-- Null Header Message -->
+ <tr align="center">
+ <td colspan="4">
+ <table border="" width="100%">
+ <caption align="top">
+ <em>Null Header Message</em>
+ </caption>
+ <tbody><tr align="center">
+ <th width="25%"></th>
+ <th width="25%"></th>
+ <th width="25%"></th>
+ <th width="25%"></th>
+ </tr>
+
+ <tr align="center">
+ <td colspan="2"><em>Message Type:</em> 0x0000</td>
+ <td colspan="2"><em>Message Data Size:</em> 144</td>
+ </tr>
+ <tr align="center">
+ <td colspan="1"><em>Flags:</em> 0x00</td>
+ <td colspan="3"><em>Reserved:</em> 0</td>
+ </tr>
+ </tbody></table>
+ </td>
+ </tr>
+ </tbody></table>
+ </center>
+<br>
+<pre> <code>
+%h5debug example2.h5 976
+
+New address: 976
+Reading signature at address 976 (rel)
+Object Header...
+Dirty: 0
+Version: 1
+Header size (in bytes): 16
+Number of links: 1
+Number of messages (allocated): 6 (32)
+Number of chunks (allocated): 1 (8)
+Chunk 0...
+ Dirty: 0
+ Address: 992
+ Size in bytes: 256
+Message 0...
+ Message ID (sequence number): 0x0005 `fill_new' (0)
+ Shared: No
+ Constant: Yes
+ Raw size in obj header: 8 bytes
+ Chunk number: 0
+ Message Information:
+ Version: 1
+ Space Allocation Time: Late
+ Fill Time: On Allocation
+ Fill Value Defined: Undefined
+ Size: 0
+ Data type: <dataset type="">
+Message 1...
+ Message ID (sequence number): 0x0003 data_type(0)
+ Shared message: No
+ Constant: Yes
+ Raw size in obj header: 16 bytes
+ Chunk number: 0
+ Message Information:
+ Type class: integer
+ Size: 4 bytes
+ Byte order: little endian
+ Precision: 32 bits
+ Offset: 0 bits
+ Low pad type: zero
+ High pad type: zero
+ Sign scheme: 2's comp
+Message 2...
+ Message ID (sequence number): 0x0001 simple_dspace(0)
+ Shared message: No
+ Constant: No
+ Raw size in obj header: 8 bytes
+ Chunk number: 0
+ Message Information:
+ Rank: 0
+Message 3...
+ Message ID (sequence number): 0x0008 layout(0)
+ Shared message: No
+ Constant: No
+ Raw size in obj header: 24 bytes
+ Chunk number: 0
+ Message Information:
+ Data address: UNDEF
+ Number of dimensions: 1
+ Size: {4}
+Message 4...
+ Message ID (sequence number): 0x0012 mtime_new(0)
+ Shared message: No
+ Constant: No
+ Raw size in obj header: 8 bytes
+ Chunk number: 0
+ Message Information:
+ Time: 2003-03-05 14:52:00 CST
+Message 5...
+ Message ID (sequence number): 0x0000 null(0)
+ Shared message: No
+ Constant: No
+ Raw size in obj header: 144 bytes
+ Chunk number: 0
+ Message Information:
+ <no info="" for="" this="" message="">
+</no></dataset></code> </pre>
+
+<p></p>
+
+</li></ol>
+
+
+
+</body></html>
diff --git a/doxygen/examples/Filters.html b/doxygen/examples/Filters.html
new file mode 100644
index 0000000..2d5bc5e
--- /dev/null
+++ b/doxygen/examples/Filters.html
@@ -0,0 +1,450 @@
+<html>
+ <head>
+ <title>Filters</title>
+ <h1>Filters in HDF5</h1>
+
+ <b>Note: Transient pipelines described in this document have not
+ been implemented.</b>
+
+ <h2>Introduction</h2>
+
+ <p>HDF5 allows chunked data to pass through user-defined filters
+ on the way to or from disk. The filters operate on chunks of an
+ <code>H5D_CHUNKED</code> dataset can be arranged in a pipeline
+ so output of one filter becomes the input of the next filter.
+
+ </p><p>Each filter has a two-byte identification number (type
+ <code>H5Z_filter_t</code>) allocated by The HDF Group and can also be
+ passed application-defined integer resources to control its
+ behavior. Each filter also has an optional ASCII comment
+ string.
+
+ </p>
+ <table>
+ <tbody><tr>
+ <th>Values for <code>H5Z_filter_t</code></th>
+ <th>Description</th>
+ </tr>
+
+ <tr valign="top">
+ <td><code>0-255</code></td>
+ <td>These values are reserved for filters predefined and
+ registered by the HDF5 library and of use to the general
+ public. They are described in a separate section
+ below.</td>
+ </tr>
+
+ <tr valign="top">
+ <td><code>256-511</code></td>
+ <td>Filter numbers in this range are used for testing only
+ and can be used temporarily by any organization. No
+ attempt is made to resolve numbering conflicts since all
+ definitions are by nature temporary.</td>
+ </tr>
+
+ <tr valign="top">
+ <td><code>512-65535</code></td>
+ <td>Reserved for future assignment. Please contact the
+ <a href="mailto:help@hdfgroup.org">HDF5 development team</a>
+ to reserve a value or range of values for
+ use by your filters.</td>
+ </tr></tbody></table>
+
+ <h2>Defining and Querying the Filter Pipeline</h2>
+
+ <p>Two types of filters can be applied to raw data I/O: permanent
+ filters and transient filters. The permanent filter pipeline is
+ defned when the dataset is created while the transient pipeline
+ is defined for each I/O operation. During an
+ <code>H5Dwrite()</code> the transient filters are applied first
+ in the order defined and then the permanent filters are applied
+ in the order defined. For an <code>H5Dread()</code> the
+ opposite order is used: permanent filters in reverse order, then
+ transient filters in reverse order. An <code>H5Dread()</code>
+ must result in the same amount of data for a chunk as the
+ original <code>H5Dwrite()</code>.
+
+ </p><p>The permanent filter pipeline is defined by calling
+ <code>H5Pset_filter()</code> for a dataset creation property
+ list while the transient filter pipeline is defined by calling
+ that function for a dataset transfer property list.
+
+ </p><dl>
+ <dt><code>herr_t H5Pset_filter (hid_t <em>plist</em>,
+ H5Z_filter_t <em>filter</em>, unsigned int <em>flags</em>,
+ size_t <em>cd_nelmts</em>, const unsigned int
+ <em>cd_values</em>[])</code>
+ </dt><dd>This function adds the specified <em>filter</em> and
+ corresponding properties to the end of the transient or
+ permanent output filter pipeline (depending on whether
+ <em>plist</em> is a dataset creation or dataset transfer
+ property list). The <em>flags</em> argument specifies certain
+ general properties of the filter and is documented below. The
+ <em>cd_values</em> is an array of <em>cd_nelmts</em> integers
+ which are auxiliary data for the filter. The integer values
+ will be stored in the dataset object header as part of the
+ filter information.
+ </dd><dt><code>int H5Pget_nfilters (hid_t <em>plist</em>)</code>
+ </dt><dd>This function returns the number of filters defined in the
+ permanent or transient filter pipeline depending on whether
+ <em>plist</em> is a dataset creation or dataset transfer
+ property list. In each pipeline the filters are numbered from
+ 0 through <em>N</em>-1 where <em>N</em> is the value returned
+ by this function. During output to the file the filters of a
+ pipeline are applied in increasing order (the inverse is true
+ for input). Zero is returned if there are no filters in the
+ pipeline and a negative value is returned for errors.
+ </dd><dt><code>H5Z_filter_t H5Pget_filter (hid_t <em>plist</em>,
+ int <em>filter_number</em>, unsigned int *<em>flags</em>,
+ size_t *<em>cd_nelmts</em>, unsigned int
+ *<em>cd_values</em>, size_t namelen, char name[])</code>
+ </dt><dd>This is the query counterpart of
+ <code>H5Pset_filter()</code> and returns information about a
+ particular filter number in a permanent or transient pipeline
+ depending on whether <em>plist</em> is a dataset creation or
+ dataset transfer property list. On input, <em>cd_nelmts</em>
+ indicates the number of entries in the <em>cd_values</em>
+ array allocated by the caller while on exit it contains the
+ number of values defined by the filter. The
+ <em>filter_number</em> should be a value between zero and
+ <em>N</em>-1 as described for <code>H5Pget_nfilters()</code>
+ and the function will return failure (a negative value) if the
+ filter number is out of range. If <em>name</em> is a pointer
+ to an array of at least <em>namelen</em> bytes then the filter
+ name will be copied into that array. The name will be null
+ terminated if the <em>namelen</em> is large enough. The
+ filter name returned will be the name appearing in the file or
+ else the name registered for the filter or else an empty string.
+ </dd></dl>
+
+ <p>The flags argument to the functions above is a bit vector of
+ the following fields:
+
+ </p>
+ <table>
+ <tbody><tr>
+ <th>Values for <em>flags</em></th>
+ <th>Description</th>
+ </tr>
+
+ <tr valign="top">
+ <td><code>H5Z_FLAG_OPTIONAL</code></td>
+ <td>If this bit is set then the filter is optional. If
+ the filter fails (see below) during an
+ <code>H5Dwrite()</code> operation then the filter is
+ just excluded from the pipeline for the chunk for which
+ it failed; the filter will not participate in the
+ pipeline during an <code>H5Dread()</code> of the chunk.
+ This is commonly used for compression filters: if the
+ compression result would be larger than the input then
+ the compression filter returns failure and the
+ uncompressed data is stored in the file. If this bit is
+ clear and a filter fails then the
+ <code>H5Dwrite()</code> or <code>H5Dread()</code> also
+ fails.</td>
+ </tr>
+ </tbody></table>
+
+ <h2>Defining Filters</h2>
+
+ <p>Each filter is bidirectional, handling both input and output to
+ the file, and a flag is passed to the filter to indicate the
+ direction. In either case the filter reads a chunk of data from
+ a buffer, usually performs some sort of transformation on the
+ data, places the result in the same or new buffer, and returns
+ the buffer pointer and size to the caller. If something goes
+ wrong the filter should return zero to indicate a failure.
+
+ </p><p>During output, a filter that fails or isn't defined and is
+ marked as optional is silently excluded from the pipeline and
+ will not be used when reading that chunk of data. A required
+ filter that fails or isn't defined causes the entire output
+ operation to fail. During input, any filter that has not been
+ excluded from the pipeline during output and fails or is not
+ defined will cause the entire input operation to fail.
+
+ </p><p>Filters are defined in two phases. The first phase is to
+ define a function to act as the filter and link the function
+ into the application. The second phase is to register the
+ function, associating the function with an
+ <code>H5Z_filter_t</code> identification number and a comment.
+
+ </p><dl>
+ <dt><code>typedef size_t (*H5Z_func_t)(unsigned int
+ <em>flags</em>, size_t <em>cd_nelmts</em>, const unsigned int
+ <em>cd_values</em>[], size_t <em>nbytes</em>, size_t
+ *<em>buf_size</em>, void **<em>buf</em>)</code>
+ </dt><dd>The <em>flags</em>, <em>cd_nelmts</em>, and
+ <em>cd_values</em> are the same as for the
+ <code>H5Pset_filter()</code> function with the additional flag
+ <code>H5Z_FLAG_REVERSE</code> which is set when the filter is
+ called as part of the input pipeline. The input buffer is
+ pointed to by <em>*buf</em> and has a total size of
+ <em>*buf_size</em> bytes but only <em>nbytes</em> are valid
+ data. The filter should perform the transformation in place if
+ possible and return the number of valid bytes or zero for
+ failure. If the transformation cannot be done in place then
+ the filter should allocate a new buffer with
+ <code>malloc()</code> and assign it to <em>*buf</em>,
+ assigning the allocated size of that buffer to
+ <em>*buf_size</em>. The old buffer should be freed
+ by calling <code>free()</code>.
+
+ <br><br>
+ </dd><dt><code>herr_t H5Zregister (H5Z_filter_t <em>filter_id</em>,
+ const char *<em>comment</em>, H5Z_func_t
+ <em>filter</em>)</code>
+ </dt><dd>The <em>filter</em> function is associated with a filter
+ number and a short ASCII comment which will be stored in the
+ hdf5 file if the filter is used as part of a permanent
+ pipeline during dataset creation.
+ </dd></dl>
+
+ <h2>Predefined Filters</h2>
+
+ <p>If <code>zlib</code> version 1.1.2 or later was found
+ during configuration then the library will define a filter whose
+ <code>H5Z_filter_t</code> number is
+ <code>H5Z_FILTER_DEFLATE</code>. Since this compression method
+ has the potential for generating compressed data which is larger
+ than the original, the <code>H5Z_FLAG_OPTIONAL</code> flag
+ should be turned on so such cases can be handled gracefully by
+ storing the original data instead of the compressed data. The
+ <em>cd_nvalues</em> should be one with <em>cd_value[0]</em>
+ being a compression agression level between zero and nine,
+ inclusive (zero is the fastest compression while nine results in
+ the best compression ratio).
+
+ </p><p>A convenience function for adding the
+ <code>H5Z_FILTER_DEFLATE</code> filter to a pipeline is:
+
+ </p><dl>
+ <dt><code>herr_t H5Pset_deflate (hid_t <em>plist</em>, unsigned
+ <em>aggression</em>)</code>
+ </dt><dd>The deflate compression method is added to the end of the
+ permanent or transient filter pipeline depending on whether
+ <em>plist</em> is a dataset creation or dataset transfer
+ property list. The <em>aggression</em> is a number between
+ zero and nine (inclusive) to indicate the tradeoff between
+ speed and compression ratio (zero is fastest, nine is best
+ ratio).
+ </dd></dl>
+
+ <p>Even if the <code>zlib</code> isn't detected during
+ configuration the application can define
+ <code>H5Z_FILTER_DEFLATE</code> as a permanent filter. If the
+ filter is marked as optional (as with
+ <code>H5Pset_deflate()</code>) then it will always fail and be
+ automatically removed from the pipeline. Applications that read
+ data will fail only if the data is actually compressed; they
+ won't fail if <code>H5Z_FILTER_DEFLATE</code> was part of the
+ permanent output pipeline but was automatically excluded because
+ it didn't exist when the data was written.
+
+ </p><p><code>zlib</code> can be acquired from
+ <code><a href="http://www.cdrom.com/pub/infozip/zlib/">
+ http://www.cdrom.com/pub/infozip/zlib/</a></code>.
+
+ </p><h2>Example</h2>
+
+ <p>This example shows how to define and register a simple filter
+ that adds a checksum capability to the data stream.
+
+ </p><p>The function that acts as the filter always returns zero
+ (failure) if the <code>md5()</code> function was not detected at
+ configuration time (left as an excercise for the reader).
+ Otherwise the function is broken down to an input and output
+ half. The output half calculates a checksum, increases the size
+ of the output buffer if necessary, and appends the checksum to
+ the end of the buffer. The input half calculates the checksum
+ on the first part of the buffer and compares it to the checksum
+ already stored at the end of the buffer. If the two differ then
+ zero (failure) is returned, otherwise the buffer size is reduced
+ to exclude the checksum.
+
+ </p>
+ <table>
+ <tbody><tr>
+ <td>
+ <p><code></code></p><pre><code>
+ size_t
+ md5_filter(unsigned int flags, size_t cd_nelmts,
+ const unsigned int cd_values[], size_t nbytes,
+ size_t *buf_size, void **buf)
+ {
+ #ifdef HAVE_MD5
+ unsigned char cksum[16];
+
+ if (flags &amp; H5Z_REVERSE) {
+ /* Input */
+ assert(nbytes&gt;=16);
+ md5(nbytes-16, *buf, cksum);
+
+ /* Compare */
+ if (memcmp(cksum, (char*)(*buf)+nbytes-16, 16)) {
+ return 0; /*fail*/
+ }
+
+ /* Strip off checksum */
+ return nbytes-16;
+
+ } else {
+ /* Output */
+ md5(nbytes, *buf, cksum);
+
+ /* Increase buffer size if necessary */
+ if (nbytes+16&gt;*buf_size) {
+ *buf_size = nbytes + 16;
+ *buf = realloc(*buf, *buf_size);
+ }
+
+ /* Append checksum */
+ memcpy((char*)(*buf)+nbytes, cksum, 16);
+ return nbytes+16;
+ }
+ #else
+ return 0; /*fail*/
+ #endif
+ }
+ </code></pre>
+ </td>
+ </tr>
+ </tbody></table>
+
+ <p>Once the filter function is defined it must be registered so
+ the HDF5 library knows about it. Since we're testing this
+ filter we choose one of the <code>H5Z_filter_t</code> numbers
+ from the reserved range. We'll randomly choose 305.
+
+ </p><p>
+ </p>
+ <table>
+ <tbody><tr>
+ <td>
+ <p><code></code></p><pre><code>
+ #define FILTER_MD5 305
+ herr_t status = H5Zregister(FILTER_MD5, "md5 checksum", md5_filter);
+ </code></pre>
+ </td>
+ </tr>
+ </tbody></table>
+
+ <p>Now we can use the filter in a pipeline. We could have added
+ the filter to the pipeline before defining or registering the
+ filter as long as the filter was defined and registered by time
+ we tried to use it (if the filter is marked as optional then we
+ could have used it without defining it and the library would
+ have automatically removed it from the pipeline for each chunk
+ written before the filter was defined and registered).
+
+ </p><p>
+ </p>
+ <table>
+ <tbody><tr>
+ <td>
+ <p><code></code></p><pre><code>
+ hid_t dcpl = H5Pcreate(H5P_DATASET_CREATE);
+ hsize_t chunk_size[3] = {10,10,10};
+ H5Pset_chunk(dcpl, 3, chunk_size);
+ H5Pset_filter(dcpl, FILTER_MD5, 0, 0, NULL);
+ hid_t dset = H5Dcreate(file, "dset", H5T_NATIVE_DOUBLE, space, dcpl);
+ </code></pre>
+ </td>
+ </tr>
+ </tbody></table>
+
+ <h2>6. Filter Diagnostics</h2>
+
+ <p>If the library is compiled with debugging turned on for the H5Z
+ layer (usually as a result of <code>configure
+ --enable-debug=z</code>) then filter statistics are printed when
+ the application exits normally or the library is closed. The
+ statistics are written to the standard error stream and include
+ two lines for each filter that was used: one for input and one
+ for output. The following fields are displayed:
+
+ </p><p>
+ </p>
+ <table>
+ <tbody><tr>
+ <th>Field Name</th>
+ <th>Description</th>
+ </tr>
+
+ <tr valign="top">
+ <td>Method</td>
+ <td>This is the name of the method as defined with
+ <code>H5Zregister()</code> with the charaters
+ "&lt; or "&gt;" prepended to indicate
+ input or output.</td>
+ </tr>
+
+ <tr valign="top">
+ <td>Total</td>
+ <td>The total number of bytes processed by the filter
+ including errors. This is the maximum of the
+ <em>nbytes</em> argument or the return value.
+ </td></tr>
+
+ <tr valign="top">
+ <td>Errors</td>
+ <td>This field shows the number of bytes of the Total
+ column which can be attributed to errors.</td>
+ </tr>
+
+ <tr valign="top">
+ <td>User, System, Elapsed</td>
+ <td>These are the amount of user time, system time, and
+ elapsed time in seconds spent in the filter function.
+ Elapsed time is sensitive to system load. These times
+ may be zero on operating systems that don't support the
+ required operations.</td>
+ </tr>
+
+ <tr valign="top">
+ <td>Bandwidth</td>
+ <td>This is the filter bandwidth which is the total
+ number of bytes processed divided by elapsed time.
+ Since elapsed time is subject to system load the
+ bandwidth numbers cannot always be trusted.
+ Furthermore, the bandwidth includes bytes attributed to
+ errors which may significanly taint the value if the
+ function is able to detect errors without much
+ expense.</td>
+ </tr>
+ </tbody></table>
+
+ <p>
+ </p>
+ <table>
+ <caption align="bottom">
+ <b>Example: Filter Statistics</b>
+ </caption>
+ <tbody><tr>
+ <td>
+ <p><code></code></p><pre><code>H5Z: filter statistics accumulated ov=
+ er life of library:
+ Method Total Errors User System Elapsed Bandwidth
+ ------ ----- ------ ---- ------ ------- ---------
+ &gt;deflate 160000 40000 0.62 0.74 1.33 117.5 kBs
+ &lt;deflate 120000 0 0.11 0.00 0.12 1.000 MBs
+ </code></pre>
+ </td>
+ </tr>
+ </tbody></table>
+
+ <hr>
+
+
+ <p><a name="fn1">Footnote 1:</a> Dataset chunks can be compressed
+ through the use of filters. Developers should be aware that
+ reading and rewriting compressed chunked data can result in holes
+ in an HDF5 file. In time, enough such holes can increase the
+ file size enough to impair application or library performance
+ when working with that file. See
+ <a href="https://support.hdfgroup.org/HDF5/doc1.6/Performance.html#Freespace">
+ Freespace Management</a>
+ in the chapter
+ <a href="https://support.hdfgroup.org/HDF5/doc1.6/Performance.html">
+ Performance Analysis and Issues</a>.</p>
+</html>
diff --git a/doxygen/examples/IOFlow.html b/doxygen/examples/IOFlow.html
new file mode 100644
index 0000000..6b2c27e
--- /dev/null
+++ b/doxygen/examples/IOFlow.html
@@ -0,0 +1,137 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<!-- saved from url=(0064)https://gamma.hdfgroup.org/papers/HISS/030821.IOFlow/IOFlow.html -->
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+ <title>HDF5 Raw I/O Flow Notes</title>
+
+ <meta name="author" content="Quincey Koziol">
+</head>
+
+<body text="#000000" bgcolor="#FFFFFF">
+
+<style type="text/css">
+OL.loweralpha { list-style-type: lower-alpha }
+OL.upperroman { list-style-type: upper-roman }
+</style>
+
+<center><h1>HDF5 Raw I/O Flow Notes</h1></center>
+<center><h3>Quincey Koziol<br>
+ koziol@ncsa.uiuc.edu<br>
+ August 20, 2003
+</h3></center>
+
+<ol class="upperroman">
+
+<li><h3><u>Document's Audience:</u></h3>
+
+<ul>
+ <li>Current H5 library designers and knowledgable external developers.</li>
+</ul>
+
+</li><li><h3><u>Background Reading:</u></h3>
+
+</li><li><h3><u>Introduction:</u></h3>
+
+<dl>
+ <dt><strong>What is this document about?</strong></dt>
+ <dd>This document attempts to supplement the flow charts describing
+ the flow of control for raw data I/O in the library.
+ </dd> <br>
+</dl>
+
+</li><li><h3><u>Figures:</u></h3>
+<p>The following figures provide the main information:</p>
+ <table>
+ <tr><td><img src="IOFlow.gif" alt="High-Level View of Writing Raw Data" style="height:50%;"></td></tr>
+ <tr><td><img src="IOFlow2.gif" alt="Perform Serial or Parallel I/O" style="height:50%;"></td></tr>
+ <tr><td><img src="IOFlow3.gif" alt="Gather/Convert/Scatter" style="height:50%;"></td></tr>
+ </table>
+
+</li><li><h3><u>Notes From Accompanying Figures:</u></h3>
+
+<p>This section provides notes to augment the information in the accompanying
+ figures.
+</p>
+
+<ol>
+ <li><b>Validate Parameters</b> - Resolve any H5S_ALL parameters
+ for dataspace selections to actual dataspaces, allocate
+ conversion buffers, etc.
+ </li>
+
+ <li><b>Space Allocated in File?</b> - Space may not have been allocated
+ in the file to store the dataset data, if "late allocation" was chosen
+ for the allocation time when the dataset was created.
+ </li>
+
+ <li><b>Allocate &amp; Fill Space</b> - These operations allocate both contiguous
+ and chunked dataset's space in the file. The chunked dataset space
+ allocation iterates through all the chunks in the file and allocates
+ both the B-tree information and the raw data in the file. Because of
+ the way filters work, fill-values are written out for chunked datasets
+ as they are allocated, instead of as a separate step.
+ In parallel
+ I/O, the chunked dataset allocation can potentially be time-consuming,
+ since all the raw data in the dataset is allocated from one process.
+ </li>
+
+ <li><b>Datatype Conversion Needed?</b> - This currently is the deciding
+ factor between doing "direct I/O" (in serial or parallel) and needing
+ to perform gather/convert/scatter operations. I believe that MPI
+ is capable of performing a limited range of type conversions and if so,
+ we should add support to detect when they can be used. This will
+ allow more I/O operations to be performed collectively.
+ </li>
+
+ <li><b>Collective I/O Requested/Allowed?</b> - A user has to both request
+ that collective I/O occur and also their I/O operation must meet the
+ requirements that the library sets for supporting collective parallel
+ I/O:
+ <ul>
+ <li>The dataspace must be scalar or simple (which is a no-op really,
+ since we don't support "complex" dataspaces in the library
+ currently).
+ </li>
+ <li>The selection must be regular. "all" selections
+ and hyperslab selections that were
+ made with only one call to H5Sselect_hyperslab() (i.e. not a
+ hyperslab selection that has been aggregated over multiple
+ selection calls) are regular. Supporting point and
+ irregular hyperslab selections are on the "to do" list.
+ </li>
+ <li>The dataset must be stored contiguously on disk (as shown in the
+ figure also). Supporting chunked dataset storage is also
+ on the "to do" list.
+ </li>
+ </ul>
+ </li>
+
+ <li><b>Build "chunk map"</b> - This step still has some scalability issues
+ as it creates a data structure that is proportional to the number of
+ chunks which will be written to, which could potentially be very large.
+ Building the "chunk map" information incrementally is on the "to do"
+ list also.
+ </li>
+
+ <li><b>Perform Chunked I/O</b> - As the figure shows, there is no support
+ for collective parallel I/O on chunked datasets currently. As noted
+ earlier, this is on the "to do" list.
+ </li>
+
+ <li><b>Perform "Direct" Serial I/O</b> - "Direct" serial I/O writes data
+ from the application's buffer, without any intervening buffer or memory
+ copies. For maximum efficiency and performance, the elements in the
+ selections should be adjoining.
+ </li>
+
+ <li><b>Perform Collective Parallel I/O</b> - This step also writes data
+ directly from an application buffer, but additionally uses collective
+ MPI I/O operations to combine the data from each process in the parallel
+ application in an efficient manner.
+ </li>
+</ol>
+
+</li></ol>
+
+
+
+</body></html>
generated by cgit v0.12 at 2024-07-25 02:01:36 (GMT)