mirror of
https://github.com/HDFGroup/hdf5.git
synced 2025-02-11 16:01:00 +08:00
82fb21b613
been checked into "HDF5 Development" branch. General ======= Various "copy edit" types of repairs. Revisions to document cross-linking. Added structural links tying all docs together (banners at top and bottom of documents, similar to Reference Manual banners of the Beta release). Set background color to white in all documents. NCSAfooterlogo.gif hdf2.jpg New image files to make the documents more self-contained (i.e., to prevent loading images from NCSA and HDF home servers). index.html Redesigned to isolate links external to the installation in a single location. Intro to HDF5 ============= H5.intro.html Fixed banner linking Intro to other docs. Set all URLs to be relative within the distribution; nothing points back to the HDF server. Updates to "Limits of the Current Release" and "Changes in the Current Release." HDF5 User's Guide ================= Changed several User Guide section titles such that all sections that are primarily about a particular interface are now titled in the format "The xxxxx Interface (H5x)". H5.user.html Commented out links to developer docs since they are marked in MANIFEST as not being for distribution in the release. Removed 2nd and 3rd indices from page. Changed "freeform" lists of sections (TOCs) to aligned tables. Datatypes.html Removed the sentence "I'm deferring definition until later since they're probably not as important as the other data types." from Section 3.3, "Properties of Date and Time Atomic Types." Added info regarding 'char' versus 'string' datatypes. Added as Section 3.7, "Character and String Datatype Issues." References.html Commented out substantial material (at end of document) from References planning document that is not appropriate for the User Guide but that is worth keeping around. Groups.html Final edits from elimination of "current working group." HDF5 Reference Manual ===================== Removed "Draft" from the <title>__</title> lines. RM_H5Front.html Removed 2nd and 3rd indices from page. Changed "freeform" lists of sections (TOCs) to aligned tables. RM_H5F.html RM_H5P.html Add file mounting information.
367 lines
14 KiB
HTML
367 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: 30 October 1998
|
|
|
|
</body>
|
|
</html>
|