cd3b105997
Intro
======
H5.intro.html
Major rewrite to Groups section. New Example 7 (groups).
Added TOC and requisite links.
Numbered sections.
Labelled figures and centered those that were not.
Fixed table formatting.
===========
User Guide
===========
H5.user.html
Linked in Chunking.html.
Linked in References.html.
Linked in DDL.html.
Chunking.html
Minor edits.
DDL.html
References.html
New documents.
Datatypes.html
Added "R Reference" to base name description and
"H5T_STD_ROBJ -- Reference to an entire object
in a file" to list of datatype names.
Files.html
H5Fflush
Added scope parameter.
Groups.html
Removed references to "current working group."
Removed H5Gpush, H5Gpop, and H5Gset functions.
Removed note that H5Glink and H5Gunlink were not implemented.
=================
Reference Manual
=================
RM_*.html and Tools.html
Updated Reference Manual internal cross-linking (the link
banner at the top and bottom of each page).
Changed
Returns SUCCEED (0) if successful;
otherwise FAIL (-1).
to read
Returns a non-negative value if successful;
otherwise returns a negative value.
and several derived changes where circumstances differred
only slightly.
Minor copy edits throughout.
RM_H5.html
Corrected H5open "Purpose" statement.
RM_H5A.html
Changed H5Aget_name return type to hssize_t.
RM_H5F.html
H5Fflush
Added scope parameter.
Added H5Freopen.
RM_H5Front.html
Reordered listing of interfaces to alphabetical order (H5,
H5A, H5D, ...)
Added H5I, H5R, and H5RA.
RM_H5G.html
H5Gopen
Edited "Description."
H5Gget_objinfo
Added named datatype to list of valid values for loc_id.
RM_H5I.html Identifier Interface
New section.
RM_H5P.html
Added H5Pset_fill_value and H5Pget_fill_value.
Several minor copy edits.
RM_H5R.html Reference Interface
New section.
H5RA.html
Essentially a new section. It was in the tree previously,
but it did not actually have content.
RM_H5S.html
Changed H5Sget_select_npoints return type to hssize_t.
Tools.html
Updated h5dump documentation.
340 lines
13 KiB
HTML
340 lines
13 KiB
HTML
<html>
|
|
<head><title>
|
|
HDF5/H5RA Draft API Specification
|
|
</title></head>
|
|
|
|
<body>
|
|
|
|
<hr>
|
|
<center>
|
|
<a href="RM_H5Front.html">HDF5 Reference Manual</a>
|
|
<a href="RM_H5.html">H5</a>
|
|
<a href="RM_H5A.html">H5A</a>
|
|
<a href="RM_H5D.html">H5D</a>
|
|
<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>
|
|
<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>
|
|
<!--
|
|
<a href="Glossary.html">Glossary</a>
|
|
-->
|
|
</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>
|
|
<a href="RM_H5Front.html">HDF5 Reference Manual</a>
|
|
<a href="RM_H5.html">H5</a>
|
|
<a href="RM_H5A.html">H5A</a>
|
|
<a href="RM_H5D.html">H5D</a>
|
|
<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>
|
|
<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>
|
|
<!--
|
|
<a href="Glossary.html">Glossary</a>
|
|
-->
|
|
</center>
|
|
<hr>
|
|
|
|
<address>
|
|
<a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a>
|
|
|
|
<br>
|
|
Last modified: 27 October 1998
|
|
|
|
</body>
|
|
</html>
|