mirror of
https://github.com/HDFGroup/hdf5.git
synced 2025-02-11 16:01:00 +08:00
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.
438 lines
17 KiB
HTML
438 lines
17 KiB
HTML
<html>
|
|
<head><title>
|
|
HDF5/H5D 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>
|
|
H5D
|
|
<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>
|
|
<a href="RM_H5RA.html">H5RA</a>
|
|
<a href="RM_H5S.html">H5S</a>
|
|
<a href="RM_H5T.html">H5T</a>
|
|
<a href="RM_H5Z.html">H5Z</a>
|
|
<a href="Tools.html">Tools</a>
|
|
<!--
|
|
<a href="Glossary.html">Glossary</a>
|
|
-->
|
|
</center>
|
|
<hr>
|
|
|
|
<center>
|
|
<h1>H5D: Datasets Interface</h1>
|
|
</center>
|
|
|
|
<h2>Dataset Object API Functions</h2>
|
|
|
|
These functions create and manipulate dataset objects,
|
|
and set and retrieve their constant or persistent properties.
|
|
|
|
<table border=0>
|
|
<tr><td valign=top>
|
|
<ul>
|
|
<li><a href="#Dataset-Create">H5Dcreate</a>
|
|
<li><a href="#Dataset-Open">H5Dopen</a>
|
|
<li><a href="#Dataset-GetSpace">H5Dget_space</a>
|
|
</ul>
|
|
</td><td> </td><td valign=top>
|
|
<ul>
|
|
<li><a href="#Dataset-GetType">H5Dget_type</a>
|
|
<li><a href="#Dataset-GetCreatePlist">H5Dget_create_plist</a>
|
|
<li><a href="#Dataset-Read">H5Dread</a>
|
|
</ul>
|
|
</td><td> </td><td valign=top>
|
|
<ul>
|
|
<li><a href="#Dataset-Write">H5Dwrite</a>
|
|
<li><a href="#Dataset-Extend">H5Dextend</a>
|
|
<li><a href="#Dataset-Close">H5Dclose</a>
|
|
</ul>
|
|
</td></tr>
|
|
</table>
|
|
|
|
|
|
<hr>
|
|
<dl>
|
|
<dt><strong>Name:</strong> <a name="Dataset-Create">H5Dcreate</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>hid_t </em><code>H5Dcreate</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>space_id</code>,
|
|
<em>hid_t</em><code>create_plist_id</code>
|
|
)
|
|
<dt><strong>Purpose:</strong>
|
|
<dd>Creates a dataset at the specified location.
|
|
<dt><strong>Description:</strong>
|
|
<dd><code>H5Dcreate</code> creates a data set with a name,
|
|
<code>name</code>, in the file or in the group specified by
|
|
the identifier <code>loc_id</code>.
|
|
The dataset has the datatype and dataspace identified by
|
|
<code>type_id</code> and <code>space_id</code>, respectively.
|
|
The specified datatype and dataspace are the datatype and
|
|
dataspace of the dataset as it will exist in the file,
|
|
which may be different than in application memory.
|
|
Dataset creation properties are specified by the argument
|
|
<code>create_plist_id</code>.
|
|
<p>
|
|
<code>create_plist_id</code> is a <code>H5P_DATASET_CREATE</code>
|
|
property list created with <code>H5Pcreate()</code> and
|
|
initialized with the various functions described above.
|
|
<code>H5Dcreate()</code> returns a dataset identifier for success
|
|
or negative for failure. The identifier should eventually be
|
|
closed by calling <code>H5Dclose()</code> to release resources
|
|
it uses.
|
|
<dt><strong>Parameters:</strong>
|
|
<dl>
|
|
<dt><em>hid_t</em> <code>loc_id</code>
|
|
<dd>Identifier of the file or group to create the dataset within.
|
|
<dt><em>const char *</em> <code>name</code>
|
|
<dd>The name of the dataset to create.
|
|
<dt><em>hid_t</em> <code>type_id</code>
|
|
<dd>Identifier of the datatype to use when creating the dataset.
|
|
<dt><em>hid_t</em> <code>space_id</code>
|
|
<dd>Identifier of the dataspace to use when creating the dataset.
|
|
<dt><em>hid_t</em> <code>create_plist_id</code>
|
|
<dd>Identifier of the set creation property list.
|
|
</dl>
|
|
<dt><strong>Returns:</strong>
|
|
<dd>Returns a dataset identifier if successful;
|
|
otherwise returns a negative value.
|
|
</dl>
|
|
|
|
|
|
<hr>
|
|
<dl>
|
|
<dt><strong>Name:</strong> <a name="Dataset-Open">H5Dopen</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>hid_t </em><code>H5Dopen</code>(<em>hid_t </em><code>loc_id</code>,
|
|
<em>const char *</em><code>name</code>
|
|
)
|
|
<dt><strong>Purpose:</strong>
|
|
<dd>Opens an existing dataset.
|
|
<dt><strong>Description:</strong>
|
|
<dd><code>H5Dopen</code> opens an existing dataset for access in the file
|
|
or group specified in <code>loc_id</code>. <code>name</code> is
|
|
a dataset name and is used to identify the dataset in the file.
|
|
<dt><strong>Parameters:</strong>
|
|
<dl>
|
|
<dt><em>hid_t</em> <code>loc_id</code>
|
|
<dd>Identifier of the dataset to open or the file or group
|
|
to access the dataset within.
|
|
<dt><em>const char *</em> <code>name</code>
|
|
<dd>The name of the dataset to access.
|
|
</dl>
|
|
<dt><strong>Returns:</strong>
|
|
<dd>Returns a dataset identifier if successful;
|
|
otherwise returns a negative value.
|
|
</dl>
|
|
|
|
|
|
<hr>
|
|
<dl>
|
|
<dt><strong>Name:</strong> <a name="Dataset-GetSpace">H5Dget_space</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>hid_t </em><code>H5Dget_space</code>(<em>hid_t </em><code>dataset_id</code>
|
|
)
|
|
<dt><strong>Purpose:</strong>
|
|
<dd>Returns an identifier for a copy of the dataspace for a dataset.
|
|
<dt><strong>Description:</strong>
|
|
<dd><code>H5Dget_space</code> returns an identifier for a copy of the
|
|
dataspace for a dataset.
|
|
The dataspace identifier should be released with the
|
|
<code>H5Sclose()</code> function.
|
|
<dt><strong>Parameters:</strong>
|
|
<dl>
|
|
<dt><em>hid_t</em> <code>dataset_id</code>
|
|
<dd>Identifier of the dataset to query.
|
|
</dl>
|
|
<dt><strong>Returns:</strong>
|
|
<dd>Returns a dataspace identifier if successful;
|
|
otherwise returns a negative value.
|
|
</dl>
|
|
|
|
|
|
<hr>
|
|
<dl>
|
|
<dt><strong>Name:</strong> <a name="Dataset-GetType">H5Dget_type</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>hid_t </em><code>H5Dget_type</code>(<em>hid_t </em><code>dataset_id</code>
|
|
)
|
|
<dt><strong>Purpose:</strong>
|
|
<dd>Returns an identifier for a copy of the datatype for a dataset.
|
|
<dt><strong>Description:</strong>
|
|
<dd><code>H5Dget_type</code> returns an identifier for a copy of the
|
|
datatype for a dataset.
|
|
The datatype should be released with the <code>H5Tclose()</code> function.
|
|
<p>
|
|
If a dataset has a named datatype, then an identifier to the
|
|
opened datatype is returned.
|
|
Otherwise, the returned datatype is read-only.
|
|
If atomization of the datatype fails, then the datatype is closed.
|
|
<dt><strong>Parameters:</strong>
|
|
<dl>
|
|
<dt><em>hid_t</em> <code>dataset_id</code>
|
|
<dd>Identifier of the dataset to query.
|
|
</dl>
|
|
<dt><strong>Returns:</strong>
|
|
<dd>Returns a datatype identifier if successful;
|
|
otherwise returns a negative value.
|
|
</dl>
|
|
|
|
|
|
<hr>
|
|
<dl>
|
|
<dt><strong>Name:</strong> <a name="Dataset-GetCreatePlist">H5Dget_create_plist</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>hid_t </em><code>H5Dget_create_plist</code>(<em>hid_t </em><code>dataset_id</code>
|
|
)
|
|
<dt><strong>Purpose:</strong>
|
|
<dd>Returns an identifier for a copy of the
|
|
dataset creation property list for a dataset.
|
|
<dt><strong>Description:</strong>
|
|
<dd><code>H5Dget_create_plist</code> returns an identifier for a
|
|
copy of the dataset creation property list for a dataset.
|
|
The creation property list identifier should be released with
|
|
the <code>H5Pclose()</code> function.
|
|
<dt><strong>Parameters:</strong>
|
|
<dl>
|
|
<dt><em>hid_t</em> <code>dataset_id</code>
|
|
<dd>Identifier of the dataset to query.
|
|
</dl>
|
|
<dt><strong>Returns:</strong>
|
|
<dd>Returns a dataset creation property list identifier if successful;
|
|
otherwise returns a negative value.
|
|
</dl>
|
|
|
|
|
|
<hr>
|
|
<dl>
|
|
<dt><strong>Name:</strong> <a name="Dataset-Read">H5Dread</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>herr_t </em><code>H5Dread</code>(<em>hid_t </em><code>dataset_id</code>,
|
|
<em>hid_t</em> <code>mem_type_id</code>,
|
|
<em>hid_t</em> <code>mem_space_id</code>,
|
|
<em>hid_t</em> <code>file_space_id</code>,
|
|
<em>hid_t</em> <code>xfer_plist_id</code>,
|
|
<em>void *</em> <code>buf</code>
|
|
)
|
|
<dt><strong>Purpose:</strong>
|
|
<dd>Reads raw data from the specified dataset into <code>buf</code>,
|
|
converting from file datatype and dataspace to
|
|
memory datatype and dataspace.
|
|
<dt><strong>Description:</strong>
|
|
<dd><code>H5Dread</code> reads a (partial) dataset, specified by its
|
|
identifier <code>dataset_id</code>, from the file into the
|
|
application memory buffer <code>buf</code>.
|
|
Data transfer properties are defined by the argument
|
|
<code>xfer_plist_id</code>.
|
|
The memory datatype of the (partial) dataset is identified by
|
|
the identifier <code>mem_type_id</code>.
|
|
The part of the dataset to read is defined by
|
|
<code>mem_space_id</code> and <code>file_space_id</code>.
|
|
<p>
|
|
<code>file_space_id</code> can be the constant <code>H5S_ALL</code>,
|
|
which indicates that the entire file data space is to be referenced.
|
|
<p>
|
|
<code>mem_space_id</code> can be the constant <code>H5S_ALL</code>,
|
|
in which case the memory data space is the same as the file data space
|
|
defined when the dataset was created.
|
|
<p>
|
|
The number of elements in the memory data space must match
|
|
the number of elements in the file data space.
|
|
<p>
|
|
<code>xfer_plist_id</code> can be the constant <code>H5P_DEFAULT</code>,
|
|
in which case the default data transfer properties are used.
|
|
|
|
<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>dataset_id</code>
|
|
<dd>Identifier of the dataset read from.
|
|
<dt><em>hid_t</em> <code>mem_type_id</code>
|
|
<dd>Identifier of the memory datatype.
|
|
<dt><em>hid_t</em> <code>mem_space_id</code>
|
|
<dd>Identifier of the memory dataspace.
|
|
<dt><em>hid_t</em> <code>file_space_id</code>
|
|
<dd>Identifier of the dataset's dataspace in the file.
|
|
<dt><em>hid_t</em> <code>xfer_plist_id</code>
|
|
<dd>Identifier of a transfer property list for this I/O operation.
|
|
<dt><em>void *</em> <code>buf</code>
|
|
<dd>Buffer to store data read from the file.
|
|
</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="Dataset-Write">H5Dwrite</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>herr_t </em><code>H5Dwrite</code>(<em>hid_t </em><code>dataset_id</code>,
|
|
<em>hid_t</em> <code>mem_type_id</code>,
|
|
<em>hid_t</em> <code>mem_space_id</code>,
|
|
<em>hid_t</em> <code>file_space_id</code>,
|
|
<em>hid_t</em> <code>xfer_plist_id</code>,
|
|
<em>const void *</em> <code>buf</code>
|
|
)
|
|
<dt><strong>Purpose:</strong>
|
|
<dd>Writes raw data from an application buffer <code>buf</code> to
|
|
the specified dataset, converting from
|
|
memory datatype and dataspace to file datatype and dataspace.
|
|
<dt><strong>Description:</strong>
|
|
<dd><code>H5Dwrite</code> writes a (partial) dataset, specified by its
|
|
identifier <code>dataset_id</code>, from the
|
|
application memory buffer <code>buf</code> into the file.
|
|
Data transfer properties are defined by the argument
|
|
<code>xfer_plist_id</code>.
|
|
The memory datatype of the (partial) dataset is identified by
|
|
the identifier <code>mem_type_id</code>.
|
|
The part of the dataset to write is defined by
|
|
<code>mem_space_id</code> and <code>file_space_id</code>.
|
|
<p>
|
|
<code>file_space_id</code> can be the constant <code>H5S_ALL</code>.
|
|
which indicates that the entire file data space is to be referenced.
|
|
<p>
|
|
<code>mem_space_id</code> can be the constant <code>H5S_ALL</code>,
|
|
in which case the memory data space is the same as the file data space
|
|
defined when the dataset was created.
|
|
<p>
|
|
The number of elements in the memory data space must match
|
|
the number of elements in the file data space.
|
|
<p>
|
|
<code>xfer_plist_id</code> can be the constant <code>H5P_DEFAULT</code>.
|
|
in which case the default data transfer properties are used.
|
|
<p>
|
|
Writing to an external dataset will fail if the HDF5 file is
|
|
not open for writing.
|
|
<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>dataset_id</code>
|
|
<dd>Identifier of the dataset read from.
|
|
<dt><em>hid_t</em> <code>mem_type_id</code>
|
|
<dd>Identifier of the memory datatype.
|
|
<dt><em>hid_t</em> <code>mem_space_id</code>
|
|
<dd>Identifier of the memory dataspace.
|
|
<dt><em>hid_t</em> <code>file_space_id</code>
|
|
<dd>Identifier of the dataset's dataspace in the file.
|
|
<dt><em>hid_t</em> <code>xfer_plist_id</code>
|
|
<dd>Identifier of a transfer property list for this I/O operation.
|
|
<dt><em>const void *</em> <code>buf</code>
|
|
<dd>Buffer with data to be written to the file.
|
|
</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="Dataset-Extend">H5Dextend</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>herr_t </em><code>H5Dextend</code>(<em>hid_t </em><code>dataset_id</code>,
|
|
<em>const hsize_t *</em> <code>size</code>
|
|
)
|
|
<dt><strong>Purpose:</strong>
|
|
<dd>Extends a dataset with unlimited dimension.
|
|
<dt><strong>Description:</strong>
|
|
<dd><code>H5Dextend</code> verifies that the dataset is at least of size
|
|
<code>size</code>.
|
|
The dimensionality of <code>size</code> is the same as that of
|
|
the dataspace of the dataset being changed.
|
|
This function cannot be applied to a dataset with fixed dimensions.
|
|
<dt><strong>Parameters:</strong>
|
|
<dl>
|
|
<dt><em>hid_t</em> <code>dataset_id</code>
|
|
<dd>Identifier of the dataset.
|
|
<dt><em>const hsize_t *</em> <code>size</code>
|
|
<dd>Array containing the new magnitude of each dimension.
|
|
</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="Dataset-Close">H5Dclose</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>hid_t </em><code>H5Dclose</code>(<em>hid_t </em><code>dataset_id</code>
|
|
)
|
|
<dt><strong>Purpose:</strong>
|
|
<dd>
|
|
<dt><strong>Description:</strong>
|
|
<dd><code>H5Dclose</code> ends access to a dataset specified by
|
|
<code>dataset_id</code> and releases resources used by it.
|
|
Further use of the dataset identifier is illegal in calls to
|
|
the dataset API.
|
|
<dt><strong>Parameters:</strong>
|
|
<dl>
|
|
<dt><em>hid_t</em> <code>dataset_id</code>
|
|
<dd>Identifier of the dataset to finish access to.
|
|
</dl>
|
|
<dt><strong>Returns:</strong>
|
|
<dd>Returns a non-negative value if successful;
|
|
otherwise returns a negative value.
|
|
</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>
|
|
H5D
|
|
<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>
|
|
<a href="RM_H5RA.html">H5RA</a>
|
|
<a href="RM_H5S.html">H5S</a>
|
|
<a href="RM_H5T.html">H5T</a>
|
|
<a href="RM_H5Z.html">H5Z</a>
|
|
<a href="Tools.html">Tools</a>
|
|
<!--
|
|
<a href="Glossary.html">Glossary</a>
|
|
-->
|
|
</center>
|
|
<hr>
|
|
|
|
<address>
|
|
<a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a>
|
|
|
|
<br>
|
|
Last modified: 27 October 1998
|
|
|
|
</body>
|
|
</html>
|