summaryrefslogtreecommitdiffstats
path: root/doc/html/RM_H5D.html
diff options
context:
space:
mode:
authorFrank Baker <fbaker@hdfgroup.org>2003-04-02 19:08:38 (GMT)
committerFrank Baker <fbaker@hdfgroup.org>2003-04-02 19:08:38 (GMT)
commitc5f5f1f5343a4ccf061b685ff493110c4f9d73f2 (patch)
tree98164d4549dac4e34169a7f17429ff438e1b7d25 /doc/html/RM_H5D.html
parentfebe7d0bd9c74b3e238870e6ce50b1b1a8258221 (diff)
downloadhdf5-c5f5f1f5343a4ccf061b685ff493110c4f9d73f2.zip
hdf5-c5f5f1f5343a4ccf061b685ff493110c4f9d73f2.tar.gz
hdf5-c5f5f1f5343a4ccf061b685ff493110c4f9d73f2.tar.bz2
[svn-r6566]
Purpose: New feature -- Fill value and storage space allocation changes Description: Added H5Dget_space_status Modified H5Dcreate and H5Dread to discuss Also, copy and readability edits in H5Dcreate, H5Dread, and H5Dwrite Platforms tested: IE 6, Safari
Diffstat (limited to 'doc/html/RM_H5D.html')
-rw-r--r--doc/html/RM_H5D.html171
1 files changed, 129 insertions, 42 deletions
diff --git a/doc/html/RM_H5D.html b/doc/html/RM_H5D.html
index e51d439..37b869c 100644
--- a/doc/html/RM_H5D.html
+++ b/doc/html/RM_H5D.html
@@ -61,10 +61,11 @@ and set and retrieve their constant or persistent properties.
<li><a href="#Dataset-Open">H5Dopen</a>
<li><a href="#Dataset-Close">H5Dclose</a>
<li><a href="#Dataset-GetSpace">H5Dget_space</a>
- <li><a href="#Dataset-GetType">H5Dget_type</a>
+ <li><a href="#Dataset-GetSpaceStatus">H5Dget_space_status</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-GetStorageSize">H5Dget_storage_size</a>
<li><a href="#Dataset-VLGetBuf">H5Dvlen_get_buf_size</a>
@@ -159,10 +160,19 @@ facilitate moving easily between them.</i>
<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.
+ <p>
+ <code>H5Dcreate</code> returns an error if the dataset's datatype
+ includes a variable-length (VL) datatype and the fill value
+ is undefined, i.e., set to <code>NULL</code> in the
+ dataset creation property list.
+ Such a VL datatype may be directly included,
+ indirectly included as part of a compound or array datatype, or
+ indirectly included as part of a nested compound or array datatype.
+ <p>
<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.
+ or a negative value for failure.
+ The dataset 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>
@@ -259,6 +269,60 @@ facilitate moving easily between them.</i>
<hr>
<dl>
+<dt><strong>Name:</strong> <a name="Dataset-GetSpaceStatus">H5Dget_space_status</a>
+<dt><strong>Signature:</strong>
+ <dd><em>hid_t</em> <code>H5Dget_space_status</code>(<em>hid_t </em><code>dset_id</code>,
+ <em>H5D_space_status_t *</em><code>status</code>)
+<dt><strong>Purpose:</strong>
+ <dd>Determines whether space has been allocated for a dataset.
+<dt><strong>Description:</strong>
+ <dd><code>H5Dget_space_status</code> determines whether space has been
+ allocated for the dataset <code>dset_id</code>.
+ <p>
+ Space allocation status is returned in <code>status</code>,
+ which will have one of the following values:
+ <center>
+ <table border="0">
+ <tr valign="top"><td rowspan="3">&nbsp;&nbsp;&nbsp;&nbsp;</td><td>
+ H5D_SPACE_STATUS_NOT_ALLOCATED
+ </td><td>
+ Space has not been allocated for this dataset.
+ </td></tr><tr valign="top"><td>
+ H5D_SPACE_STATUS_ALLOCATED
+ </td><td>
+ Space has been allocated for this dataset.
+ </td></tr><tr valign="top"><td>
+ H5D_SPACE_STATUS_PART_ALLOCATED&nbsp;&nbsp;
+ </td><td>
+ Space has been partially allocated for this dataset.
+ (Used only for datasets with chunked storage.)
+ </td></tr>
+ </table>
+ </center>
+<dt><strong>Parameters:</strong>
+ <dl>
+ <dt><em>hid_t</em> <code>dset_id</code>
+ <dd>IN: Identifier of the dataset to query.
+ <dt><em>H5D_space_status_t *</em><code>status</code>
+ <dd>OUT: Space allocatioin status.
+ </dl>
+<dt><strong>Returns:</strong>
+ <dd>Returns a non-negative value if successful;
+ otherwise returns a negative value.
+<!--
+<dt><strong>Non-C API(s):</strong>
+ <dd><a href="fortran/h5d_FORTRAN.html#h5dget_space_f"
+ target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
+ -->
+ <!--
+ <img src="Graphics/Java.gif">
+ <img src="Graphics/C++.gif">
+ -->
+</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>
@@ -468,13 +532,11 @@ facilitate moving easily between them.</i>
<em>void *</em> <code>buf</code>
)
<dt><strong>Purpose:</strong>
- <dd>Reads raw data from the specified dataset into an application buffer <code>buf</code>,
- converting from
- file datatype and dataspace to memory datatype and dataspace.
+ <dd>Reads raw data from a dataset into a buffer.
<dt><strong>Description:</strong>
<dd><code>H5Dread</code> reads a (partial) dataset, specified by its
identifier <code>dataset_id</code>, from the
- file info an application memory buffer <code>buf</code>.
+ file into an 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
@@ -496,29 +558,34 @@ facilitate moving easily between them.</i>
the selection defined with <code>file_space_id</code> is used for the
selection within that dataspace.
<p>
+ If raw data storage space has not been allocated for the dataset
+ and a fill value has been defined, the returned buffer <code>buf</code>
+ is filled with the fill value.
+ <p>
The behavior of the library for the various combinations of valid
- dataspace IDs and H5S_ALL for the <code>mem_space_id</code> and the
+ dataspace identifiers and H5S_ALL for the <code>mem_space_id</code> and the
<code>file_space_id</code> parameters is described below:
<br><br>
- <table border=1>
+ <table border=0>
<tr>
<th>
- <code>mem_space_id</code>
+ <code>mem_space_id&nbsp;&nbsp;</code>
</th>
<th>
- <code>file_space_id</code>
+ <code>file_space_id&nbsp;&nbsp;</code>
</th>
<th>
Behavior
</th>
</tr>
- <tr>
+
+ <tr valign="top">
<td>
- valid dataspace ID
+ valid dataspace identifier
</td>
<td>
- valid dataspace ID
+ valid dataspace identifier
</td>
<td>
<code>mem_space_id</code> specifies the memory dataspace and the
@@ -528,12 +595,12 @@ facilitate moving easily between them.</i>
</td>
</tr>
- <tr>
+ <tr valign="top">
<td>
H5S_ALL
</td>
<td>
- valid dataspace ID
+ valid dataspace identifier
</td>
<td>
The file dataset's dataspace is used for the memory dataspace and the
@@ -544,9 +611,9 @@ facilitate moving easily between them.</i>
</td>
</tr>
- <tr>
+ <tr valign="top">
<td>
- valid dataspace ID
+ valid dataspace identifier
</td>
<td>
H5S_ALL
@@ -559,7 +626,7 @@ facilitate moving easily between them.</i>
</td>
</tr>
- <tr>
+ <tr valign="top">
<td>
H5S_ALL
</td>
@@ -585,8 +652,9 @@ facilitate moving easily between them.</i>
<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 the read
- and is automatic. See the
+ Data is automatically converted from the file datatype
+ and dataspace to the memory datatype and dataspace
+ at the time of the write. 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
@@ -634,9 +702,7 @@ facilitate moving easily between them.</i>
<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.
+ <dd>Writes raw data from a buffer to a dataset.
<dt><strong>Description:</strong>
<dd><code>H5Dwrite</code> writes a (partial) dataset, specified by its
identifier <code>dataset_id</code>, from the
@@ -667,24 +733,25 @@ facilitate moving easily between them.</i>
<code>file_space_id</code> parameters is described below:
<br><br>
- <table border=1>
+ <table border=0>
<tr>
<th>
- <code>mem_space_id</code>
+ <code>mem_space_id&nbsp;&nbsp;</code>
</th>
<th>
- <code>file_space_id</code>
+ <code>file_space_id&nbsp;&nbsp;</code>
</th>
<th>
Behavior
</th>
</tr>
- <tr>
+
+ <tr valign="top">
<td>
- valid dataspace ID
+ valid dataspace identifier
</td>
<td>
- valid dataspace ID
+ valid dataspace identifier
</td>
<td>
<code>mem_space_id</code> specifies the memory dataspace and the
@@ -694,12 +761,12 @@ facilitate moving easily between them.</i>
</td>
</tr>
- <tr>
+ <tr valign="top">
<td>
H5S_ALL
</td>
<td>
- valid dataspace ID
+ valid dataspace identifier
</td>
<td>
The file dataset's dataspace is used for the memory dataspace and the
@@ -710,9 +777,9 @@ facilitate moving easily between them.</i>
</td>
</tr>
- <tr>
+ <tr valign="top">
<td>
- valid dataspace ID
+ valid dataspace identifier
</td>
<td>
H5S_ALL
@@ -725,7 +792,7 @@ facilitate moving easily between them.</i>
</td>
</tr>
- <tr>
+ <tr valign="top">
<td>
H5S_ALL
</td>
@@ -754,8 +821,9 @@ facilitate moving easily between them.</i>
Writing to an dataset will fail if the HDF5 file was
not opened with write access permissions.
<p>
- Datatype conversion takes place at the time of the write
- and is automatic. See the
+ Data is automatically converted from the memory datatype
+ and dataspace to the file datatype and dataspace
+ at the time of the write. 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
@@ -926,16 +994,35 @@ facilitate moving easily between them.</i>
<dt><strong>Purpose:</strong>
<dd>Fills dataspace elements with a fill value in a memory buffer.
<dt><strong>Description:</strong>
- <dd><code>H5Dfill</code> explicitly fills a dataspace selection
- in memory with the fill value specified in <code>fill</code>.
- <p>
+ <dd><code>H5Dfill</code> explicitly fills
+ the dataspace selection in memory, <code>space_id</code>,
+ with the fill value specified in <code>fill</code>.
If <code>fill</code> is <code>NULL</code>,
a fill value of <code>0</code> (zero) is used.
<p>
+ <code>fill_type_id</code> specifies the datatype
+ of the fill value.<br>
+ <code>buf</code> specifies the buffer in which
+ the dataspace elements will be written.<br>
+ <code>buf_type_id</code> specifies the datatype of
+ those data elements.
+ <p>
Note that if the fill value datatype differs
from the memory buffer datatype, the fill value
will be converted to the memory buffer datatype
before filling the selection.
+<dt><strong>Note:</strong>
+ <dd>Applications sometimes write data only to portions of
+ an allcoated dataset. It is often useful in such cases
+ to fill the unused space with a known
+ <span class="termEmphasis">fill value</span>.
+ See <a href="RM_H5P.html#Property-SetFillValue">H5Pset_fill_value</a>
+ for further discussion.
+ Related functions include
+ <a href="RM_H5P.html#Property-SetFillValue">H5Pset_fill_value</a>,
+ <a href="RM_H5P.html#Property-GetFillValue">H5Pget_fill_value</a>,
+ and
+ <a href="RM_H5P.html#Property-SetFillTime">H5Pset_fill_time</a>.
<dt><strong>Parameters:</strong>
<dl>
<dt><em>const void *</em><code>fill</code>
@@ -1005,7 +1092,7 @@ And in this document, the
Describes HDF5 Release 1.5, Unreleased Development Branch
</address><!-- #EndLibraryItem -->
-Last modified: 19 April 2002
+Last modified: 28 March 2003
</body>
</html>