diff options
Diffstat (limited to 'doc/html/RM_H5D.html')
| -rw-r--r-- | doc/html/RM_H5D.html | 171 |
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> </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"> </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> <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 </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> |