mirror of
https://github.com/HDFGroup/hdf5.git
synced 2024-11-27 02:10:55 +08:00
4146d79af1
Purpose:
Changed "HDF5 User's Guide" links (in navigation bars, primarily)
to point to new user's guide, which will reside for a while yet on
the HDF server.
The old user's guide will still go out with the distribution under
the label "HDF5 User's Guide, Release 1.4.5."
Platforms tested:
IE 5
1251 lines
48 KiB
HTML
1251 lines
48 KiB
HTML
<html>
|
|
<head><title>
|
|
HDF5/H5D API Specification
|
|
</title>
|
|
|
|
<!-- #BeginLibraryItem "/ed_libs/styles_RM.lbi" -->
|
|
|
|
<!--
|
|
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
|
|
* Copyright by the Board of Trustees of the University of Illinois. *
|
|
* All rights reserved. *
|
|
* *
|
|
* This file is part of HDF5. The full HDF5 copyright notice, including *
|
|
* terms governing use, modification, and redistribution, is contained in *
|
|
* the files COPYING and Copyright.html. COPYING can be found at the root *
|
|
* of the source code distribution tree; Copyright.html can be found at the *
|
|
* root level of an installed copy of the electronic HDF5 document set and *
|
|
* is linked from the top-level documents page. It can also be found at *
|
|
* http://hdf.ncsa.uiuc.edu/HDF5/doc/Copyright.html. If you do not have *
|
|
* access to either file, you may request a copy from hdfhelp@ncsa.uiuc.edu. *
|
|
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
|
|
-->
|
|
|
|
<link href="ed_styles/RMelect.css" rel="stylesheet" type="text/css">
|
|
<!-- #EndLibraryItem --></head>
|
|
|
|
<body bgcolor="#FFFFFF">
|
|
|
|
|
|
<!-- #BeginLibraryItem "/ed_libs/NavBar_RM.lbi" --><hr>
|
|
<center>
|
|
<table border=0 width=98%>
|
|
<tr><td valign=top align=left>
|
|
<a href="index.html">HDF5 documents and links</a> <br>
|
|
<a href="H5.intro.html">Introduction to HDF5</a> <br>
|
|
<a href="http://hdf.ncsa.uiuc.edu/HDF5/doc/UG/index.html">HDF5 User Guide</a> <br>
|
|
<!--
|
|
<a href="Glossary.html">Glossary</a><br>
|
|
-->
|
|
</td>
|
|
<td valign=top align=right>
|
|
And in this document, the
|
|
<a href="RM_H5Front.html">HDF5 Reference Manual</a>
|
|
<br>
|
|
<a href="RM_H5.html">H5</a>
|
|
<a href="RM_H5A.html">H5A</a>
|
|
<a href="RM_H5D.html">H5D</a>
|
|
<a href="RM_H5E.html">H5E</a>
|
|
<a href="RM_H5F.html">H5F</a>
|
|
<a href="RM_H5G.html">H5G</a>
|
|
<a href="RM_H5I.html">H5I</a>
|
|
<a href="RM_H5P.html">H5P</a>
|
|
<br>
|
|
<a href="RM_H5R.html">H5R</a>
|
|
<a href="RM_H5S.html">H5S</a>
|
|
<a href="RM_H5T.html">H5T</a>
|
|
<a href="RM_H5Z.html">H5Z</a>
|
|
<a href="Tools.html">Tools</a>
|
|
<a href="PredefDTypes.html">Datatypes</a>
|
|
</td></tr>
|
|
</table>
|
|
</center>
|
|
<hr>
|
|
<!-- #EndLibraryItem --><center>
|
|
<h1>H5D: Datasets Interface</h1>
|
|
</center>
|
|
|
|
<h2>Dataset Object API Functions</h2>
|
|
|
|
These functions create and manipulate dataset objects,
|
|
and set and retrieve their constant or persistent properties.
|
|
|
|
<p>
|
|
<strong>The C Interfaces:</strong>
|
|
|
|
<table border=0>
|
|
<tr><td valign=top>
|
|
<ul>
|
|
<li><a href="#Dataset-Create">H5Dcreate</a>
|
|
<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-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-GetOffset">H5Dget_offset</a>
|
|
<li><a href="#Dataset-GetStorageSize">H5Dget_storage_size</a>
|
|
<li><a href="#Dataset-VLGetBuf">H5Dvlen_get_buf_size</a>
|
|
<li><a href="#Dataset-VLReclaim">H5Dvlen_reclaim</a>
|
|
</ul>
|
|
</td><td> </td><td valign=top>
|
|
<ul>
|
|
<!--
|
|
<li><a href="#Dataset-Debug">H5Ddebug</a>
|
|
This function is in the distributed source code and is technically
|
|
a public function, but it is NOT intended for public use.
|
|
It is used only by certain tools.
|
|
DO NOT list it in the Reference Manual.
|
|
-->
|
|
<li><a href="#Dataset-Read">H5Dread</a>
|
|
<li><a href="#Dataset-Write">H5Dwrite</a>
|
|
<li><a href="#Dataset-Iterate">H5Diterate</a>
|
|
<li><a href="#Dataset-Extend">H5Dextend</a>
|
|
<li><a href="#Dataset-Fill">H5Dfill</a>
|
|
</ul>
|
|
</td></tr>
|
|
</table>
|
|
<br>
|
|
|
|
<i>Alphabetical Listing</i>
|
|
|
|
<table border="0">
|
|
<tr>
|
|
<td valign="top">
|
|
<li><a href="#Dataset-Close">H5Dclose</a>
|
|
<li><a href="#Dataset-Create">H5Dcreate</a>
|
|
<li><a href="#Dataset-Extend">H5Dextend</a>
|
|
<li><a href="#Dataset-Fill">H5Dfill</a>
|
|
<li><a href="#Dataset-GetCreatePlist">H5Dget_create_plist</a>
|
|
<li><a href="#Dataset-GetOffset">H5Dget_offset</a>
|
|
</td>
|
|
|
|
<td> </td>
|
|
|
|
<td valign="top">
|
|
<li><a href="#Dataset-GetSpace">H5Dget_space</a>
|
|
<li><a href="#Dataset-GetSpaceStatus">H5Dget_space_status</a>
|
|
<li><a href="#Dataset-GetStorageSize">H5Dget_storage_size</a>
|
|
<li><a href="#Dataset-GetType">H5Dget_type</a>
|
|
<li><a href="#Dataset-Iterate">H5Diterate</a>
|
|
<li><a href="#Dataset-Open">H5Dopen</a>
|
|
</td>
|
|
|
|
<td> </td>
|
|
|
|
<td valign="top">
|
|
<li><a href="#Dataset-Read">H5Dread</a>
|
|
<li><a href="#Dataset-VLGetBuf">H5Dvlen_get_buf_size</a>
|
|
<li><a href="#Dataset-VLReclaim">H5Dvlen_reclaim</a>
|
|
<li><a href="#Dataset-Write">H5Dwrite</a>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p>
|
|
<strong>The FORTRAN90 Interfaces:</strong>
|
|
|
|
<br>
|
|
<font size=-1>
|
|
<i>In general, each FORTRAN90 subroutine performs exactly the same task
|
|
as the corresponding C function. The links below go to the C function
|
|
descriptions, which serve as general descriptions for both. A button,
|
|
under <strong>Non-C API(s)</strong> at the end of the C function description,
|
|
opens an external browser window displaying the FORTRAN90-specific
|
|
information. You will probably want to adjust the size and location of
|
|
this external window so that both browser windows are visible and to
|
|
facilitate moving easily between them.</i>
|
|
</font>
|
|
|
|
<table border=0>
|
|
<tr><td valign=top>
|
|
<ul>
|
|
<li><a href="#Dataset-Create">h5dcreate_f</a>
|
|
<li><a href="#Dataset-Open">h5dopen_f</a>
|
|
<li><a href="#Dataset-Close">h5dclose_f</a>
|
|
<li><a href="#Dataset-GetSpace">h5dget_space_f</a>
|
|
<li><a href="#Dataset-GetSpaceStatus">h5dget_space_status_f</a>
|
|
</ul>
|
|
</td><td> </td><td valign=top>
|
|
<ul>
|
|
<li><a href="#Dataset-GetType">h5dget_type_f</a>
|
|
<li><a href="#Dataset-GetCreatePlist">h5dget_create_plist_f</a>
|
|
<li><a href="#Dataset-GetOffset">h5dget_offset_f</a>
|
|
<li><a href="#Dataset-GetStorageSize">h5dget_storage_size_f</a>
|
|
<li><a href="#Dataset-VLGetBuf">h5dvlen_get_max_len_f</a>
|
|
<!--<li><a href="#Dataset-VLReclaim">h5dvlen_reclaim_f</a> -->
|
|
</ul>
|
|
</td><td> </td><td valign=top>
|
|
<ul>
|
|
<li><a href="#Dataset-Read">h5dread_f</a>
|
|
<li><a href="#Dataset-Write">h5dwrite_f</a>
|
|
<!--<li><a href="#Dataset-Iterate">h5diterate_f</a> -->
|
|
<!--<li><a href="#Dataset-Debug">h5ddebug_f</a> -->
|
|
<li><a href="#Dataset-Extend">h5dextend_f</a>
|
|
<li><a href="#Dataset-Fill">h5dfill_f</a>
|
|
</ul>
|
|
</td></tr>
|
|
</table>
|
|
|
|
|
|
<hr>
|
|
<dl>
|
|
<dt><strong>Name:</strong> <a name="Dataset-Create">H5Dcreate</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>hid_t </em><code>H5Dcreate</code>(<em>hid_t </em><code>loc_id</code>,
|
|
<em>const char *</em><code>name</code>,
|
|
<em>hid_t</em> <code>type_id</code>,
|
|
<em>hid_t</em> <code>space_id</code>,
|
|
<em>hid_t</em> <code>create_plist_id</code>
|
|
)
|
|
<dt><strong>Purpose:</strong>
|
|
<dd>Creates a dataset at the specified location.
|
|
<dt><strong>Description:</strong>
|
|
<dd><code>H5Dcreate</code> creates a data set with a name,
|
|
<code>name</code>, in the file or in the group specified by
|
|
the identifier <code>loc_id</code>.
|
|
The dataset has the datatype and dataspace identified by
|
|
<code>type_id</code> and <code>space_id</code>, respectively.
|
|
The specified datatype and dataspace are the datatype and
|
|
dataspace of the dataset as it will exist in the file,
|
|
which may be different than in application memory.
|
|
Dataset creation properties are specified by the argument
|
|
<code>create_plist_id</code>.
|
|
<p>
|
|
Dataset names within a group are unique:
|
|
<code>H5Dcreate</code> will return an error if a dataset with
|
|
the name specified in <code>name</code> already exists at the
|
|
location specified in <code>loc_id</code>.
|
|
<p>
|
|
<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 a negative value for failure.
|
|
The dataset identifier should eventually be closed by
|
|
calling <code>H5Dclose</code> to release resources it uses.
|
|
<p>
|
|
<strong>Fill values and space allocation:</strong><br>
|
|
The HDF5 library provides flexible means
|
|
of specifying a fill value,
|
|
of specifying when space will be allocated for a dataset, and
|
|
of specifying when fill values will be written to a dataset.
|
|
For further information on these topics, see the document
|
|
<a href="http://hdf.ncsa.uiuc.edu/RFC/Fill_Value/FillValue.html">
|
|
<cite>Fill Value and Dataset Storage Allocation Issues in HDF5</a></cite>
|
|
and the descriptions of the following HDF5 functions in this
|
|
<cite>HDF5 Reference Manual</cite>:
|
|
<table width=80% border="0">
|
|
<tr valign="top" align="left"><td width=10%>
|
|
</td><td width=45%>
|
|
<a href="#Dataset-Fill">H5Dfill</a><br>
|
|
<a href="RM_H5P.html#Property-SetFillValue">H5Pset_fill_value</a><br>
|
|
<a href="RM_H5P.html#Property-GetFillValue">H5Pget_fill_value</a><br>
|
|
<a href="RM_H5P.html#Property-FillValueDefined">H5Pfill_value_defined</a>
|
|
</td><td width=45%>
|
|
<a href="RM_H5P.html#Property-SetFillTime">H5Pset_fill_time</a><br>
|
|
<a href="RM_H5P.html#Property-GetFillTime">H5Pget_fill_time</a><br>
|
|
<a href="RM_H5P.html#Property-SetAllocTime">H5Pset_alloc_time</a><br>
|
|
<a href="RM_H5P.html#Property-GetAllocTime">H5Pget_alloc_time</a>
|
|
</td></tr>
|
|
</table>
|
|
This information is also included in the
|
|
“HDF5 Datasets” chapter of
|
|
the new <cite>HDF5 User's Guide</cite>,
|
|
which is being prepared for release.
|
|
<dt><strong>Parameters:</strong>
|
|
<dl>
|
|
<dt><em>hid_t</em> <code>loc_id</code>
|
|
<dd>IN: Identifier of the file or group
|
|
within which to create the dataset.
|
|
<dt><em>const char *</em> <code>name</code>
|
|
<dd>IN: The name of the dataset to create.
|
|
<dt><em>hid_t</em> <code>type_id</code>
|
|
<dd>IN: Identifier of the datatype to use
|
|
when creating the dataset.
|
|
<dt><em>hid_t</em> <code>space_id</code>
|
|
<dd>IN: Identifier of the dataspace to use
|
|
when creating the dataset.
|
|
<dt><em>hid_t</em> <code>create_plist_id</code>
|
|
<dd>IN: Identifier of the set creation property list.
|
|
</dl>
|
|
<dt><strong>Returns:</strong>
|
|
<dd>Returns a dataset identifier if successful;
|
|
otherwise returns a negative value.
|
|
<dt><strong>Non-C API(s):</strong>
|
|
<dd><a href="fortran/h5d_FORTRAN.html#h5dcreate_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-Open">H5Dopen</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>hid_t </em><code>H5Dopen</code>(<em>hid_t </em><code>loc_id</code>,
|
|
<em>const char *</em><code>name</code>
|
|
)
|
|
<dt><strong>Purpose:</strong>
|
|
<dd>Opens an existing dataset.
|
|
<dt><strong>Description:</strong>
|
|
<dd><code>H5Dopen</code> opens an existing dataset for access in the file
|
|
or group specified in <code>loc_id</code>. <code>name</code> is
|
|
a dataset name and is used to identify the dataset in the file.
|
|
<dt><strong>Parameters:</strong>
|
|
<dl>
|
|
<dt><em>hid_t</em> <code>loc_id</code>
|
|
<dd>IN: Identifier of the file or group
|
|
within which the dataset to be accessed will be found.
|
|
<dt><em>const char *</em> <code>name</code>
|
|
<dd>IN: The name of the dataset to access.
|
|
</dl>
|
|
<dt><strong>Returns:</strong>
|
|
<dd>Returns a dataset identifier if successful;
|
|
otherwise returns a negative value.
|
|
<dt><strong>Non-C API(s):</strong>
|
|
<dd><a href="fortran/h5d_FORTRAN.html#h5dopen_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-GetSpace">H5Dget_space</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>hid_t </em><code>H5Dget_space</code>(<em>hid_t </em><code>dataset_id</code>
|
|
)
|
|
<dt><strong>Purpose:</strong>
|
|
<dd>Returns an identifier for a copy of the dataspace for a dataset.
|
|
<dt><strong>Description:</strong>
|
|
<dd><code>H5Dget_space</code> returns an identifier for a copy of the
|
|
dataspace for a dataset.
|
|
The dataspace identifier should be released with the
|
|
<code>H5Sclose</code> function.
|
|
<dt><strong>Parameters:</strong>
|
|
<dl>
|
|
<dt><em>hid_t</em> <code>dataset_id</code>
|
|
<dd>IN: Identifier of the dataset to query.
|
|
</dl>
|
|
<dt><strong>Returns:</strong>
|
|
<dd>Returns a dataspace identifier 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-GetSpaceStatus">H5Dget_space_status</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>herr_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 allocation 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_status_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>
|
|
)
|
|
<dt><strong>Purpose:</strong>
|
|
<dd>Returns an identifier for a copy of the datatype for a dataset.
|
|
<dt><strong>Description:</strong>
|
|
<dd><code>H5Dget_type</code> returns an identifier for a copy of the
|
|
datatype for a dataset.
|
|
The datatype should be released with the <code>H5Tclose</code> function.
|
|
<p>
|
|
If a dataset has a named datatype, then an identifier to the
|
|
opened datatype is returned.
|
|
Otherwise, the returned datatype is read-only.
|
|
If atomization of the datatype fails, then the datatype is closed.
|
|
<dt><strong>Parameters:</strong>
|
|
<dl>
|
|
<dt><em>hid_t</em> <code>dataset_id</code>
|
|
<dd>IN: Identifier of the dataset to query.
|
|
</dl>
|
|
<dt><strong>Returns:</strong>
|
|
<dd>Returns a datatype identifier if successful;
|
|
otherwise returns a negative value.
|
|
<dt><strong>Non-C API(s):</strong>
|
|
<dd><a href="fortran/h5d_FORTRAN.html#h5dget_type_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-GetCreatePlist">H5Dget_create_plist</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>hid_t </em><code>H5Dget_create_plist</code>(<em>hid_t </em><code>dataset_id</code>
|
|
)
|
|
<dt><strong>Purpose:</strong>
|
|
<dd>Returns an identifier for a copy of the
|
|
dataset creation property list for a dataset.
|
|
<dt><strong>Description:</strong>
|
|
<dd><code>H5Dget_create_plist</code> returns an identifier for a
|
|
copy of the dataset creation property list for a dataset.
|
|
The creation property list identifier should be released with
|
|
the <code>H5Pclose</code> function.
|
|
<dt><strong>Parameters:</strong>
|
|
<dl>
|
|
<dt><em>hid_t</em> <code>dataset_id</code>
|
|
<dd>IN: Identifier of the dataset to query.
|
|
</dl>
|
|
<dt><strong>Returns:</strong>
|
|
<dd>Returns a dataset creation property list identifier if successful;
|
|
otherwise returns a negative value.
|
|
<dt><strong>Non-C API(s):</strong>
|
|
<dd><a href="fortran/h5d_FORTRAN.html#h5dget_create_plist_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-GetOffset">H5Dget_offset</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>haddr_t </em><code>H5Dget_offset</code>(<em>hid_t </em><code>dset_id</code>)
|
|
<dt><strong>Purpose:</strong>
|
|
<dd>Returns dataset address in file.
|
|
<dt><strong>Description:</strong>
|
|
<dd><code>H5Dget_offset</code> returns the address in the file
|
|
of the dataset <code>dset_id</code>.
|
|
That address is expressed as the offset in bytes from
|
|
the beginning of the file.
|
|
<dt><strong>Parameters:</strong>
|
|
<dl>
|
|
<dt><em>hid_t </em><code>dset_id</code>
|
|
<dd>Dataset identifier.
|
|
</dl>
|
|
<dt><strong>Returns:</strong>
|
|
<dd>Returns the offset in bytes;
|
|
otherwise returns <code>HADDR_UNDEF</code>, a negative value.
|
|
<!--
|
|
<dt><strong>Non-C API(s):</strong>
|
|
<dd><a href="fortran/h5d_FORTRAN.html#h5dget_offset_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-GetStorageSize">H5Dget_storage_size</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>hsize_t </em><code>H5Dget_storage_size</code>(<em>hid_t </em><code>dataset_id</code>
|
|
)
|
|
<dt><strong>Purpose:</strong>
|
|
<dd>Returns the amount of storage required for a dataset.
|
|
<dt><strong>Description:</strong>
|
|
<dd><code>H5Dget_storage_size</code> returns the amount of storage
|
|
that is required for the specified dataset, <code>dataset_id</code>.
|
|
For chunked datasets, this is the number of allocated chunks times
|
|
the chunk size.
|
|
The return value may be zero if no data has been stored.
|
|
<dt><strong>Parameters:</strong>
|
|
<dl>
|
|
<dt><em>hid_t</em> <code>dataset_id</code>
|
|
<dd>IN: Identifier of the dataset to query.
|
|
</dl>
|
|
<dt><strong>Returns:</strong>
|
|
<dd>Returns the amount of storage space allocated for the dataset,
|
|
not counting meta data;
|
|
otherwise returns 0 (zero).
|
|
<dt><strong>Non-C API(s):</strong>
|
|
<dd><a href="fortran/h5d_FORTRAN.html#h5dget_storage_size_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-VLGetBuf">H5Dvlen_get_buf_size</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>herr_t </em><code>H5Dvlen_get_buf_size</code>(<em>hid_t </em><code>dataset_id</code>,
|
|
<em>hid_t</em> <code>type_id</code>,
|
|
<em>hid_t</em> <code>space_id</code>,
|
|
<em>hsize_t</em> *<code>size</code>
|
|
)
|
|
<dt><strong>Purpose:</strong>
|
|
<dd>Determines the number of bytes required to store VL data.
|
|
<dt><strong>Description:</strong>
|
|
<dd><code>H5Dvlen_get_buf_size</code> determines the number of bytes
|
|
required to store the VL data from the dataset, using the
|
|
<code>space_id</code> for the selection in the dataset on
|
|
disk and the <code>type_id</code> for the memory representation
|
|
of the VL data in memory.
|
|
<p>
|
|
<code>*size</code> is returned with the number of bytes
|
|
required to store the VL data in memory.
|
|
<dt><strong>Parameters:</strong>
|
|
<dl>
|
|
<dt><em>hid_t</em> <code>dataset_id</code>
|
|
<dd>IN: Identifier of the dataset to query.
|
|
<dt><em>hid_t</em> <code>type_id</code>
|
|
<dd>IN: Datatype identifier.
|
|
<dt><em>hid_t</em> <code>space_id</code>
|
|
<dd>IN: Dataspace identifier.
|
|
<dt><em>hsize_t</em> *<code>size</code>
|
|
<dd>OUT: The size in bytes of the memory buffer required to store the VL data.
|
|
</dl>
|
|
<dt><strong>Returns:</strong>
|
|
<dd>Returns non-negative value if successful;
|
|
otherwise returns a negative value.
|
|
<dt><strong>Non-C API(s):</strong>
|
|
<dd>There is no direct FORTRAN couterpart for the C function
|
|
<code>H5Dvlen_get_buf_size</code>;
|
|
corresponding functionality is provided by the FORTRAN function
|
|
<a href="fortran/h5d_FORTRAN.html#h5dvlen_get_max_len_f"
|
|
target="FortranWin"><code>h5dvlen_get_max_len_f</code></a>.
|
|
<br>
|
|
<a href="fortran/h5d_FORTRAN.html#h5dvlen_get_max_len_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-VLReclaim">H5Dvlen_reclaim</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>herr_t </em><code>H5Dvlen_reclaim</code>(<em>hid_t </em><code>type_id</code>,
|
|
<em>hid_t</em> <code>space_id</code>,
|
|
<em>hid_t</em> <code>plist_id</code>,
|
|
<em>void</em> *<code>buf</code>
|
|
)
|
|
<dt><strong>Purpose:</strong>
|
|
<dd>Reclaims VL datatype memory buffers.
|
|
<dt><strong>Description:</strong>
|
|
<dd><code>H5Dvlen_reclaim</code> reclaims memory buffers created to
|
|
store VL datatypes.
|
|
<p>
|
|
The <code>type_id</code> must be the datatype stored in the buffer.
|
|
The <code>space_id</code> describes the selection for the memory buffer
|
|
to free the VL datatypes within.
|
|
The <code>plist_id</code> is the dataset transfer property list which
|
|
was used for the I/O transfer to create the buffer.
|
|
And <code>buf</code> is the pointer to the buffer to be reclaimed.
|
|
<p>
|
|
The VL structures (<code>hvl_t</code>) in the user's buffer are
|
|
modified to zero out the VL information after the memory has been reclaimed.
|
|
<p>
|
|
If nested VL datatypes were used to create the buffer,
|
|
this routine frees them <em>from the bottom up</em>, releasing all
|
|
the memory without creating memory leaks.
|
|
<dt><strong>Parameters:</strong>
|
|
<dl>
|
|
<dt><em>hid_t</em> <code>type_id</code>
|
|
<dd>IN: Identifier of the datatype.
|
|
<dt><em>hid_t</em> <code>space_id</code>
|
|
<dd>IN: Identifier of the dataspace.
|
|
<dt><em>hid_t</em> <code>plist_id</code>
|
|
<dd>IN: Identifier of the property list used to create the buffer.
|
|
<dt><em>void</em> *<code>buf</code>
|
|
<dd>IN: Pointer to the buffer to be reclaimed.
|
|
</dl>
|
|
<dt><strong>Returns:</strong>
|
|
<dd>Returns non-negative value if successful;
|
|
otherwise returns a negative value.
|
|
<!--
|
|
<dt><strong>Non-C API(s):</strong>
|
|
<dd><a href="fortran/h5d_FORTRAN.html#h5dvlen_reclaim_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-Read">H5Dread</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>herr_t </em><code>H5Dread</code>(<em>hid_t </em><code>dataset_id</code>,
|
|
<em>hid_t</em> <code>mem_type_id</code>,
|
|
<em>hid_t</em> <code>mem_space_id</code>,
|
|
<em>hid_t</em> <code>file_space_id</code>,
|
|
<em>hid_t</em> <code>xfer_plist_id</code>,
|
|
<em>void *</em> <code>buf</code>
|
|
)
|
|
<dt><strong>Purpose:</strong>
|
|
<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 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
|
|
the identifier <code>mem_type_id</code>.
|
|
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> 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>
|
|
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 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=0>
|
|
<tr>
|
|
<th>
|
|
<code>mem_space_id </code>
|
|
</th>
|
|
<th>
|
|
<code>file_space_id </code>
|
|
</th>
|
|
<th>
|
|
Behavior
|
|
</th>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td>
|
|
valid dataspace identifier
|
|
</td>
|
|
<td>
|
|
valid dataspace identifier
|
|
</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 valign="top">
|
|
<td>
|
|
<code>H5S_ALL</code>
|
|
</td>
|
|
<td>
|
|
valid dataspace identifier
|
|
</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.
|
|
The combination of the file dataset's dataspace and the selection from
|
|
<code>file_space_id</code> is used for memory also.
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td>
|
|
valid dataspace identifier
|
|
</td>
|
|
<td>
|
|
<code>H5S_ALL</code>
|
|
</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 valign="top">
|
|
<td>
|
|
<code>H5S_ALL</code>
|
|
</td>
|
|
<td>
|
|
<code>H5S_ALL</code>
|
|
</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 <code>H5S_ALL</code> 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>
|
|
Data is automatically converted from the file datatype
|
|
and dataspace to the memory datatype and dataspace
|
|
at the time of the read. 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
|
|
data conversion, including the range of conversions currently
|
|
supported by the HDF5 libraries.
|
|
<dt><strong>Parameters:</strong>
|
|
<dl>
|
|
<dt><em>hid_t</em> <code>dataset_id</code>
|
|
<dd>IN: Identifier of the dataset read from.
|
|
<dt><em>hid_t</em> <code>mem_type_id</code>
|
|
<dd>IN: Identifier of the memory datatype.
|
|
<dt><em>hid_t</em> <code>mem_space_id</code>
|
|
<dd>IN: Identifier of the memory dataspace.
|
|
<dt><em>hid_t</em> <code>file_space_id</code>
|
|
<dd>IN: Identifier of the dataset's dataspace in the file.
|
|
<dt><em>hid_t</em> <code>xfer_plist_id</code>
|
|
<dd>IN: Identifier of a transfer property list
|
|
for this I/O operation.
|
|
<dt><em>void *</em> <code>buf</code>
|
|
<dd>OUT: Buffer to receive data read from file.
|
|
</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#h5dread_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-Write">H5Dwrite</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>herr_t </em><code>H5Dwrite</code>(<em>hid_t </em><code>dataset_id</code>,
|
|
<em>hid_t</em> <code>mem_type_id</code>,
|
|
<em>hid_t</em> <code>mem_space_id</code>,
|
|
<em>hid_t</em> <code>file_space_id</code>,
|
|
<em>hid_t</em> <code>xfer_plist_id</code>,
|
|
<em>const void *</em> <code>buf</code>
|
|
)
|
|
<dt><strong>Purpose:</strong>
|
|
<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
|
|
application memory buffer <code>buf</code> into the file.
|
|
Data transfer properties are defined by the argument
|
|
<code>xfer_plist_id</code>.
|
|
The memory datatype of the (partial) dataset is identified by
|
|
the identifier <code>mem_type_id</code>.
|
|
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 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>
|
|
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=0>
|
|
<tr>
|
|
<th>
|
|
<code>mem_space_id </code>
|
|
</th>
|
|
<th>
|
|
<code>file_space_id </code>
|
|
</th>
|
|
<th>
|
|
Behavior
|
|
</th>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td>
|
|
valid dataspace identifier
|
|
</td>
|
|
<td>
|
|
valid dataspace identifier
|
|
</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 valign="top">
|
|
<td>
|
|
H5S_ALL
|
|
</td>
|
|
<td>
|
|
valid dataspace identifier
|
|
</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.
|
|
The combination of the file dataset's dataspace and the selection from
|
|
<code>file_space_id</code> is used for memory also.
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td>
|
|
valid dataspace identifier
|
|
</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 valign="top">
|
|
<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 dataset will fail if the HDF5 file was
|
|
not opened with write access permissions.
|
|
<p>
|
|
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
|
|
data conversion, including the range of conversions currently
|
|
supported by the HDF5 libraries.
|
|
<p>
|
|
If the dataset's space allocation time is set to
|
|
<code>H5D_ALLOC_TIME_LATE</code> or <code>H5D_ALLOC_TIME_INCR</code>
|
|
and the space for the dataset has not yet been allocated,
|
|
that space is allocated when the first raw data is written to the
|
|
dataset.
|
|
Unused space in the dataset will be written with fill values at the
|
|
same time if the dataset's fill time is set to
|
|
<code>H5D_FILL_TIME_IFSET</code> or <code>H5D_FILL_TIME_ALLOC</code>.
|
|
(Also see
|
|
<a href="RM_H5P.html#Property-SetFillTime">H5Pset_fill_time</a>
|
|
and
|
|
<a href="RM_H5P.html#Property-SetAllocTime">H5Pset_alloc_time</a>.)
|
|
|
|
<dt><strong>Parameters:</strong>
|
|
<dl>
|
|
<dt><em>hid_t</em> <code>dataset_id</code>
|
|
<dd>IN: Identifier of the dataset to write to.
|
|
<dt><em>hid_t</em> <code>mem_type_id</code>
|
|
<dd>IN: Identifier of the memory datatype.
|
|
<dt><em>hid_t</em> <code>mem_space_id</code>
|
|
<dd>IN: Identifier of the memory dataspace.
|
|
<dt><em>hid_t</em> <code>file_space_id</code>
|
|
<dd>IN: Identifier of the dataset's dataspace in the file.
|
|
<dt><em>hid_t</em> <code>xfer_plist_id</code>
|
|
<dd>IN: Identifier of a transfer property list
|
|
for this I/O operation.
|
|
<dt><em>const void *</em> <code>buf</code>
|
|
<dd>IN: Buffer with data to be written to the file.
|
|
</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#h5dwrite_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-Extend">H5Dextend</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>herr_t </em><code>H5Dextend</code>(<em>hid_t </em><code>dataset_id</code>,
|
|
<em>const hsize_t *</em> <code>size</code>
|
|
)
|
|
<dt><strong>Purpose:</strong>
|
|
<dd>Extends a dataset with unlimited dimension.
|
|
<dt><strong>Description:</strong>
|
|
<dd><code>H5Dextend</code> verifies that the dataset is at least of size
|
|
<code>size</code>.
|
|
The dimensionality of <code>size</code> is the same as that of
|
|
the dataspace of the dataset being changed.
|
|
This function cannot be applied to a dataset with fixed dimensions.
|
|
<p>
|
|
Space on disk is immediately allocated for the new dataset extent
|
|
if the dataset's space allocation time is set to
|
|
<code>H5D_ALLOC_TIME_EARLY</code>.
|
|
Fill values will be written to the dataset if the dataset's fill time
|
|
is set to <code>H5D_FILL_TIME_IFSET</code> or
|
|
<code>H5D_FILL_TIME_ALLOC</code>.
|
|
(Also see
|
|
<a href="RM_H5P.html#Property-SetFillTime">H5Pset_fill_time</a>
|
|
and
|
|
<a href="RM_H5P.html#Property-SetAllocTime">H5Pset_alloc_time</a>.)
|
|
|
|
<dt><strong>Parameters:</strong>
|
|
<dl>
|
|
<dt><em>hid_t</em> <code>dataset_id</code>
|
|
<dd>IN: Identifier of the dataset.
|
|
<dt><em>const hsize_t *</em> <code>size</code>
|
|
<dd>IN: Array containing the new magnitude of each dimension.
|
|
</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#h5dextend_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-Close">H5Dclose</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>herr_t </em><code>H5Dclose</code>(<em>hid_t </em><code>dataset_id</code>
|
|
)
|
|
<dt><strong>Purpose:</strong>
|
|
<dd>Closes the specified dataset.
|
|
<dt><strong>Description:</strong>
|
|
<dd><code>H5Dclose</code> ends access to a dataset specified by
|
|
<code>dataset_id</code> and releases resources used by it.
|
|
Further use of the dataset identifier is illegal in calls to
|
|
the dataset API.
|
|
<dt><strong>Parameters:</strong>
|
|
<dl>
|
|
<dt><em>hid_t</em> <code>dataset_id</code>
|
|
<dd>IN: Identifier of the dataset to close access to.
|
|
</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#h5dclose_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-Iterate">H5Diterate</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>herr_t </em><code>H5Diterate</code>(
|
|
<em>void *</em><code>buf</code>,
|
|
<em>hid_t </em><code>type_id</code>,
|
|
<em>hid_t </em><code>space_id</code>,
|
|
<em>H5D_operator_t </em><code>operator</code>,
|
|
<em>void *</em><code>operator_data</code>
|
|
)
|
|
<dt><strong>Purpose:</strong>
|
|
<dd>Iterates over all selected elements in a dataspace.
|
|
<dt><strong>Description:</strong>
|
|
<dd><code>H5Diterate</code> iterates over all the elements selected
|
|
in a memory buffer. The callback function is called once for each
|
|
element selected in the dataspace.
|
|
<p>
|
|
The selection in the dataspace is modified so that any elements
|
|
already iterated over are removed from the selection if the
|
|
iteration is interrupted (by the <code>H5D_operator_t</code>
|
|
function returning non-zero) before the iteration is complete;
|
|
the iteration may then be re-started by the user where it left off.
|
|
|
|
<dt><strong>Parameters:</strong>
|
|
<dl>
|
|
<dt><em>void *</em><code>buf</code>
|
|
<dd>IN/OUT: Pointer to the buffer in memory containing the
|
|
elements to iterate over.
|
|
<dt><em>hid_t </em><code>type_id</code>
|
|
<dd>IN: Datatype identifier for the elements stored in
|
|
<code>buf</code>.
|
|
<dt><em>hid_t </em><code>space_id</code>
|
|
<dd>IN: Dataspace identifier for <code>buf</code>.
|
|
Also contains the selection to iterate over.
|
|
<dt><em>H5D_operator_t </em><code>operator</code>
|
|
<dd>IN: Function pointer to the routine to be called
|
|
for each element in <code>buf</code> iterated over.
|
|
<dt><em>void *</em><code>operator_data</code>
|
|
<dd>IN/OUT: Pointer to any user-defined data associated
|
|
with the operation.
|
|
</dl>
|
|
<dt><strong>Returns:</strong>
|
|
<dd>Returns the return value of the last operator if it was non-zero,
|
|
or zero if all elements have been processed.
|
|
Otherwise returns a negative value.
|
|
<!--
|
|
<dt><strong>Non-C API(s):</strong>
|
|
<dd><a href="fortran/h5d_FORTRAN.html#h5diterate_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-Fill">H5Dfill</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>herr_t </em><code>H5Dfill</code>(
|
|
<em>const void *</em><code>fill</code>,
|
|
<em>hid_t </em><code>fill_type_id</code>,
|
|
<em>void *</em><code>buf</code>,
|
|
<em>hid_t </em><code>buf_type_id</code>,
|
|
<em>hid_t </em><code>space_id</code>
|
|
)
|
|
<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
|
|
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 allocated 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.
|
|
Other related functions include
|
|
<a href="RM_H5P.html#Property-GetFillValue">H5Pget_fill_value</a>,
|
|
<a href="RM_H5P.html#Property-FillValueDefined">H5Pfill_value_defined</a>,
|
|
<a href="RM_H5P.html#Property-SetFillTime">H5Pset_fill_time</a>,
|
|
<a href="RM_H5P.html#Property-GetFillTime">H5Pget_fill_time</a>,
|
|
and
|
|
<a href="#Dataset-Create">H5Dcreate</a>.
|
|
<dt><strong>Parameters:</strong>
|
|
<dl>
|
|
<dt><em>const void *</em><code>fill</code>
|
|
<dd>IN: Pointer to the fill value to be used.
|
|
<dt><em>hid_t </em><code>fill_type_id</code>
|
|
<dd>IN: Fill value datatype identifier.
|
|
<dt><em>void *</em><code>buf</code>
|
|
<dd>IN/OUT: Pointer to the memory buffer containing the
|
|
selection to be filled.
|
|
<dt><em>hid_t </em><code>buf_type_id</code>
|
|
<dd>IN: Datatype of dataspace elements to be filled.
|
|
<dt><em>hid_t </em><code>space_id</code>
|
|
<dd>IN: Dataspace describing memory buffer and
|
|
containing the selection to be filled.
|
|
</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#h5dfill_f"
|
|
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
|
|
<!--
|
|
<img src="Graphics/Java.gif">
|
|
<img src="Graphics/C++.gif">
|
|
-->
|
|
</dl>
|
|
|
|
|
|
<!-- #BeginLibraryItem "/ed_libs/NavBar_RM.lbi" --><hr>
|
|
<center>
|
|
<table border=0 width=98%>
|
|
<tr><td valign=top align=left>
|
|
<a href="index.html">HDF5 documents and links</a> <br>
|
|
<a href="H5.intro.html">Introduction to HDF5</a> <br>
|
|
<a href="http://hdf.ncsa.uiuc.edu/HDF5/doc/UG/index.html">HDF5 User Guide</a> <br>
|
|
<!--
|
|
<a href="Glossary.html">Glossary</a><br>
|
|
-->
|
|
</td>
|
|
<td valign=top align=right>
|
|
And in this document, the
|
|
<a href="RM_H5Front.html">HDF5 Reference Manual</a>
|
|
<br>
|
|
<a href="RM_H5.html">H5</a>
|
|
<a href="RM_H5A.html">H5A</a>
|
|
<a href="RM_H5D.html">H5D</a>
|
|
<a href="RM_H5E.html">H5E</a>
|
|
<a href="RM_H5F.html">H5F</a>
|
|
<a href="RM_H5G.html">H5G</a>
|
|
<a href="RM_H5I.html">H5I</a>
|
|
<a href="RM_H5P.html">H5P</a>
|
|
<br>
|
|
<a href="RM_H5R.html">H5R</a>
|
|
<a href="RM_H5S.html">H5S</a>
|
|
<a href="RM_H5T.html">H5T</a>
|
|
<a href="RM_H5Z.html">H5Z</a>
|
|
<a href="Tools.html">Tools</a>
|
|
<a href="PredefDTypes.html">Datatypes</a>
|
|
</td></tr>
|
|
</table>
|
|
</center>
|
|
<hr>
|
|
<!-- #EndLibraryItem --><!-- #BeginLibraryItem "/ed_libs/Footer.lbi" --><address>
|
|
<a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a>
|
|
<br>
|
|
Describes HDF5 Release 1.6.0, July 2003
|
|
</address><!-- #EndLibraryItem -->
|
|
|
|
Last modified: 25 June 2003
|
|
|
|
</body>
|
|
</html>
|