summaryrefslogtreecommitdiffstats
path: root/doc/src/RM_H5D.html
diff options
context:
space:
mode:
Diffstat (limited to 'doc/src/RM_H5D.html')
-rw-r--r--doc/src/RM_H5D.html374
1 files changed, 374 insertions, 0 deletions
diff --git a/doc/src/RM_H5D.html b/doc/src/RM_H5D.html
new file mode 100644
index 0000000..a9f5189
--- /dev/null
+++ b/doc/src/RM_H5D.html
@@ -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>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</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>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</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>