diff options
Diffstat (limited to 'doc/html/RM_H5D.html')
| -rw-r--r-- | doc/html/RM_H5D.html | 233 |
1 files 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.</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> 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> - <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. + 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> - 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. <p> - <code>xfer_plist_id</code> can be the constant <code>H5P_DEFAULT</code>, - in which case the default data transfer properties are used. - + <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 a read or write + 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 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> - 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. <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> |