diff options
| author | byrnHDF <byrnHDF@users.noreply.github.com> | 2023-11-16 13:49:28 (GMT) |
|---|---|---|
| committer | byrnHDF <byrnHDF@users.noreply.github.com> | 2023-11-16 13:49:28 (GMT) |
| commit | 4f20d880c97be1249f8d89ced95f72836dbf3ee0 (patch) | |
| tree | 30d8dcb282134b7126b092796f2be00d2d97bd3c /develop/_l_b_dset_sub_r_w.html | |
| parent | 4e7e457497c948b41c8b0065225875bf10cdf9d4 (diff) | |
| download | hdf5-4f20d880c97be1249f8d89ced95f72836dbf3ee0.zip hdf5-4f20d880c97be1249f8d89ced95f72836dbf3ee0.tar.gz hdf5-4f20d880c97be1249f8d89ced95f72836dbf3ee0.tar.bz2 | |
deploy: ef39882fa1e13740d2530c7a0637bd1f1a822b68
Diffstat (limited to 'develop/_l_b_dset_sub_r_w.html')
| -rw-r--r-- | develop/_l_b_dset_sub_r_w.html | 241 |
1 files changed, 241 insertions, 0 deletions
diff --git a/develop/_l_b_dset_sub_r_w.html b/develop/_l_b_dset_sub_r_w.html new file mode 100644 index 0000000..982e620 --- /dev/null +++ b/develop/_l_b_dset_sub_r_w.html @@ -0,0 +1,241 @@ +<!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 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> +<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.ef39882</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_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"> +<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 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" 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" 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" 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" 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" 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.9.1 </li> + </ul> +</div> +</body> +</html> |