From a237041a909d877fe4d3205d52944f146a9c2cb8 Mon Sep 17 00:00:00 2001 From: Quincey Koziol Date: Mon, 8 Oct 2001 10:40:56 -0500 Subject: [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. --- doc/html/RM_H5D.html | 233 +++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 206 insertions(+), 27 deletions(-) diff --git a/doc/html/RM_H5D.html b/doc/html/RM_H5D.html index 720629c..615bff7 100644 --- a/doc/html/RM_H5D.html +++ b/doc/html/RM_H5D.html @@ -463,13 +463,13 @@ facilitate moving easily between them. void * buf )
Purpose: -
Reads raw data from the specified dataset into buf, - converting from file datatype and dataspace to - memory datatype and dataspace. +
Reads raw data from the specified dataset into an application buffer buf, + converting from + file datatype and dataspace to memory datatype and dataspace.
Description:
H5Dread reads a (partial) dataset, specified by its - identifier dataset_id, from the file into the - application memory buffer buf. + identifier dataset_id, from the + file info an application memory buffer buf. Data transfer properties are defined by the argument xfer_plist_id. The memory datatype of the (partial) dataset is identified by @@ -477,21 +477,110 @@ facilitate moving easily between them. The part of the dataset to read is defined by mem_space_id and file_space_id.

- file_space_id can be the constant H5S_ALL, - which indicates that the entire file data space is to be referenced. + file_space_id is used to specify only the selection within + the file dataset's dataspace. Any dataspace specified in file_space_id + is ignored by the library and the dataset's dataspace is always used. + file_space_id can be the constant H5S_ALL. + which indicates that the entire file dataspace, as defined by the + current dimensions of the dataset, is to be selected. +

+ mem_space_id is used to specify both the memory dataspace + and the selection within that dataspace. + mem_space_id can be the constant H5S_ALL, + in which case the file dataspace is used for the memory dataspace and + the selection defined with file_space_id is used for the + selection within that dataspace.

- mem_space_id can be the constant H5S_ALL, - in which case the memory data space is the same as the file data space - defined when the dataset was created. + The behavior of the library for the various combinations of valid + dataspace IDs and H5S_ALL for the mem_space_id and the + file_space_id parameters is described below: + +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ mem_space_id + + file_space_id + + Behavior +
+ valid dataspace ID + + valid dataspace ID + + mem_space_id specifies the memory dataspace and the + selection within it. + file_space_id specifies the selection within the file + dataset's dataspace. +
+ H5S_ALL + + valid dataspace ID + + The file dataset's dataspace is used for the memory dataspace and the + selection specified with file_space_id specifies the + selection within it. + file_space_id specifies the selection within the file + dataset's dataspace. +
+ valid dataspace ID + + H5S_ALL + + mem_space_id specifies the memory dataspace and the + selection within it. + The selection within the file dataset's dataspace is set to the "all" + selection. +
+ H5S_ALL + + H5S_ALL + + 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. +
+

- The number of elements in the memory data space must match - the number of elements in the file data space. + 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.

- xfer_plist_id can be the constant H5P_DEFAULT, - in which case the default data transfer properties are used. - + xfer_plist_id can be the constant H5P_DEFAULT. + in which case the default data transfer properties are used.

- Datatype conversion takes place at the time of a read or write + Datatype conversion takes place at the time of the read and is automatic. See the Data Conversion section of The Data Type Interface (H5T) in the @@ -511,7 +600,7 @@ facilitate moving easily between them.

hid_t xfer_plist_id
Identifier of a transfer property list for this I/O operation.
void * buf -
Buffer to store data read from the file. +
Buffer to receive data read from file.
Returns:
Returns a non-negative value if successful; @@ -526,6 +615,7 @@ facilitate moving easily between them. +
Name: H5Dwrite @@ -552,23 +642,113 @@ facilitate moving easily between them. The part of the dataset to write is defined by mem_space_id and file_space_id.

+ file_space_id is used to specify only the selection within + the file dataset's dataspace. Any dataspace specified in file_space_id + is ignored by the library and the dataset's dataspace is always used. file_space_id can be the constant H5S_ALL. - 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.

+ mem_space_id is used to specify both the memory dataspace + and the selection within that dataspace. mem_space_id can be the constant H5S_ALL, - 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 file_space_id is used for the + selection within that dataspace. +

+ The behavior of the library for the various combinations of valid + dataspace IDs and H5S_ALL for the mem_space_id and the + file_space_id parameters is described below: + +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ mem_space_id + + file_space_id + + Behavior +
+ valid dataspace ID + + valid dataspace ID + + mem_space_id specifies the memory dataspace and the + selection within it. + file_space_id specifies the selection within the file + dataset's dataspace. +
+ H5S_ALL + + valid dataspace ID + + The file dataset's dataspace is used for the memory dataspace and the + selection specified with file_space_id specifies the + selection within it. + file_space_id specifies the selection within the file + dataset's dataspace. +
+ valid dataspace ID + + H5S_ALL + + mem_space_id specifies the memory dataspace and the + selection within it. + The selection within the file dataset's dataspace is set to the "all" + selection. +
+ H5S_ALL + + H5S_ALL + + 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. +
+

- The number of elements in the memory data space must match - the number of elements in the file data space. + 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.

xfer_plist_id can be the constant H5P_DEFAULT. in which case the default data transfer properties are used.

- 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.

- 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 Data Conversion section of The Data Type Interface (H5T) in the @@ -578,7 +758,7 @@ facilitate moving easily between them.

Parameters:
hid_t dataset_id -
Identifier of the dataset read from. +
Identifier of the dataset to write to.
hid_t mem_type_id
Identifier of the memory datatype.
hid_t mem_space_id @@ -602,7 +782,6 @@ facilitate moving easily between them. -->
-
Name: H5Dextend -- cgit v0.12