diff options
Diffstat (limited to 'doc/src/RM_H5D.html')
| -rw-r--r-- | doc/src/RM_H5D.html | 374 |
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> </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> |