mirror of
https://github.com/HDFGroup/hdf5.git
synced 2025-03-25 17:00:45 +08:00
[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
This commit is contained in:
Frank Baker
parent
febe7d0bd9
commit
c5f5f1f534
@ -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> </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>
|
||||
@ -257,6 +267,60 @@ facilitate moving easily between them.</i>
|
||||
</dl>
|
||||
|
||||
|
||||
<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"> </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
|
||||
</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>
|
||||
@ -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 </code>
|
||||
</th>
|
||||
<th>
|
||||
<code>file_space_id</code>
|
||||
<code>file_space_id </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 </code>
|
||||
</th>
|
||||
<th>
|
||||
<code>file_space_id</code>
|
||||
<code>file_space_id </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>
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user