mirror of
https://github.com/HDFGroup/hdf5.git
synced 2024-12-09 07:32:32 +08:00
369 lines
14 KiB
HTML
369 lines
14 KiB
HTML
<html>
|
|
<head><title>
|
|
HDF5/H5RA Experimental API Specification
|
|
</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="H5.user.html">HDF5 User Guide</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="RM_H5Front.html">HDF5 Reference Manual</a>
|
|
<br>
|
|
<a href="RM_H5.html">H5</a>
|
|
<a href="RM_H5A.html">H5A</a>
|
|
<a href="RM_H5D.html">H5D</a>
|
|
<a href="RM_H5E.html">H5E</a>
|
|
<a href="RM_H5F.html">H5F</a>
|
|
<a href="RM_H5G.html">H5G</a>
|
|
<a href="RM_H5I.html">H5I</a>
|
|
<br>
|
|
<a href="RM_H5P.html">H5P</a>
|
|
<a href="RM_H5R.html">H5R</a>
|
|
H5RA
|
|
<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>
|
|
</td></tr>
|
|
</table>
|
|
</center>
|
|
<hr>
|
|
|
|
|
|
<center>
|
|
<h1>H5RA: Ragged Array Interface</h1>
|
|
</center>
|
|
|
|
<h2>Ragged Array API Functions</h2>
|
|
<table border=1>
|
|
<tr><th align=left>
|
|
<font color=red>
|
|
The H5RA Interface is strictly experimental at this time;
|
|
the interface may change dramatically or support for ragged arrays
|
|
may be unavailable in future in releases. As a result, future releases
|
|
may be unable to retrieve data stored with this interface.
|
|
<p><center>Use these functions at your own risk!<br>
|
|
Do not create any archives using this interface!</center>
|
|
</font>
|
|
</th></tr>
|
|
</table>
|
|
<p>
|
|
These functions enable the user to store and retrieve data in ragged arrays.
|
|
|
|
<table border=0>
|
|
<tr><td valign=top>
|
|
<ul>
|
|
<li><a href="#Ragged-Create">H5RAcreate</a>
|
|
</ul>
|
|
</td><td> </td><td valign=top>
|
|
<ul>
|
|
<li><a href="#Ragged-Open">H5RAopen</a>
|
|
<li><a href="#Ragged-Close">H5RAclose</a>
|
|
</ul>
|
|
</td><td> </td><td valign=top>
|
|
<ul>
|
|
<li><a href="#Ragged-Write">H5RAwrite</a>
|
|
<li><a href="#Ragged-Read">H5RAread</a>
|
|
</ul>
|
|
</td></tr>
|
|
</table>
|
|
|
|
<p>
|
|
This version of the Ragged Array interface implements a
|
|
two-dimensional array where each row of the array is a different length.
|
|
It is intended for applications where the distribution of row lengths
|
|
is such that most rows are near an average length with only a few rows
|
|
that are significantly shorter or longer. The raw data is split among
|
|
two datasets, <code>raw</code> and <code>over</code>: the <code>raw</code>
|
|
dataset is a two-dimensional chunked dataset whose width is large enough
|
|
to hold most of the rows while the <code>over</code> dataset is a heap
|
|
that stores the ends of rows that overflow the first dataset.
|
|
A third dataset, called <code>meta</code>, contains one record for each
|
|
row and describes what elements, if any, overflow the <code>raw</code>
|
|
dataset and where they are stored in the <code>over</code> dataset.
|
|
All three datasets are contained in a single group whose name is the
|
|
name of the ragged array.
|
|
<p>
|
|
|
|
|
|
|
|
<hr>
|
|
<dl>
|
|
<dt><strong>Name:</strong> <a name="Ragged-Create">H5RAcreate</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>hid_t</em> <code>H5RAcreate</code>(<em>hid_t</em> <code>loc_id</code>,
|
|
<em>const char *</em><code>name</code>,
|
|
<em>hid_t</em> <code>type_id</code>,
|
|
<em>hid_t</em> <code>plist_id</code>
|
|
)
|
|
<dt><strong>Purpose:</strong>
|
|
<dd>Creates a ragged array.
|
|
<dt><strong>Description:</strong>
|
|
<dd><code>H5RAcreate</code> creates a new ragged array with the
|
|
name specified in <code>name</code>. A ragged array is
|
|
implemented as a group containing three datasets.
|
|
The dataset <code>raw</code> is a fixed width dataset
|
|
which will hold the majority of the data.
|
|
The dataset <code>over</code> is a one dimensional heap
|
|
which will hold the end of rows which are too long to fit
|
|
in <code>raw</code>
|
|
Finally, the <code>meta</code> dataset contains information
|
|
about the <code>over</code> array. All elements of the
|
|
ragged array are stored with the same data type.
|
|
<p>
|
|
The property list <code>plist_id</code> should contain
|
|
information about chunking. The chunk width will determine
|
|
the width of the <code>raw</code> dataset while the chunk
|
|
length should be such that the total chunk size is
|
|
reasonably large since I/O will be performed in units
|
|
of chunks). If the <code>plist_id</code> does not have
|
|
a chunk size defined (e.g., <code>H5P_DEFAULT</code>)
|
|
then this function will fail.
|
|
<dt><strong>Parameters:</strong>
|
|
<dl>
|
|
<dt><em>hid_t</em> <code>loc_id</code>
|
|
<dd>Location identifier of the dataset.
|
|
<dt><em>const char *</em><code>name</code>
|
|
<dd>The assigned name of the data set to be stored in the
|
|
ragged array.
|
|
<dt><em>hid_t</em> <code>type_id</code>
|
|
<dd>Data type identifier for the ragged array data.
|
|
<dt><em>hid_t</em> <code>plist_id</code>
|
|
<dd>Property list of the dataset.
|
|
</dl>
|
|
<dt><strong>Returns:</strong>
|
|
<dd>Returns a ragged array identifier if successful;
|
|
otherwise returns a negative value.
|
|
</dl>
|
|
|
|
|
|
<hr>
|
|
<dl>
|
|
<dt><strong>Name:</strong> <a name="Ragged-Open">H5RAopen</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>hid_t</em> <code>H5RAopen</code>(<em>hid_t</em> <code>loc_id</code>,
|
|
<em>const char *</em><code>name</code>
|
|
)
|
|
<dt><strong>Purpose:</strong>
|
|
<dd>Opens a ragged array.
|
|
<dt><strong>Description:</strong>
|
|
<dd><code>H5RAopen</code> opens an existing ragged array.
|
|
<p>
|
|
The name of the array, <code>name</code>, should be the same
|
|
that was used when the array was created, i.e., the name of
|
|
the group which implements the array.
|
|
<dt><strong>Parameters:</strong>
|
|
<dl>
|
|
<dt><em>hid_t</em> <code>loc_id</code>
|
|
<dd>The location identifier of the dataset.
|
|
<dt><em>const char *</em><code>name</code>
|
|
<dd>The name of the ragged array.
|
|
</dl>
|
|
<dt><strong>Returns:</strong>
|
|
<dd>Returns a ragged array identifier if successful;
|
|
otherwise returns a negative value.
|
|
</dl>
|
|
|
|
|
|
<hr>
|
|
<dl>
|
|
<dt><strong>Name:</strong> <a name="Ragged-Close">H5RAclose</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>herr_t</em> <code>H5RAclose</code>(<em>hid_t</em> <code>array_id</code>)
|
|
<dt><strong>Purpose:</strong>
|
|
<dd>Closes a ragged array.
|
|
<dt><strong>Description:</strong>
|
|
<dd><code>H5RAclose</code> closes the ragged array specified
|
|
with the array identifier <code>array_id</code>.
|
|
<dt><strong>Parameters:</strong>
|
|
<dl>
|
|
<dt><em>hid_t</em> <code>array_id</code>
|
|
<dd>The array identifier for the ragged array to be closed.
|
|
</dl>
|
|
<dt><strong>Returns:</strong>
|
|
<dd>Returns a non-negative value if successful;
|
|
otherwise returns a negative value.
|
|
</dl>
|
|
|
|
|
|
<hr>
|
|
<dl>
|
|
<dt><strong>Name:</strong> <a name="Ragged-Write">H5RAwrite</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>herr_t</em> <code>H5RAwrite</code>(<em>hid_t</em> <code>array_id</code>,
|
|
<em>hssize_t</em> <code>start_row</code>,
|
|
<em>hsize_t</em> <code>nrows</code>,
|
|
<em>hid_t</em> <code>type_id</code>,
|
|
<em>hsize_t</em> <code>size[/*nrows*/]</code>,
|
|
<em>void *</em><code>buf[/*nrows*/]</code>
|
|
)
|
|
<dt><strong>Purpose:</strong>
|
|
<dd>Writes to a ragged array.
|
|
<dt><strong>Description:</strong>
|
|
<dd><code>H5RAwrite</code> writes a contiguous set of rows to a
|
|
ragged array beginning at row number <code>start_row</code>
|
|
and continuing for <code>nrows</code> rows.
|
|
<p>
|
|
Each row of the ragged array contains <code>size[]</code>
|
|
elements of type <code>type_id</code> and each row is stored
|
|
in a buffer pointed to by <code>buf[]</code>.
|
|
<p>
|
|
Datatype conversion takes place at the time of a read or write
|
|
and is automatic. See the
|
|
<a href="Datatypes.html#Datatypes-DataConversion">Data Conversion</a>
|
|
section of <cite>The Data Type Interface (H5T)</cite> in the
|
|
<cite>HDF5 User's Guide</cite> for a discussion of
|
|
data conversion, including the range of conversions currently
|
|
supported by the HDF5 libraries.
|
|
<dt><strong>Parameters:</strong>
|
|
<dl>
|
|
<dt><em>hid_t</em> <code>array_id</code>
|
|
<dd>Array identifier for the ragged array to be written to.
|
|
<dt><em>hssize_t</em> <code>start_row</code>
|
|
<dd>Row at which the write will start.
|
|
<dt><em>hsize_t</em> <code>nrows</code>
|
|
<dd>Number of rows to be written
|
|
<dt><em>hid_t</em> <code>type_id</code>
|
|
<dd>Data type identifier for the data to be written.
|
|
<dt><em>hsize_t</em> <code>size[/*nrows*/]</code>
|
|
<dd>Lengths of the rows to be written.
|
|
<dt><em>void *</em><code>buf[/*nrows*/]</code>
|
|
<dd>Pointers to buffers containing the data to be written.
|
|
</dl>
|
|
<dt><strong>Returns:</strong>
|
|
<dd>Returns a non-negative value if successful;
|
|
otherwise returns a negative value.
|
|
</dl>
|
|
|
|
|
|
<hr>
|
|
<dl>
|
|
<dt><strong>Name:</strong> <a name="Ragged-Read">H5RAread</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>herr_t</em> <code>H5RAread</code>(<em>hid_t</em> <code>array_id</code>,
|
|
<em>hssize_t</em> <code>start_row</code>,
|
|
<em>hsize_t</em> <code>nrows</code>,
|
|
<em>hid_t</em> <code>type_id</code>,
|
|
<em>hsize_t</em> <code>size[/*nrows*/]</code>,
|
|
<em>void *</em><code>buf[/*nrows*/]</code>
|
|
)
|
|
<dt><strong>Purpose:</strong>
|
|
<dd>
|
|
<dt><strong>Description:</strong>
|
|
<dd><code>H5RAread</code> reads the contents of one or more rows
|
|
of the ragged array pointed to by <code>array_id</code>.
|
|
<p>
|
|
The rows to be read begin at row <code>start_row</code> and
|
|
continue for <code>nrows</code> rows.
|
|
<p>
|
|
All raw data is converted to type <code>type_id</code>.
|
|
<p>
|
|
The caller must allocate the <code>size[]</code> and
|
|
<code>buf[]</code> arrays.
|
|
<p>
|
|
Memory for the data can be allocated by either the caller or
|
|
the library. In the former case, the caller should initialize
|
|
the <code>buf[]</code> array with pointers to valid memory and
|
|
the <code>size[]</code> array with the lengths of the buffers.
|
|
In the latter case, the caller should initialize
|
|
<code>buf[]</code> with null pointers (the input value of
|
|
<code>size[]</code> is irrelevant in this case) and the
|
|
library will allocate memory for each row by calling
|
|
<code>malloc()</code>.
|
|
<p>
|
|
Datatype conversion takes place at the time of a read or write
|
|
and is automatic. See the
|
|
<a href="Datatypes.html#Datatypes-DataConversion">Data Conversion</a>
|
|
section of <cite>The Data Type Interface (H5T)</cite> in the
|
|
<cite>HDF5 User's Guide</cite> for a discussion of
|
|
data conversion, including the range of conversions currently
|
|
supported by the HDF5 libraries.
|
|
<dt><strong>Parameters:</strong>
|
|
<dl>
|
|
<dt><em>hid_t</em> <code>array_id</code>
|
|
<dd>Array identifier for the ragged array to be read from.
|
|
<dt><em>hssize_t</em> <code>start_row</code>
|
|
<dd>Row at which the read will start.
|
|
<dt><em>hsize_t</em> <code>nrows</code>
|
|
<dd>Number of rows to be read
|
|
<dt><em>hid_t</em> <code>type_id</code>
|
|
<dd>Data type identifier for the data to be read.
|
|
<dt><em>hsize_t</em> <code>size[/*nrows*/]</code>
|
|
<dd>Lengths of the rows to be read.
|
|
<dt><em>void *</em><code>buf[/*nrows*/]</code>
|
|
<dd>Pointers to buffers into which the data is to be read.
|
|
</dl>
|
|
<dt><strong>Returns:</strong>
|
|
<dd>Returns a non-negative value if successful.
|
|
The values of the <code>size[]</code> array will be the
|
|
true length of each row. If a row is longer than the
|
|
caller-allocated length, then <code>size[]</code> will
|
|
contain the true length of the row although not all elements
|
|
of that row will be stored in the buffer.
|
|
<p>
|
|
Returns a negative value on failure. The <code>buf[]</code>
|
|
array will contain it's original pointers (null or otherwise),
|
|
although the caller-supplied buffers may have been modified.
|
|
The <code>size[]</code> array may also have been modified.
|
|
</dl>
|
|
|
|
|
|
<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="H5.user.html">HDF5 User Guide</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="RM_H5Front.html">HDF5 Reference Manual</a>
|
|
<br>
|
|
<a href="RM_H5.html">H5</a>
|
|
<a href="RM_H5A.html">H5A</a>
|
|
<a href="RM_H5D.html">H5D</a>
|
|
<a href="RM_H5E.html">H5E</a>
|
|
<a href="RM_H5F.html">H5F</a>
|
|
<a href="RM_H5G.html">H5G</a>
|
|
<a href="RM_H5I.html">H5I</a>
|
|
<br>
|
|
<a href="RM_H5P.html">H5P</a>
|
|
<a href="RM_H5R.html">H5R</a>
|
|
H5RA
|
|
<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>
|
|
</td></tr>
|
|
</table>
|
|
</center>
|
|
<hr>
|
|
|
|
|
|
<address>
|
|
<a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a>
|
|
|
|
<br>
|
|
Last modified: 8 July 1999
|
|
<br>
|
|
Describes HDF5 Version 1.3 (Unrelased development version. Dynamic.)
|
|
|
|
</body>
|
|
</html>
|