<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_H5P.html">H5P</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 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 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 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. <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 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. <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 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> <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_H5P.html">H5P</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: 12 August 1998 </body> </html>