1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.9.1"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>HDF5: Reading From and Writing To a Dataset</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */
$(document).ready(function() { init_search(); });
/* @license-end */
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="hdf5doxy.css" rel="stylesheet" type="text/css">
<!-- <link href="hdf5doxy.css" rel="stylesheet" type="text/css"/>
-->
<script type="text/javascript" src="hdf5_navtree_hacks.js"></script>
</head>
<body>
<div style="background:#FFDDDD;font-size:120%;text-align:center;margin:0;padding:5px">Please, help us to better serve our user community by answering the following short survey: <a href="https://www.hdfgroup.org/website-survey/">https://www.hdfgroup.org/website-survey/</a></div>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td id="projectlogo"><img alt="Logo" src="HDFG-logo.png"/></td>
<td id="projectalign" style="padding-left: 0.5em;">
<div id="projectname"><a href="https://www.hdfgroup.org">HDF5</a>
 <span id="projectnumber">1.15.0.f39b228</span>
</div>
<div id="projectbrief">API Reference</div>
</td>
<td> <div id="MSearchBox" class="MSearchBoxInactive">
<span class="left">
<img id="MSearchSelect" src="search/mag_sel.svg"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
alt=""/>
<input type="text" id="MSearchField" value="Search" accesskey="S"
onfocus="searchBox.OnSearchFieldFocus(true)"
onblur="searchBox.OnSearchFieldFocus(false)"
onkeyup="searchBox.OnSearchFieldChange(event)"/>
</span><span class="right">
<a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.svg" alt=""/></a>
</span>
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.9.1 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */
var searchBox = new SearchBox("searchBox", "search",false,'Search','.html');
/* @license-end */
</script>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
<div id="nav-tree">
<div id="nav-tree-contents">
<div id="nav-sync" class="sync"></div>
</div>
</div>
<div id="splitbar" style="-moz-user-select:none;"
class="ui-resizable-handle">
</div>
</div>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */
$(document).ready(function(){initNavTree('_l_b_dset_r_w.html',''); initResizable(); });
/* @license-end */
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>
<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0"
name="MSearchResults" id="MSearchResults">
</iframe>
</div>
<div class="PageDoc"><div class="header">
<div class="headertitle">
<div class="title">Reading From and Writing To a Dataset </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>Navigate back: <a class="el" href="index.html">Main</a> / <a class="el" href="_getting_started.html">Getting Started with HDF5</a> / <a class="el" href="_learn_basics.html">Learning the Basics</a> </p><hr />
<h1><a class="anchor" id="secLBDsetRW"></a>
Dataset I/O Operation</h1>
<p>During a dataset I/O operation, the library transfers raw data between memory and the file. The data in memory can have a datatype different from that of the file and can also be of a different size (i.e., the data in memory is a subset of the dataset elements, or vice versa). Therefore, to perform read or write operations, the application program must specify: </p><ul>
<li>The dataset </li>
<li>The dataset's datatype in memory </li>
<li>The dataset's dataspace in memory </li>
<li>The dataset's dataspace in the file </li>
<li>The dataset transfer property list<br />
<ul>
<li>
(The dataset transfer property list controls various aspects of the I/O operations, such as the number of processes participating in a collective I/O request or hints to the library to control caching of raw data. In this tutorial, we use the default dataset transfer property list.) </li>
</ul>
</li>
<li>The data buffer</li>
</ul>
<p>The steps to read from or write to a dataset are as follows: </p><ol>
<li>
Obtain the dataset identifier. </li>
<li>
Specify the memory datatype. </li>
<li>
Specify the memory dataspace. </li>
<li>
Specify the file dataspace. </li>
<li>
Specify the transfer properties. </li>
<li>
Perform the desired operation on the dataset. </li>
<li>
Close the dataset. </li>
<li>
Close the dataspace, datatype, and property list if necessary. </li>
</ol>
<p>To read from or write to a dataset, the <a class="el" href="group___h5_d.html#ga8287d5a7be7b8e55ffeff68f7d26811c" title="Reads raw data from a dataset into a provided buffer.">H5Dread</a> and <a class="el" href="group___h5_d.html#ga98f44998b67587662af8b0d8a0a75906" title="Writes raw data from a buffer to a dataset.">H5Dwrite</a> routines are used.</p>
<p><em>C</em> </p><div class="fragment"><div class="line">status = <a class="code" href="group___h5_d.html#ga8287d5a7be7b8e55ffeff68f7d26811c">H5Dread</a> (set_id, mem_type_id, mem_space_id, file_space_id, xfer_prp, buf );</div>
<div class="line">status = <a class="code" href="group___h5_d.html#ga98f44998b67587662af8b0d8a0a75906">H5Dwrite</a> (set_id, mem_type_id, mem_space_id, file_space_id, xfer_prp, buf);</div>
<div class="ttc" id="agroup___h5_d_html_ga8287d5a7be7b8e55ffeff68f7d26811c"><div class="ttname"><a href="group___h5_d.html#ga8287d5a7be7b8e55ffeff68f7d26811c">H5Dread</a></div><div class="ttdeci">herr_t H5Dread(hid_t dset_id, hid_t mem_type_id, hid_t mem_space_id, hid_t file_space_id, hid_t dxpl_id, void *buf)</div><div class="ttdoc">Reads raw data from a dataset into a provided buffer.</div></div>
<div class="ttc" id="agroup___h5_d_html_ga98f44998b67587662af8b0d8a0a75906"><div class="ttname"><a href="group___h5_d.html#ga98f44998b67587662af8b0d8a0a75906">H5Dwrite</a></div><div class="ttdeci">herr_t H5Dwrite(hid_t dset_id, hid_t mem_type_id, hid_t mem_space_id, hid_t file_space_id, hid_t dxpl_id, const void *buf)</div><div class="ttdoc">Writes raw data from a buffer to a dataset.</div></div>
</div><!-- fragment --><p><em>Fortran</em> </p><div class="fragment"><div class="line">CALL <a class="code" href="group___f_h5_d.html#ga652d31ef398eeed35e32c3de0de273d0">h5dread_f</a>(dset_id, mem_type_id, buf, dims, error, &</div>
<div class="line"> mem_space_id=mspace_id, file_space_id=fspace_id, &</div>
<div class="line"> xfer_prp=xfer_plist_id)</div>
<div class="line"> or</div>
<div class="line">CALL <a class="code" href="group___f_h5_d.html#ga652d31ef398eeed35e32c3de0de273d0">h5dread_f</a>(dset_id, mem_type_id, buf, dims, error)</div>
<div class="line"> </div>
<div class="line"> </div>
<div class="line">CALL <a class="code" href="group___f_h5_d.html#ga474d18ed38c193fd1eb36b1b73f65ea8">h5dwrite_f</a>(dset_id, mem_type_id, buf, dims, error, &</div>
<div class="line"> mem_space_id=mspace_id, file_space_id=fspace_id, &</div>
<div class="line"> xfer_prp=xfer_plist_id)</div>
<div class="line"> or</div>
<div class="line">CALL <a class="code" href="group___f_h5_d.html#ga474d18ed38c193fd1eb36b1b73f65ea8">h5dwrite_f</a>(dset_id, mem_type_id, buf, dims, error)</div>
<div class="ttc" id="agroup___f_h5_d_html_ga474d18ed38c193fd1eb36b1b73f65ea8"><div class="ttname"><a href="group___f_h5_d.html#ga474d18ed38c193fd1eb36b1b73f65ea8">h5d::h5dwrite_f</a></div><div class="ttdeci">subroutine h5dwrite_f(dset_id, mem_type_id, buf, hdferr, mem_space_id, file_space_id, xfer_prp)</div><div class="ttdoc">Writes raw data from a buffer to a dataset.</div><div class="ttdef"><b>Definition:</b> H5Dff.F90:1633</div></div>
<div class="ttc" id="agroup___f_h5_d_html_ga652d31ef398eeed35e32c3de0de273d0"><div class="ttname"><a href="group___f_h5_d.html#ga652d31ef398eeed35e32c3de0de273d0">h5d::h5dread_f</a></div><div class="ttdeci">subroutine h5dread_f(dset_id, mem_type_id, buf, hdferr, mem_space_id, file_space_id, xfer_prp)</div><div class="ttdoc">Reads raw data from a dataset into a buffer (Passes Pointer).</div><div class="ttdef"><b>Definition:</b> H5Dff.F90:1661</div></div>
</div><!-- fragment --><h1><a class="anchor" id="secLBDsetRWHL"></a>
High Level APIs</h1>
<p>The High Level <a class="el" href="group___h5_l_t.html">HDF5 Lite APIs (H5LT,H5LD)</a> include functions that simplify and condense the steps for creating and reading datasets. Please be sure to review them, in addition to this tutorial.</p>
<h1><a class="anchor" id="secLBDsetRWEx"></a>
Programming Example</h1>
<h2><a class="anchor" id="secLBDsetRWExDesc"></a>
Description</h2>
<p>See <a class="el" href="_l_b_examples.html">Examples from Learning the Basics</a> for the examples used in the <a class="el" href="_learn_basics.html">Learning the Basics</a> tutorial.</p>
<p>The example shows how to read and write an existing dataset. It opens the file created in the previous example, obtains the dataset identifier for the dataset <code style="background-color:whitesmoke;">/dset</code>, writes the dataset to the file, then reads the dataset back. It then closes the dataset and file.</p>
<p>Note that <a class="el" href="_h5_spublic_8h.html#a5f96eeee84b987f18470737f85af0484">H5S_ALL</a> is passed in for both the memory and file dataspace parameters in the read and write calls. This indicates that the entire dataspace of the dataset will be read or written to. <a class="el" href="_h5_spublic_8h.html#a5f96eeee84b987f18470737f85af0484">H5S_ALL</a> by itself does not necessarily have this meaning. See the <a class="el" href="_r_m.html">HDF5 Reference Manual</a> entry for <a class="el" href="group___h5_d.html#ga8287d5a7be7b8e55ffeff68f7d26811c" title="Reads raw data from a dataset into a provided buffer.">H5Dread</a> or <a class="el" href="group___h5_d.html#ga98f44998b67587662af8b0d8a0a75906" title="Writes raw data from a buffer to a dataset.">H5Dwrite</a> for more information on using <a class="el" href="_h5_spublic_8h.html#a5f96eeee84b987f18470737f85af0484">H5S_ALL</a>.</p>
<p>For details on compiling an HDF5 application: [ <a class="el" href="_l_b_compiling.html">Compiling HDF5 Applications</a> ]</p>
<h2><a class="anchor" id="secLBDsetRWExRem"></a>
Remarks</h2>
<p><a class="el" href="group___h5_f.html#gaa3f4f877b9bb591f3880423ed2bf44bc" title="Opens an existing HDF5 file.">H5Fopen</a> opens an existing file and returns a file identifier.</p>
<p><a class="el" href="_h5version_8h.html#a7dba2e5b2045f31c0932123ffb54f7a3">H5Dopen</a> opens an existing dataset with the specified name and location.</p>
<p><a class="el" href="group___h5_d.html#ga98f44998b67587662af8b0d8a0a75906" title="Writes raw data from a buffer to a dataset.">H5Dwrite</a> writes raw data from an application buffer to the specified dataset, converting from the datatype and dataspace of the dataset in memory to the datatype and dataspace of the dataset in the file. Specifying <a class="el" href="_h5_spublic_8h.html#a5f96eeee84b987f18470737f85af0484">H5S_ALL</a> for both the memory and file dataspaces indicates that the entire dataspace of the dataset is to be written to. <a class="el" href="_h5_spublic_8h.html#a5f96eeee84b987f18470737f85af0484">H5S_ALL</a> by itself does not necessarily have this meaning. See the <a class="el" href="_r_m.html">HDF5 Reference Manual</a> entry for <a class="el" href="group___h5_d.html#ga98f44998b67587662af8b0d8a0a75906" title="Writes raw data from a buffer to a dataset.">H5Dwrite</a> for more information on using <a class="el" href="_h5_spublic_8h.html#a5f96eeee84b987f18470737f85af0484">H5S_ALL</a>.</p>
<p><a class="el" href="group___h5_d.html#ga8287d5a7be7b8e55ffeff68f7d26811c" title="Reads raw data from a dataset into a provided buffer.">H5Dread</a> reads raw data from the specified dataset to an application buffer, converting from the file datatype and dataspace to the memory datatype and dataspace. Specifying <a class="el" href="_h5_spublic_8h.html#a5f96eeee84b987f18470737f85af0484">H5S_ALL</a> for both the memory and file dataspaces indicates that the entire dataspace of the dataset is to be read. <a class="el" href="_h5_spublic_8h.html#a5f96eeee84b987f18470737f85af0484">H5S_ALL</a> by itself does not necessarily have this meaning. See the <a class="el" href="_r_m.html">HDF5 Reference Manual</a> entry for <a class="el" href="group___h5_d.html#ga8287d5a7be7b8e55ffeff68f7d26811c" title="Reads raw data from a dataset into a provided buffer.">H5Dread</a> for more information on using <a class="el" href="_h5_spublic_8h.html#a5f96eeee84b987f18470737f85af0484">H5S_ALL</a>.</p>
<h2><a class="anchor" id="secLBDsetRWExCont"></a>
File Contents</h2>
<p>Shown below is the contents of dset.h5 (created by the C program).</p>
<p><em>dset.h5 in DDL</em> </p><div class="fragment"><div class="line">HDF5 <span class="stringliteral">"dset.h5"</span> {</div>
<div class="line">GROUP <span class="stringliteral">"/"</span> {</div>
<div class="line"> DATASET <span class="stringliteral">"dset"</span> {</div>
<div class="line"> DATATYPE { <a class="code" href="group___p_d_t_s_t_d.html#ga37e8a6be7ee64587c2a282b965019bb8">H5T_STD_I32BE</a> }</div>
<div class="line"> DATASPACE { SIMPLE ( 4, 6 ) / ( 4, 6 ) }</div>
<div class="line"> DATA {</div>
<div class="line"> 1, 2, 3, 4, 5, 6,</div>
<div class="line"> 7, 8, 9, 10, 11, 12,</div>
<div class="line"> 13, 14, 15, 16, 17, 18,</div>
<div class="line"> 19, 20, 21, 22, 23, 24</div>
<div class="line"> }</div>
<div class="line"> }</div>
<div class="line">}</div>
<div class="line">}</div>
<div class="ttc" id="agroup___p_d_t_s_t_d_html_ga37e8a6be7ee64587c2a282b965019bb8"><div class="ttname"><a href="group___p_d_t_s_t_d.html#ga37e8a6be7ee64587c2a282b965019bb8">H5T_STD_I32BE</a></div><div class="ttdeci">#define H5T_STD_I32BE</div><div class="ttdef"><b>Definition:</b> H5Tpublic.h:305</div></div>
</div><!-- fragment --><p>Shown below is the contents of dsetf.h5 (created by the FORTRAN program).</p>
<p><em>dsetf.h5 in DDL</em> </p><div class="fragment"><div class="line">HDF5 <span class="stringliteral">"dsetf.h5"</span> {</div>
<div class="line">GROUP <span class="stringliteral">"/"</span> {</div>
<div class="line"> DATASET <span class="stringliteral">"dset"</span> {</div>
<div class="line"> DATATYPE { <a class="code" href="group___p_d_t_s_t_d.html#ga37e8a6be7ee64587c2a282b965019bb8">H5T_STD_I32BE</a> }</div>
<div class="line"> DATASPACE { SIMPLE ( 6, 4 ) / ( 6, 4 ) }</div>
<div class="line"> DATA {</div>
<div class="line"> 1, 7, 13, 19,</div>
<div class="line"> 2, 8, 14, 20,</div>
<div class="line"> 3, 9, 15, 21,</div>
<div class="line"> 4, 10, 16, 22,</div>
<div class="line"> 5, 11, 17, 23,</div>
<div class="line"> 6, 12, 18, 24</div>
<div class="line"> }</div>
<div class="line"> }</div>
<div class="line">}</div>
<div class="line">}</div>
</div><!-- fragment --><hr />
<p> Navigate back: <a class="el" href="index.html">Main</a> / <a class="el" href="_getting_started.html">Getting Started with HDF5</a> / <a class="el" href="_learn_basics.html">Learning the Basics</a> </p>
</div></div><!-- contents -->
</div><!-- PageDoc -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
<ul>
<li class="footer">Generated by
<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.9.1 </li>
</ul>
</div>
</body>
</html>
|
