[svn-r4531] Purpose:
Update docs
Description:
H5Dread and H5Dwrite description contained some inaccurate information about
how H5S_ALL works as a parameter for the memory and file dataspaces.
Solution:
Updated information to reflect current library behavior for H5S_ALL.
This commit is contained in:
Quincey Koziol
@@ -463,13 +463,13 @@ 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 <code>buf</code>,
|
||||
converting from file datatype and dataspace to
|
||||
memory datatype and dataspace.
|
||||
<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.
|
||||
<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>.
|
||||
identifier <code>dataset_id</code>, from the
|
||||
file info 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
|
||||
@@ -477,21 +477,110 @@ facilitate moving easily between them.</i>
|
||||
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.
|
||||
<code>file_space_id</code> is used to specify only the selection within
|
||||
the file dataset's dataspace. Any dataspace specified in <code>file_space_id</code>
|
||||
is ignored by the library and the dataset's dataspace is always used.
|
||||
<code>file_space_id</code> can be the constant <code>H5S_ALL</code>.
|
||||
which indicates that the entire file dataspace, as defined by the
|
||||
current dimensions of the dataset, is to be selected.
|
||||
<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.
|
||||
<code>mem_space_id</code> is used to specify both the memory dataspace
|
||||
and the selection within that dataspace.
|
||||
<code>mem_space_id</code> can be the constant <code>H5S_ALL</code>,
|
||||
in which case the file dataspace is used for the memory dataspace and
|
||||
the selection defined with <code>file_space_id</code> is used for the
|
||||
selection within that dataspace.
|
||||
<p>
|
||||
The number of elements in the memory data space must match
|
||||
the number of elements in the file data space.
|
||||
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
|
||||
<code>file_space_id</code> parameters is described below:
|
||||
|
||||
<br><br>
|
||||
<table border=1>
|
||||
<tr>
|
||||
<th>
|
||||
<code>mem_space_id</code>
|
||||
</th>
|
||||
<th>
|
||||
<code>file_space_id</code>
|
||||
</th>
|
||||
<th>
|
||||
Behavior
|
||||
</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
valid dataspace ID
|
||||
</td>
|
||||
<td>
|
||||
valid dataspace ID
|
||||
</td>
|
||||
<td>
|
||||
<code>mem_space_id</code> specifies the memory dataspace and the
|
||||
selection within it.
|
||||
<code>file_space_id</code> specifies the selection within the file
|
||||
dataset's dataspace.
|
||||
</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>
|
||||
H5S_ALL
|
||||
</td>
|
||||
<td>
|
||||
valid dataspace ID
|
||||
</td>
|
||||
<td>
|
||||
The file dataset's dataspace is used for the memory dataspace and the
|
||||
selection specified with <code>file_space_id</code> specifies the
|
||||
selection within it.
|
||||
<code>file_space_id</code> specifies the selection within the file
|
||||
dataset's dataspace.
|
||||
</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>
|
||||
valid dataspace ID
|
||||
</td>
|
||||
<td>
|
||||
H5S_ALL
|
||||
</td>
|
||||
<td>
|
||||
<code>mem_space_id</code> specifies the memory dataspace and the
|
||||
selection within it.
|
||||
The selection within the file dataset's dataspace is set to the "all"
|
||||
selection.
|
||||
</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>
|
||||
H5S_ALL
|
||||
</td>
|
||||
<td>
|
||||
H5S_ALL
|
||||
</td>
|
||||
<td>
|
||||
The file dataset's dataspace is used for the memory dataspace and the
|
||||
selection within the memory dataspace is set to the "all" selection.
|
||||
The selection within the file dataset's dataspace is set to the "all"
|
||||
selection.
|
||||
</td>
|
||||
</tr>
|
||||
|
||||
</table>
|
||||
|
||||
<p>
|
||||
<code>xfer_plist_id</code> can be the constant <code>H5P_DEFAULT</code>,
|
||||
in which case the default data transfer properties are used.
|
||||
|
||||
Setting an "all" selection indicates that the entire dataspace, as
|
||||
defined by the current dimensions of a dataspace, will be selected.
|
||||
The number of elements selected in the memory dataspace must match the
|
||||
number of elements selected in the file dataspace.
|
||||
<p>
|
||||
Datatype conversion takes place at the time of a read or write
|
||||
<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
|
||||
<a href="Datatypes.html#Datatypes-DataConversion">Data Conversion</a>
|
||||
section of <cite>The Data Type Interface (H5T)</cite> in the
|
||||
@@ -511,7 +600,7 @@ facilitate moving easily between them.</i>
|
||||
<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.
|
||||
<dd>Buffer to receive data read from file.
|
||||
</dl>
|
||||
<dt><strong>Returns:</strong>
|
||||
<dd>Returns a non-negative value if successful;
|
||||
@@ -526,6 +615,7 @@ facilitate moving easily between them.</i>
|
||||
</dl>
|
||||
|
||||
|
||||
|
||||
<hr>
|
||||
<dl>
|
||||
<dt><strong>Name:</strong> <a name="Dataset-Write">H5Dwrite</a>
|
||||
@@ -552,23 +642,113 @@ facilitate moving easily between them.</i>
|
||||
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> is used to specify only the selection within
|
||||
the file dataset's dataspace. Any dataspace specified in <code>file_space_id</code>
|
||||
is ignored by the library and the dataset's dataspace is always used.
|
||||
<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.
|
||||
which indicates that the entire file dataspace, as defined by the
|
||||
current dimensions of the dataset, is to be selected.
|
||||
<p>
|
||||
<code>mem_space_id</code> is used to specify both the memory dataspace
|
||||
and the selection within that dataspace.
|
||||
<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.
|
||||
in which case the file dataspace is used for the memory dataspace and
|
||||
the selection defined with <code>file_space_id</code> is used for the
|
||||
selection within that dataspace.
|
||||
<p>
|
||||
The number of elements in the memory data space must match
|
||||
the number of elements in the file data space.
|
||||
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
|
||||
<code>file_space_id</code> parameters is described below:
|
||||
|
||||
<br><br>
|
||||
<table border=1>
|
||||
<tr>
|
||||
<th>
|
||||
<code>mem_space_id</code>
|
||||
</th>
|
||||
<th>
|
||||
<code>file_space_id</code>
|
||||
</th>
|
||||
<th>
|
||||
Behavior
|
||||
</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
valid dataspace ID
|
||||
</td>
|
||||
<td>
|
||||
valid dataspace ID
|
||||
</td>
|
||||
<td>
|
||||
<code>mem_space_id</code> specifies the memory dataspace and the
|
||||
selection within it.
|
||||
<code>file_space_id</code> specifies the selection within the file
|
||||
dataset's dataspace.
|
||||
</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>
|
||||
H5S_ALL
|
||||
</td>
|
||||
<td>
|
||||
valid dataspace ID
|
||||
</td>
|
||||
<td>
|
||||
The file dataset's dataspace is used for the memory dataspace and the
|
||||
selection specified with <code>file_space_id</code> specifies the
|
||||
selection within it.
|
||||
<code>file_space_id</code> specifies the selection within the file
|
||||
dataset's dataspace.
|
||||
</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>
|
||||
valid dataspace ID
|
||||
</td>
|
||||
<td>
|
||||
H5S_ALL
|
||||
</td>
|
||||
<td>
|
||||
<code>mem_space_id</code> specifies the memory dataspace and the
|
||||
selection within it.
|
||||
The selection within the file dataset's dataspace is set to the "all"
|
||||
selection.
|
||||
</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>
|
||||
H5S_ALL
|
||||
</td>
|
||||
<td>
|
||||
H5S_ALL
|
||||
</td>
|
||||
<td>
|
||||
The file dataset's dataspace is used for the memory dataspace and the
|
||||
selection within the memory dataspace is set to the "all" selection.
|
||||
The selection within the file dataset's dataspace is set to the "all"
|
||||
selection.
|
||||
</td>
|
||||
</tr>
|
||||
|
||||
</table>
|
||||
|
||||
<p>
|
||||
Setting an "all" selection indicates that the entire dataspace, as
|
||||
defined by the current dimensions of a dataspace, will be selected.
|
||||
The number of elements selected in the memory dataspace must match the
|
||||
number of elements selected in the file dataspace.
|
||||
<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.
|
||||
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 a read or write
|
||||
Datatype conversion takes place at the time of the 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
|
||||
@@ -578,7 +758,7 @@ facilitate moving easily between them.</i>
|
||||
<dt><strong>Parameters:</strong>
|
||||
<dl>
|
||||
<dt><em>hid_t</em> <code>dataset_id</code>
|
||||
<dd>Identifier of the dataset read from.
|
||||
<dd>Identifier of the dataset to write to.
|
||||
<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>
|
||||
@@ -602,7 +782,6 @@ facilitate moving easily between them.</i>
|
||||
-->
|
||||
</dl>
|
||||
|
||||
|
||||
<hr>
|
||||
<dl>
|
||||
<dt><strong>Name:</strong> <a name="Dataset-Extend">H5Dextend</a>
|
||||
|
||||
Reference in New Issue
Block a user