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.
465 lines
17 KiB
HTML
465 lines
17 KiB
HTML
<html>
|
|
<head><title>
|
|
HDF5/H5D 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>
|
|
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>
|
|
<br>
|
|
<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>
|
|
</td></tr>
|
|
</table>
|
|
</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>
|
|
<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>
|
|
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>
|
|
<br>
|
|
<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>
|
|
</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>
|