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
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
|
<!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.10.0"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>HDF5: Reading From or Writing To a Subset of 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>
<script type="text/javascript" src="cookie.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:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt MIT */
$(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.2908dd1</span>
</div>
<div id="projectbrief">API Reference</div>
</td>
<td> <div id="MSearchBox" class="MSearchBoxInactive">
<span class="left">
<span id="MSearchSelect" onmouseover="return searchBox.OnSearchSelectShow()" onmouseout="return searchBox.OnSearchSelectHide()"> </span>
<input type="text" id="MSearchField" value="" placeholder="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.10.0 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt MIT */
var searchBox = new SearchBox("searchBox", "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:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt MIT */
$(function(){initNavTree('_l_b_dset_sub_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">
<div id="MSearchResults">
<div class="SRPage">
<div id="SRIndex">
<div id="SRResults"></div>
<div class="SRStatus" id="Loading">Loading...</div>
<div class="SRStatus" id="Searching">Searching...</div>
<div class="SRStatus" id="NoMatches">No Matches</div>
</div>
</div>
</div>
</div>
<div><div class="header">
<div class="headertitle"><div class="title">Reading From or Writing To a Subset of 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="secLBDsetSubRW"></a>
Dataset Subsets</h1>
<p>There are two ways that you can select a subset in an HDF5 dataset and read or write to it: </p><ul>
<li>
<b>Hyperslab Selection</b>: The <a class="el" href="group___h5_s.html#ga6adfdf1b95dc108a65bf66e97d38536d" title="Selects a hyperslab region to add to the current selected region.">H5Sselect_hyperslab</a> call selects a logically contiguous collection of points in a dataspace, or a regular pattern of points or blocks in a dataspace. </li>
<li>
<b>Element Selection</b>: The <a class="el" href="group___h5_s.html#ga2f4407dd73d0ec37e5d9e80e4382483d" title="Selects array elements to be included in the selection for a dataspace.">H5Sselect_elements</a> call selects elements in an array. </li>
</ul>
<p>HDF5 allows you to read from or write to a portion or subset of a dataset by: </p><ul>
<li>Selecting a Subset of the Dataset's Dataspace, </li>
<li>Selecting a Memory Dataspace, </li>
<li>Reading From or Writing to a Dataset Subset.</li>
</ul>
<h1><a class="anchor" id="secLBDsetSubRWSel"></a>
Selecting a Subset of the Dataset's Dataspace</h1>
<p>First you must obtain the dataspace of a dataset in a file by calling <a class="el" href="group___h5_d.html#gad42a46be153d895d8c28a11ebf5a0d0a" title="Returns an identifier for a copy of the dataspace for a dataset.">H5Dget_space</a>.</p>
<p>Then select a subset of that dataspace by calling <a class="el" href="group___h5_s.html#ga6adfdf1b95dc108a65bf66e97d38536d" title="Selects a hyperslab region to add to the current selected region.">H5Sselect_hyperslab</a>. The <em>offset</em>, <em>count</em>, <em>stride</em> and <em>block</em> parameters of this API define the shape and size of the selection. They must be arrays with the same number of dimensions as the rank of the dataset's dataspace. These arrays <b>ALL</b> work together to define a selection. A change to one of these arrays can affect the others. </p><ul>
<li><em>offset:</em> An array that specifies the offset of the starting element of the specified hyperslab. </li>
<li><em>count:</em> An array that determines how many blocks to select from the dataspace in each dimension. If the block size for a dimension is one then the count is the number of elements along that dimension. </li>
<li><em>stride:</em> An array that allows you to sample elements along a dimension. For example, a stride of one (or NULL) will select every element along a dimension, a stride of two will select every other element, and a stride of three will select an element after every two elements. </li>
<li><em>block:</em> An array that determines the size of the element block selected from a dataspace. If the block size is one or NULL then the block size is a single element in that dimension.</li>
</ul>
<h1><a class="anchor" id="secLBDsetSubRWMem"></a>
Selecting a Memory Dataspace</h1>
<p>You must select a memory dataspace in addition to a file dataspace before you can read a subset from or write a subset to a dataset. A memory dataspace can be specified by calling <a class="el" href="group___h5_s.html#ga8e35eea5738b4805856eac7d595254ae" title="Creates a new simple dataspace and opens it for access.">H5Screate_simple</a>.</p>
<p>The memory dataspace passed to the read or write call must contain the same number of elements as the file dataspace. The number of elements in a dataspace selection can be determined with the <a class="el" href="group___h5_s.html#ga1a44dde97206f40f366f99d9c39b6046" title="Determines the number of elements in a dataspace selection.">H5Sget_select_npoints</a> API.</p>
<h1><a class="anchor" id="secLBDsetSubRWSub"></a>
Reading From or Writing To a Dataset Subset</h1>
<p>To read from or write to a dataset subset, 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. The memory and file dataspace identifiers from the selections that were made are passed into the read or write call. For example (C): </p><div class="fragment"><div class="line">status = <a class="code hl_function" href="group___h5_d.html#ga98f44998b67587662af8b0d8a0a75906">H5Dwrite</a> (.., .., memspace_id, dataspace_id, .., ..);</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 --><h1><a class="anchor" id="secLBDsetSubRWProg"></a>
Programming Example</h1>
<h2><a class="anchor" id="subsecLBDsetSubRWProgDesc"></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 creates an 8 x 10 integer dataset in an HDF5 file. It then selects and writes to a 3 x 4 subset of the dataset created with the dimensions offset by 1 x 2. (If using Fortran, the dimensions will be swapped. The dataset will be 10 x 8, the subset will be 4 x 3, and the offset will be 2 x 1.)</p>
<p>PLEASE NOTE that the examples and images below were created using C.</p>
<p>The following image shows the dataset that gets written originally, and the subset of data that gets modified afterwards. Dimension 0 is vertical and Dimension 1 is horizontal as shown below: </p><table class="doxtable">
<tr>
<td><div class="image">
<img src="LBDsetSubRWProg.png" alt=""/>
</div>
</td></tr>
</table>
<p>The subset on the right above is created using these values for offset, count stride, and block: </p><div class="fragment"><div class="line">offset = {1, 2}</div>
<div class="line"> </div>
<div class="line">count = {3, 4}</div>
<div class="line"> </div>
<div class="line">stride = {1, 1}</div>
<div class="line"> </div>
<div class="line">block = {1, 1}</div>
</div><!-- fragment --><h2><a class="anchor" id="subsecLBDsetSubRWProgExper"></a>
Experiments with Different Selections</h2>
<p>Following are examples of changes that can be made to the example code provided to better understand how to make selections.</p>
<h3><a class="anchor" id="subsubsecLBDsetSubRWProgExperOne"></a>
Example 1</h3>
<p>By default the example code will select and write to a 3 x 4 subset. You can modify the count parameter in the example code to select a different subset, by changing the value of DIM0_SUB (C, C++) / dim0_sub (Fortran) near the top. Change its value to 7 to create a 7 x 4 subset: </p><table class="doxtable">
<tr>
<td><div class="image">
<img src="imgLBDsetSubRW11.png" alt=""/>
</div>
</td></tr>
</table>
<p>If you were to change the subset to 8 x 4, the selection would be beyond the extent of the dimension: </p><table class="doxtable">
<tr>
<td><div class="image">
<img src="imgLBDsetSubRW12.png" alt=""/>
</div>
</td></tr>
</table>
<p>The write will fail with the error: "<strong>file selection+offset not within extent</strong>"</p>
<h3><a class="anchor" id="subsubsecLBDsetSubRWProgExperTwo"></a>
Example 2</h3>
<p>In the example code provided, the memory and file dataspaces passed to the H5Dwrite call have the same size, 3 x 4 (DIM0_SUB x DIM1_SUB). Change the size of the memory dataspace to be 4 x 4 so that they do not match, and then compile: </p><div class="fragment"><div class="line">dimsm[0] = DIM0_SUB + 1;</div>
<div class="line">dimsm[1] = DIM1_SUB;</div>
<div class="line">memspace_id = <a class="code hl_function" href="group___h5_s.html#ga8e35eea5738b4805856eac7d595254ae">H5Screate_simple</a> (RANK, dimsm, NULL);</div>
<div class="ttc" id="agroup___h5_s_html_ga8e35eea5738b4805856eac7d595254ae"><div class="ttname"><a href="group___h5_s.html#ga8e35eea5738b4805856eac7d595254ae">H5Screate_simple</a></div><div class="ttdeci">hid_t H5Screate_simple(int rank, const hsize_t dims[], const hsize_t maxdims[])</div><div class="ttdoc">Creates a new simple dataspace and opens it for access.</div></div>
</div><!-- fragment --><p> The code will fail with the error: "<strong>src and dest data spaces have different sizes</strong>"</p>
<p>How many elements are in the memory and file dataspaces that were specified above? Add these lines: </p><div class="fragment"><div class="line"><a class="code hl_typedef" href="_h5public_8h.html#a7d9d4293176a8d7535ea6d4038235280">hssize_t</a> size;</div>
<div class="line"> </div>
<div class="line"><span class="comment">/* Just before H5Dwrite call the following */</span></div>
<div class="line">size = <a class="code hl_function" href="group___h5_s.html#ga1a44dde97206f40f366f99d9c39b6046">H5Sget_select_npoints</a> (memspace_id);</div>
<div class="line">printf (<span class="stringliteral">"\nmemspace_id size: %i\n"</span>, size);</div>
<div class="line">size = <a class="code hl_function" href="group___h5_s.html#ga1a44dde97206f40f366f99d9c39b6046">H5Sget_select_npoints</a> (dataspace_id);</div>
<div class="line">printf (<span class="stringliteral">"dataspace_id size: %i\n"</span>, size);</div>
<div class="ttc" id="a_h5public_8h_html_a7d9d4293176a8d7535ea6d4038235280"><div class="ttname"><a href="_h5public_8h.html#a7d9d4293176a8d7535ea6d4038235280">hssize_t</a></div><div class="ttdeci">int64_t hssize_t</div><div class="ttdef"><b>Definition</b> H5public.h:309</div></div>
<div class="ttc" id="agroup___h5_s_html_ga1a44dde97206f40f366f99d9c39b6046"><div class="ttname"><a href="group___h5_s.html#ga1a44dde97206f40f366f99d9c39b6046">H5Sget_select_npoints</a></div><div class="ttdeci">hssize_t H5Sget_select_npoints(hid_t spaceid)</div><div class="ttdoc">Determines the number of elements in a dataspace selection.</div></div>
</div><!-- fragment --><p>You should see these lines followed by the error: </p><div class="fragment"><div class="line">memspace_id size: 16</div>
<div class="line">dataspace_id size: 12</div>
</div><!-- fragment --><h3><a class="anchor" id="subsubsecLBDsetSubRWProgExperThree"></a>
Example 3</h3>
<p>This example shows the selection that occurs if changing the values of the <em>offset</em>, <em>count</em>, <em>stride</em> and <em>block</em> parameters in the example code.</p>
<p>This will select two blocks. The <em>count</em> array specifies the number of blocks. The <em>block</em> array specifies the size of a block. The <em>stride</em> must be modified to accommodate the block <em>size</em>. </p><table class="doxtable">
<tr>
<td><div class="image">
<img src="imgLBDsetSubRW31.png" alt=""/>
</div>
</td></tr>
</table>
<p>Now try modifying the count as shown below. The write will fail because the selection goes beyond the extent of the dimension: </p><table class="doxtable">
<tr>
<td><div class="image">
<img src="imgLBDsetSubRW32.png" alt=""/>
</div>
</td></tr>
</table>
<p>If the offset were 1x1 (instead of 1x2), then the selection can be made: </p><table class="doxtable">
<tr>
<td><div class="image">
<img src="imgLBDsetSubRW33.png" alt=""/>
</div>
</td></tr>
</table>
<p>The selections above were tested with the <a href="https://support.hdfgroup.org/ftp/HDF5/examples/howto/subset/h5_subsetbk.c">h5_subsetbk.c</a> example code. The memory dataspace was defined as one-dimensional.</p>
<h2><a class="anchor" id="subsecLBDsetSubRWProgRem"></a>
Remarks</h2>
<ul>
<li>In addition to <a class="el" href="group___h5_s.html#ga6adfdf1b95dc108a65bf66e97d38536d" title="Selects a hyperslab region to add to the current selected region.">H5Sselect_hyperslab</a>, this example introduces the <a class="el" href="group___h5_d.html#gad42a46be153d895d8c28a11ebf5a0d0a" title="Returns an identifier for a copy of the dataspace for a dataset.">H5Dget_space</a> call to obtain the dataspace of a dataset. </li>
<li>If using the default values for the stride and block parameters of <a class="el" href="group___h5_s.html#ga6adfdf1b95dc108a65bf66e97d38536d" title="Selects a hyperslab region to add to the current selected region.">H5Sselect_hyperslab</a>, then, for C you can specify NULL for these parameters, rather than passing in an array for each, and for Fortran 90 you can omit these parameters.</li>
</ul>
<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.10.0 </li>
</ul>
</div>
</body>
</html>
|
