[svn-r475] HDF5 Reference Manual files.
Main file is RM_H5Front.html. Created from the Alpha1 Ref. Manual, Alpha1 User's Guide Documents and the Alpha2 Source Code.
This commit is contained in:
Elena Pourmal
374
doc/src/RM_H5D.html
Normal file
374
doc/src/RM_H5D.html
Normal file
@@ -0,0 +1,374 @@
|
||||
<html>
|
||||
<head><title>
|
||||
HDF5/H5D Draft API Specification
|
||||
</title></head>
|
||||
|
||||
<body>
|
||||
|
||||
<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 FAIL (-1).
|
||||
</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 file 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 FAIL (-1).
|
||||
</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 FAIL (-1).
|
||||
</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 FAIL (-1).
|
||||
</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 FAIL (-1).
|
||||
</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.
|
||||
|
||||
<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 SUCCEED (0) if successful;
|
||||
otherwise FAIL (-1).
|
||||
</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.
|
||||
<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 SUCCEED (0) if successful;
|
||||
otherwise FAIL (-1).
|
||||
</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 SUCCEED (0) if successful;
|
||||
otherwise FAIL (-1).
|
||||
</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 SUCCEED (0) if successful;
|
||||
otherwise FAIL (-1).
|
||||
</dl>
|
||||
|
||||
|
||||
<hr>
|
||||
<address>
|
||||
<a href="mailto:fbaker@ncsa.uiuc.edu">Frank Baker</a>
|
||||
<br>
|
||||
<a href="mailto:h5docs@ncsa.uiuc.edu">HDF5 Documentation</a>
|
||||
|
||||
<br>
|
||||
Last modified: 8 July 1998
|
||||
|
||||
</body>
|
||||
</html>
|
||||
Reference in New Issue
Block a user