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
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
|
<!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: Command-line Tools For Viewing HDF5 Files</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.68e8c0e</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('_view_tools_view.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">Command-line Tools For Viewing HDF5 Files</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="_view_tools_command.html">Command-line Tools</a> </p><hr />
<h1><a class="anchor" id="secViewToolsViewTOC"></a>
Contents</h1>
<ul>
<li>
<a class="el" href="#secViewToolsViewContent">File Content and Structure</a> </li>
<li>
<a class="el" href="#secViewToolsViewDset">Datasets and Dataset Properties</a> </li>
<li>
<a class="el" href="#secViewToolsViewGrps">Groups</a> </li>
<li>
<a class="el" href="#secViewToolsViewAttr">Attributes</a> </li>
<li>
<a class="el" href="#secViewToolsViewSub">Dataset Subset</a> </li>
<li>
<a class="el" href="#secViewToolsViewDtypes">Datatypes</a> </li>
</ul>
<h1><a class="anchor" id="secViewToolsViewContent"></a>
File Content and Structure</h1>
<p>The h5dump and h5ls tools can both be used to view the contents of an HDF5 file. The tools are discussed below: </p><ul>
<li>
<a class="el" href="#subsecViewToolsViewContent_h5dump">h5dump</a> </li>
<li>
<a class="el" href="#subsecViewToolsViewContent_h5ls">h5ls</a> </li>
</ul>
<h2><a class="anchor" id="subsecViewToolsViewContent_h5dump"></a>
h5dump</h2>
<p>The h5dump tool dumps or displays the contents of an HDF5 file (textually). By default if you specify no options, h5dump will display the entire contents of a file. There are many h5dump options for examining specific details of a file. To see all of the available h5dump options, specify the <code style="background-color:whitesmoke;">-h</code> or <code style="background-color:whitesmoke;">–help</code> option: </p><div class="fragment"><div class="line">h5dump -h</div>
</div><!-- fragment --><p>The following h5dump options can be helpful in viewing the content and structure of a file: </p><table class="doxtable">
<tr>
<th>Option </th><th>Description </th><th>Comment </th></tr>
<tr>
<td>-n, –contents </td><td>Displays a list of the objects in a file </td><td>See <a class="el" href="#subsubsecViewToolsViewContent_h5dumpEx1">Example 1</a> </td></tr>
<tr>
<td>-n 1, –contents=1 </td><td>Displays a list of the objects and attributes in a file </td><td>See <a class="el" href="#subsubsecViewToolsViewAttr_h5dumpEx6">Example 6</a> </td></tr>
<tr>
<td>-H, –header </td><td>Displays header information only (no data) </td><td>See <a class="el" href="#subsubsecViewToolsViewContent_h5dumpEx2">Example 2</a> </td></tr>
<tr>
<td>-A 0, –onlyattr=0 </td><td>Suppresses the display of attributes </td><td>See <a class="el" href="#subsubsecViewToolsViewContent_h5dumpEx2">Example 2</a> </td></tr>
<tr>
<td>-N P, –any_path=P </td><td>Displays any object or attribute that matches path P </td><td>See <a class="el" href="#subsubsecViewToolsViewAttr_h5dumpEx6">Example 6</a> </td></tr>
</table>
<h3><a class="anchor" id="subsubsecViewToolsViewContent_h5dumpEx1"></a>
Example 1</h3>
<p>The following command displays a list of the objects in the file OMI-Aura.he5 (an HDF-EOS5 file): </p><div class="fragment"><div class="line">h5dump -n OMI-Aura.he5</div>
</div><!-- fragment --><p>As shown in the output below, the objects (groups, datasets) are listed to the left, followed by their names. You can see that this file contains two root groups, HDFEOS and HDFEOS INFORMATION: </p><div class="fragment"><div class="line">HDF5 <span class="stringliteral">"OMI-Aura.he5"</span> {</div>
<div class="line">FILE_CONTENTS {</div>
<div class="line"> group /</div>
<div class="line"> group /HDFEOS</div>
<div class="line"> group /HDFEOS/ADDITIONAL</div>
<div class="line"> group /HDFEOS/ADDITIONAL/FILE_ATTRIBUTES</div>
<div class="line"> group /HDFEOS/GRIDS</div>
<div class="line"> group /HDFEOS/GRIDS/OMI Column Amount O3</div>
<div class="line"> group /HDFEOS/GRIDS/OMI Column Amount O3/Data Fields</div>
<div class="line"> dataset /HDFEOS/GRIDS/OMI Column Amount O3/Data Fields/ColumnAmountO3</div>
<div class="line"> dataset /HDFEOS/GRIDS/OMI Column Amount O3/Data Fields/RadiativeCloudFraction</div>
<div class="line"> dataset /HDFEOS/GRIDS/OMI Column Amount O3/Data Fields/SolarZenithAngle</div>
<div class="line"> dataset /HDFEOS/GRIDS/OMI Column Amount O3/Data Fields/ViewingZenithAngle</div>
<div class="line"> group /HDFEOS INFORMATION</div>
<div class="line"> dataset /HDFEOS INFORMATION/StructMetadata.0</div>
<div class="line"> }</div>
<div class="line">}</div>
</div><!-- fragment --><h3><a class="anchor" id="subsubsecViewToolsViewContent_h5dumpEx2"></a>
Example 2</h3>
<p>The file structure of the OMI-Aura.he5 file can be seen with the following command. The -A 0 option suppresses the display of attributes: </p><div class="fragment"><div class="line">h5dump -H -A 0 OMI-Aura.he5</div>
</div><!-- fragment --><p>Output of this command is shown below: </p><div class="fragment"><div class="line">HDF5 <span class="stringliteral">"OMI-Aura.he5"</span> {</div>
<div class="line">GROUP <span class="stringliteral">"/"</span> {</div>
<div class="line"> GROUP <span class="stringliteral">"HDFEOS"</span> {</div>
<div class="line"> GROUP <span class="stringliteral">"ADDITIONAL"</span> {</div>
<div class="line"> GROUP <span class="stringliteral">"FILE_ATTRIBUTES"</span> {</div>
<div class="line"> }</div>
<div class="line"> }</div>
<div class="line"> GROUP <span class="stringliteral">"GRIDS"</span> {</div>
<div class="line"> GROUP <span class="stringliteral">"OMI Column Amount O3"</span> {</div>
<div class="line"> GROUP <span class="stringliteral">"Data Fields"</span> {</div>
<div class="line"> DATASET <span class="stringliteral">"ColumnAmountO3"</span> {</div>
<div class="line"> DATATYPE <a class="code hl_define" href="group___p_d_t_i_e_e_e.html#ga994ce9ffdd2c77a9352b102a883503ea">H5T_IEEE_F32LE</a></div>
<div class="line"> DATASPACE SIMPLE { ( 720, 1440 ) / ( 720, 1440 ) }</div>
<div class="line"> }</div>
<div class="line"> DATASET <span class="stringliteral">"RadiativeCloudFraction"</span> {</div>
<div class="line"> DATATYPE <a class="code hl_define" href="group___p_d_t_i_e_e_e.html#ga994ce9ffdd2c77a9352b102a883503ea">H5T_IEEE_F32LE</a></div>
<div class="line"> DATASPACE SIMPLE { ( 720, 1440 ) / ( 720, 1440 ) }</div>
<div class="line"> }</div>
<div class="line"> DATASET <span class="stringliteral">"SolarZenithAngle"</span> {</div>
<div class="line"> DATATYPE <a class="code hl_define" href="group___p_d_t_i_e_e_e.html#ga994ce9ffdd2c77a9352b102a883503ea">H5T_IEEE_F32LE</a></div>
<div class="line"> DATASPACE SIMPLE { ( 720, 1440 ) / ( 720, 1440 ) }</div>
<div class="line"> }</div>
<div class="line"> DATASET <span class="stringliteral">"ViewingZenithAngle"</span> {</div>
<div class="line"> DATATYPE <a class="code hl_define" href="group___p_d_t_i_e_e_e.html#ga994ce9ffdd2c77a9352b102a883503ea">H5T_IEEE_F32LE</a></div>
<div class="line"> DATASPACE SIMPLE { ( 720, 1440 ) / ( 720, 1440 ) }</div>
<div class="line"> }</div>
<div class="line"> }</div>
<div class="line"> }</div>
<div class="line"> }</div>
<div class="line"> }</div>
<div class="line"> GROUP <span class="stringliteral">"HDFEOS INFORMATION"</span> {</div>
<div class="line"> DATASET <span class="stringliteral">"StructMetadata.0"</span> {</div>
<div class="line"> DATATYPE <a class="code hl_enumvalue" href="_h5_tpublic_8h.html#a071841985f647f69516dbe77d93167f2a2de5d7919fe54466b7cf6a6c0b4265fa">H5T_STRING</a> {</div>
<div class="line"> STRSIZE 32000;</div>
<div class="line"> STRPAD <a class="code hl_enumvalue" href="_h5_tpublic_8h.html#ad2ab726f3bd28222a2ffb91c6bbc3514a23c685afc240bbac4da23b36d8fd7e13">H5T_STR_NULLTERM</a>;</div>
<div class="line"> CSET <a class="code hl_enumvalue" href="_h5_tpublic_8h.html#a03755b8370672668ddc7063add28e71aa27383e03d1cad9b4c32d8611a145d663">H5T_CSET_ASCII</a>;</div>
<div class="line"> CTYPE <a class="code hl_define" href="group___p_d_t_s.html#ga7f6b6959fefe56d2e871659110936d2d">H5T_C_S1</a>;</div>
<div class="line"> }</div>
<div class="line"> DATASPACE SCALAR</div>
<div class="line"> }</div>
<div class="line"> }</div>
<div class="line">}</div>
<div class="line">}</div>
<div class="ttc" id="a_h5_tpublic_8h_html_a03755b8370672668ddc7063add28e71aa27383e03d1cad9b4c32d8611a145d663"><div class="ttname"><a href="_h5_tpublic_8h.html#a03755b8370672668ddc7063add28e71aa27383e03d1cad9b4c32d8611a145d663">H5T_CSET_ASCII</a></div><div class="ttdeci">@ H5T_CSET_ASCII</div><div class="ttdef"><b>Definition</b> H5Tpublic.h:95</div></div>
<div class="ttc" id="a_h5_tpublic_8h_html_a071841985f647f69516dbe77d93167f2a2de5d7919fe54466b7cf6a6c0b4265fa"><div class="ttname"><a href="_h5_tpublic_8h.html#a071841985f647f69516dbe77d93167f2a2de5d7919fe54466b7cf6a6c0b4265fa">H5T_STRING</a></div><div class="ttdeci">@ H5T_STRING</div><div class="ttdef"><b>Definition</b> H5Tpublic.h:35</div></div>
<div class="ttc" id="a_h5_tpublic_8h_html_ad2ab726f3bd28222a2ffb91c6bbc3514a23c685afc240bbac4da23b36d8fd7e13"><div class="ttname"><a href="_h5_tpublic_8h.html#ad2ab726f3bd28222a2ffb91c6bbc3514a23c685afc240bbac4da23b36d8fd7e13">H5T_STR_NULLTERM</a></div><div class="ttdeci">@ H5T_STR_NULLTERM</div><div class="ttdef"><b>Definition</b> H5Tpublic.h:120</div></div>
<div class="ttc" id="agroup___p_d_t_i_e_e_e_html_ga994ce9ffdd2c77a9352b102a883503ea"><div class="ttname"><a href="group___p_d_t_i_e_e_e.html#ga994ce9ffdd2c77a9352b102a883503ea">H5T_IEEE_F32LE</a></div><div class="ttdeci">#define H5T_IEEE_F32LE</div><div class="ttdef"><b>Definition</b> H5Tpublic.h:261</div></div>
<div class="ttc" id="agroup___p_d_t_s_html_ga7f6b6959fefe56d2e871659110936d2d"><div class="ttname"><a href="group___p_d_t_s.html#ga7f6b6959fefe56d2e871659110936d2d">H5T_C_S1</a></div><div class="ttdeci">#define H5T_C_S1</div><div class="ttdef"><b>Definition</b> H5Tpublic.h:476</div></div>
</div><!-- fragment --><h2><a class="anchor" id="subsecViewToolsViewContent_h5ls"></a>
h5ls</h2>
<p>The h5ls tool by default just displays the objects in the root group. It will not display items in groups beneath the root group unless specified. Useful h5ls options for viewing file content and structure are: </p><table class="doxtable">
<tr>
<th>Option </th><th>Description </th><th>Comment </th></tr>
<tr>
<td>-r </td><td>Lists all groups and objects recursively </td><td>See <a class="el" href="#subsubsecViewToolsViewContent_h5lsEx3">Example 3</a> </td></tr>
<tr>
<td>-v </td><td>Generates verbose output (lists dataset properties, attributes and attribute values, but no dataset values) </td><td></td></tr>
</table>
<h3><a class="anchor" id="subsubsecViewToolsViewContent_h5lsEx3"></a>
Example 3</h3>
<p>The following command shows the contents of the HDF-EOS5 file OMI-Aura.he5. The output is similar to h5dump, except that h5ls also shows dataspace information for each dataset: </p><div class="fragment"><div class="line">h5ls -r OMI-Aura.he5</div>
</div><!-- fragment --><p>The output is shown below: </p><div class="fragment"><div class="line">/ Group</div>
<div class="line">/HDFEOS Group</div>
<div class="line">/HDFEOS/ADDITIONAL Group</div>
<div class="line">/HDFEOS/ADDITIONAL/FILE_ATTRIBUTES Group</div>
<div class="line">/HDFEOS/GRIDS Group</div>
<div class="line">/HDFEOS/GRIDS/OMI\ Column\ Amount\ O3 Group</div>
<div class="line">/HDFEOS/GRIDS/OMI\ Column\ Amount\ O3/Data\ Fields Group</div>
<div class="line">/HDFEOS/GRIDS/OMI\ Column\ Amount\ O3/Data\ Fields/ColumnAmountO3 Dataset {720, 1440}</div>
<div class="line">/HDFEOS/GRIDS/OMI\ Column\ Amount\ O3/Data\ Fields/RadiativeCloudFraction Dataset {720, 1440}</div>
<div class="line">/HDFEOS/GRIDS/OMI\ Column\ Amount\ O3/Data\ Fields/SolarZenithAngle Dataset {720, 1440}</div>
<div class="line">/HDFEOS/GRIDS/OMI\ Column\ Amount\ O3/Data\ Fields/ViewingZenithAngle Dataset {720, 1440}</div>
<div class="line">/HDFEOS\ INFORMATION Group</div>
<div class="line">/HDFEOS\ INFORMATION/StructMetadata.0 Dataset {SCALAR}</div>
</div><!-- fragment --><h1><a class="anchor" id="secViewToolsViewDset"></a>
Datasets and Dataset Properties</h1>
<p>Both h5dump and h5ls can be used to view specific datasets. </p><ul>
<li>
<a class="el" href="#subsecViewToolsViewDset_h5dump">h5dump</a> </li>
<li>
<a class="el" href="#subsecViewToolsViewDset_h5ls">h5ls</a> </li>
</ul>
<h2><a class="anchor" id="subsecViewToolsViewDset_h5dump"></a>
h5dump</h2>
<p>Useful h5dump options for examining specific datasets include: </p><table class="doxtable">
<tr>
<th>Option </th><th>Description </th><th>Comment </th></tr>
<tr>
<td>-d D, –dataset=D </td><td>Displays dataset D </td><td>See <a class="el" href="#subsubsecViewToolsViewDset_h5dumpEx4">Example 4</a> </td></tr>
<tr>
<td>-H, –header </td><td>Displays header information only </td><td>See <a class="el" href="#subsubsecViewToolsViewDset_h5dumpEx4">Example 4</a> </td></tr>
<tr>
<td>-p, –properties </td><td>Displays dataset filters, storage layout, and fill value properties </td><td>See <a class="el" href="#subsubsecViewToolsViewDset_h5dumpEx5">Example 5</a> </td></tr>
<tr>
<td>-A 0, –onlyattr=0 </td><td>Suppresses the display of attributes </td><td>See <a class="el" href="#subsubsecViewToolsViewContent_h5dumpEx2">Example 2</a> </td></tr>
<tr>
<td>-N P, –any_path=P </td><td>Displays any object or attribute that matches path P </td><td>See <a class="el" href="#subsubsecViewToolsViewAttr_h5dumpEx6">Example 6</a> </td></tr>
</table>
<h3><a class="anchor" id="subsubsecViewToolsViewDset_h5dumpEx4"></a>
Example 4</h3>
<p>A specific dataset can be viewed with <code style="background-color:whitesmoke;">h5dump</code> using the <code style="background-color:whitesmoke;">-d D</code> option and specifying the entire path and name of the dataset for <code style="background-color:whitesmoke;">D</code>. The path is important in identifying the correct dataset, as there can be multiple datasets with the same name. The path can be determined by looking at the objects in the file with <code style="background-color:whitesmoke;">h5dump -n</code>.</p>
<p>The following example uses the <code style="background-color:whitesmoke;">groups.h5</code> file that is created by the <a class="el" href="_l_b_examples.html">Examples from Learning the Basics</a> example <code style="background-color:whitesmoke;">h5_crtgrpar.c</code>. To display <code style="background-color:whitesmoke;">dset1</code> in the <code style="background-color:whitesmoke;">groups.h5</code> file below, specify dataset <code style="background-color:whitesmoke;">/MyGroup/dset1</code>. The <code style="background-color:whitesmoke;">-H</code> option is used to suppress printing of the data values:</p>
<p><em>Contents of groups.h5</em> </p><div class="fragment"><div class="line">$ h5dump -n groups.h5</div>
<div class="line">HDF5 <span class="stringliteral">"groups.h5"</span> {</div>
<div class="line">FILE_CONTENTS {</div>
<div class="line"> group /</div>
<div class="line"> group /MyGroup</div>
<div class="line"> group /MyGroup/Group_A</div>
<div class="line"> dataset /MyGroup/Group_A/dset2</div>
<div class="line"> group /MyGroup/Group_B</div>
<div class="line"> dataset /MyGroup/dset1</div>
<div class="line"> }</div>
<div class="line">}</div>
</div><!-- fragment --><p><em>Display dataset "dset1"</em> </p><div class="fragment"><div class="line">$ h5dump -d <span class="stringliteral">"/MyGroup/dset1"</span> -H groups.h5</div>
<div class="line">HDF5 <span class="stringliteral">"groups.h5"</span> {</div>
<div class="line">DATASET <span class="stringliteral">"/MyGroup/dset1"</span> {</div>
<div class="line"> DATATYPE <a class="code hl_define" href="group___p_d_t_s_t_d.html#ga37e8a6be7ee64587c2a282b965019bb8">H5T_STD_I32BE</a></div>
<div class="line"> DATASPACE SIMPLE { ( 3, 3 ) / ( 3, 3 ) }</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 --><h3><a class="anchor" id="subsubsecViewToolsViewDset_h5dumpEx5"></a>
Example 5</h3>
<p>The <code style="background-color:whitesmoke;">-p</code> option is used to examine the dataset filters, storage layout, and fill value properties of a dataset.</p>
<p>This option can be useful for checking how well compression works, or even for analyzing performance and dataset size issues related to chunking. (The smaller the chunk size, the more chunks that HDF5 has to keep track of, which increases the size of the file and potentially affects performance.)</p>
<p>In the file shown below the dataset <code style="background-color:whitesmoke;">/DS1</code> is both chunked and compressed: </p><div class="fragment"><div class="line">$ h5dump -H -p -d <span class="stringliteral">"/DS1"</span> h5ex_d_gzip.h5</div>
<div class="line">HDF5 <span class="stringliteral">"h5ex_d_gzip.h5"</span> {</div>
<div class="line">DATASET <span class="stringliteral">"/DS1"</span> {</div>
<div class="line"> DATATYPE <a class="code hl_define" href="group___p_d_t_s_t_d.html#ga8db8c9c2bcc457f9f8526c8fcb81218b">H5T_STD_I32LE</a></div>
<div class="line"> DATASPACE SIMPLE { ( 32, 64 ) / ( 32, 64 ) }</div>
<div class="line"> STORAGE_LAYOUT {</div>
<div class="line"> CHUNKED ( 4, 8 )</div>
<div class="line"> SIZE 5278 (1.552:1 COMPRESSION)</div>
<div class="line"> }</div>
<div class="line"> FILTERS {</div>
<div class="line"> COMPRESSION DEFLATE { LEVEL 9 }</div>
<div class="line"> }</div>
<div class="line"> FILLVALUE {</div>
<div class="line"> FILL_TIME <a class="code hl_enumvalue" href="_h5_dpublic_8h.html#aa39293626c4e68dd28b06c0dc84bde4aa85b225308b0a277c4dd6fed7ee465a72">H5D_FILL_TIME_IFSET</a></div>
<div class="line"> VALUE 0</div>
<div class="line"> }</div>
<div class="line"> ALLOCATION_TIME {</div>
<div class="line"> <a class="code hl_enumvalue" href="_h5_dpublic_8h.html#aab70b464cf3c5fc931dce0c4fe98b3d2ac898a96931fd3402d9e5646690c77636">H5D_ALLOC_TIME_INCR</a></div>
<div class="line"> }</div>
<div class="line">}</div>
<div class="line">}</div>
<div class="ttc" id="a_h5_dpublic_8h_html_aa39293626c4e68dd28b06c0dc84bde4aa85b225308b0a277c4dd6fed7ee465a72"><div class="ttname"><a href="_h5_dpublic_8h.html#aa39293626c4e68dd28b06c0dc84bde4aa85b225308b0a277c4dd6fed7ee465a72">H5D_FILL_TIME_IFSET</a></div><div class="ttdeci">@ H5D_FILL_TIME_IFSET</div><div class="ttdef"><b>Definition</b> H5Dpublic.h:104</div></div>
<div class="ttc" id="a_h5_dpublic_8h_html_aab70b464cf3c5fc931dce0c4fe98b3d2ac898a96931fd3402d9e5646690c77636"><div class="ttname"><a href="_h5_dpublic_8h.html#aab70b464cf3c5fc931dce0c4fe98b3d2ac898a96931fd3402d9e5646690c77636">H5D_ALLOC_TIME_INCR</a></div><div class="ttdeci">@ H5D_ALLOC_TIME_INCR</div><div class="ttdef"><b>Definition</b> H5Dpublic.h:79</div></div>
<div class="ttc" id="agroup___p_d_t_s_t_d_html_ga8db8c9c2bcc457f9f8526c8fcb81218b"><div class="ttname"><a href="group___p_d_t_s_t_d.html#ga8db8c9c2bcc457f9f8526c8fcb81218b">H5T_STD_I32LE</a></div><div class="ttdeci">#define H5T_STD_I32LE</div><div class="ttdef"><b>Definition</b> H5Tpublic.h:310</div></div>
</div><!-- fragment --><p>You can obtain the <code style="background-color:whitesmoke;">h5ex_d_gzip.c</code> program that created this file, as well as the file created, from the <a class="el" href="_ex_a_p_i.html">Examples by API</a> page.</p>
<h2><a class="anchor" id="subsecViewToolsViewDset_h5ls"></a>
h5ls</h2>
<p>Specific datasets can be specified with <code style="background-color:whitesmoke;">h5ls</code> by simply adding the dataset path and dataset after the file name. As an example, this command displays dataset <code style="background-color:whitesmoke;">dset2</code> in the <code style="background-color:whitesmoke;">groups.h5</code> file used in <a class="el" href="#subsubsecViewToolsViewDset_h5dumpEx4">Example 4</a> : </p><div class="fragment"><div class="line">h5ls groups.h5/MyGroup/Group_A/dset2</div>
</div><!-- fragment --><p>Just the dataspace information gets displayed: </p><div class="fragment"><div class="line">dset2 Dataset {2, 10}</div>
</div><!-- fragment --><p>The following options can be used to see detailed information about a dataset. </p><table class="doxtable">
<tr>
<th>Option </th><th>Description </th></tr>
<tr>
<td>-v, –verbose </td><td>Generates verbose output (lists dataset properties, attributes and attribute values, but no dataset values) </td></tr>
<tr>
<td>-d, –data </td><td>Displays dataset values </td></tr>
</table>
<p>The output of using <code style="background-color:whitesmoke;">-v</code> is shown below: </p><div class="fragment"><div class="line">$ h5ls -v groups.h5/MyGroup/Group_A/dset2</div>
<div class="line">Opened <span class="stringliteral">"groups.h5"</span> with sec2 driver.</div>
<div class="line">dset2 Dataset {2/2, 10/10}</div>
<div class="line"> Location: 1:3840</div>
<div class="line"> Links: 1</div>
<div class="line"> Storage: 80 logical bytes, 80 allocated bytes, 100.00% utilization</div>
<div class="line"> Type: 32-bit big-endian integer</div>
</div><!-- fragment --><p>The output of using <code style="background-color:whitesmoke;">-d</code> is shown below: </p><div class="fragment"><div class="line">$ h5ls -d groups.h5/MyGroup/Group_A/dset2</div>
<div class="line">dset2 Dataset {2, 10}</div>
<div class="line"> Data:</div>
<div class="line"> (0,0) 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10</div>
</div><!-- fragment --><h1><a class="anchor" id="secViewToolsViewGrps"></a>
Groups</h1>
<p>Both h5dump and h5ls can be used to view specific groups in a file. </p><ul>
<li>
<a class="el" href="#subsecViewToolsViewGrps_h5dump">h5dump</a> </li>
<li>
<a class="el" href="#subsecViewToolsViewGrps_h5ls">h5ls</a> </li>
</ul>
<h2><a class="anchor" id="subsecViewToolsViewGrps_h5dump"></a>
h5dump</h2>
<p>The <code style="background-color:whitesmoke;">h5dump</code> options that are useful for examining groups are: </p><table class="doxtable">
<tr>
<th>Option </th><th>Description </th></tr>
<tr>
<td>-g G, –group=G </td><td>Displays group G and its members </td></tr>
<tr>
<td>-H, –header </td><td>Displays header information only </td></tr>
<tr>
<td>-A 0, –onlyattr=0 </td><td>Suppresses the display of attributes </td></tr>
</table>
<p>To view the contents of the <code style="background-color:whitesmoke;">HDFEOS</code> group in the OMI file mentioned previously, you can specify the path and name of the group as follows: </p><div class="fragment"><div class="line">h5dump -g <span class="stringliteral">"/HDFEOS"</span> -H -A 0 OMI-Aura.he5</div>
</div><!-- fragment --><p>The <code style="background-color:whitesmoke;">-A 0</code> option suppresses attributes and <code style="background-color:whitesmoke;">-H</code> suppresses printing of data values: </p><div class="fragment"><div class="line">HDF5 <span class="stringliteral">"OMI-Aura.he5"</span> {</div>
<div class="line">GROUP <span class="stringliteral">"/HDFEOS"</span> {</div>
<div class="line"> GROUP <span class="stringliteral">"ADDITIONAL"</span> {</div>
<div class="line"> GROUP <span class="stringliteral">"FILE_ATTRIBUTES"</span> {</div>
<div class="line"> }</div>
<div class="line"> }</div>
<div class="line"> GROUP <span class="stringliteral">"GRIDS"</span> {</div>
<div class="line"> GROUP <span class="stringliteral">"OMI Column Amount O3"</span> {</div>
<div class="line"> GROUP <span class="stringliteral">"Data Fields"</span> {</div>
<div class="line"> DATASET <span class="stringliteral">"ColumnAmountO3"</span> {</div>
<div class="line"> DATATYPE <a class="code hl_define" href="group___p_d_t_i_e_e_e.html#ga994ce9ffdd2c77a9352b102a883503ea">H5T_IEEE_F32LE</a></div>
<div class="line"> DATASPACE SIMPLE { ( 720, 1440 ) / ( 720, 1440 ) }</div>
<div class="line"> }</div>
<div class="line"> DATASET <span class="stringliteral">"RadiativeCloudFraction"</span> {</div>
<div class="line"> DATATYPE <a class="code hl_define" href="group___p_d_t_i_e_e_e.html#ga994ce9ffdd2c77a9352b102a883503ea">H5T_IEEE_F32LE</a></div>
<div class="line"> DATASPACE SIMPLE { ( 720, 1440 ) / ( 720, 1440 ) }</div>
<div class="line"> }</div>
<div class="line"> DATASET <span class="stringliteral">"SolarZenithAngle"</span> {</div>
<div class="line"> DATATYPE <a class="code hl_define" href="group___p_d_t_i_e_e_e.html#ga994ce9ffdd2c77a9352b102a883503ea">H5T_IEEE_F32LE</a></div>
<div class="line"> DATASPACE SIMPLE { ( 720, 1440 ) / ( 720, 1440 ) }</div>
<div class="line"> }</div>
<div class="line"> DATASET <span class="stringliteral">"ViewingZenithAngle"</span> {</div>
<div class="line"> DATATYPE <a class="code hl_define" href="group___p_d_t_i_e_e_e.html#ga994ce9ffdd2c77a9352b102a883503ea">H5T_IEEE_F32LE</a></div>
<div class="line"> DATASPACE SIMPLE { ( 720, 1440 ) / ( 720, 1440 ) }</div>
<div class="line"> }</div>
<div class="line"> }</div>
<div class="line"> }</div>
<div class="line"> }</div>
<div class="line">}</div>
<div class="line">}</div>
</div><!-- fragment --><h2><a class="anchor" id="subsecViewToolsViewGrps_h5ls"></a>
h5ls</h2>
<p>You can view the contents of a group with <code style="background-color:whitesmoke;">h5ls</code>/ by specifying the group after the file name. To use <code style="background-color:whitesmoke;">h5ls</code> to view the contents of the <code style="background-color:whitesmoke;">/HDFEOS</code> group in the <code style="background-color:whitesmoke;">OMI-Aura.he5</code> file, type: </p><div class="fragment"><div class="line">h5ls -r OMI-Aura.he5/HDFEOS</div>
</div><!-- fragment --><p>The output of this command is: </p><div class="fragment"><div class="line">/ADDITIONAL Group</div>
<div class="line">/ADDITIONAL/FILE_ATTRIBUTES Group</div>
<div class="line">/GRIDS Group</div>
<div class="line">/GRIDS/OMI\ Column\ Amount\ O3 Group</div>
<div class="line">/GRIDS/OMI\ Column\ Amount\ O3/Data\ Fields Group</div>
<div class="line">/GRIDS/OMI\ Column\ Amount\ O3/Data\ Fields/ColumnAmountO3 Dataset {720, 1440}</div>
<div class="line">/GRIDS/OMI\ Column\ Amount\ O3/Data\ Fields/RadiativeCloudFraction Dataset {720, 1440}</div>
<div class="line">/GRIDS/OMI\ Column\ Amount\ O3/Data\ Fields/SolarZenithAngle Dataset {720, 1440}</div>
<div class="line">/GRIDS/OMI\ Column\ Amount\ O3/Data\ Fields/ViewingZenithAngle Dataset {720, 1440}</div>
</div><!-- fragment --><p>If you specify the <code style="background-color:whitesmoke;">-v</code> option, you can also see the attributes and properties of the datasets.</p>
<h1><a class="anchor" id="secViewToolsViewAttr"></a>
Attributes</h1>
<h2><a class="anchor" id="subsecViewToolsViewAttr_h5dump"></a>
h5dump</h2>
<p>Attributes are displayed by default if using <code style="background-color:whitesmoke;">h5dump</code>. Some files contain many attributes, which can make it difficult to examine the objects in the file. Shown below are options that can help when using <code style="background-color:whitesmoke;">h5dump</code> to work with files that have attributes.</p>
<h3><a class="anchor" id="subsubsecViewToolsViewAttr_h5dumpEx6"></a>
Example 6</h3>
<p>The <code style="background-color:whitesmoke;">-a</code> A option will display an attribute. However, the path to the attribute must be included when specifying this option. For example, to see the <code style="background-color:whitesmoke;">ScaleFactor</code> attribute in the <code style="background-color:whitesmoke;">OMI-Aura.he5</code> file, type: </p><div class="fragment"><div class="line">h5dump -a <span class="stringliteral">"/HDFEOS/GRIDS/OMI Column Amount O3/Data Fields/SolarZenithAngle/ScaleFactor"</span> OMI-Aura.he5</div>
</div><!-- fragment --><p>This command displays: </p><div class="fragment"><div class="line">HDF5 <span class="stringliteral">"OMI-Aura.he5"</span> {</div>
<div class="line">ATTRIBUTE <span class="stringliteral">"ScaleFactor"</span> {</div>
<div class="line"> DATATYPE <a class="code hl_define" href="group___p_d_t_i_e_e_e.html#ga3f9c2185ec16632fab8c20ec7a63178e">H5T_IEEE_F64LE</a></div>
<div class="line"> DATASPACE SIMPLE { ( 1 ) / ( 1 ) }</div>
<div class="line"> DATA {</div>
<div class="line"> (0): 1</div>
<div class="line"> }</div>
<div class="line">}</div>
<div class="line">}</div>
<div class="ttc" id="agroup___p_d_t_i_e_e_e_html_ga3f9c2185ec16632fab8c20ec7a63178e"><div class="ttname"><a href="group___p_d_t_i_e_e_e.html#ga3f9c2185ec16632fab8c20ec7a63178e">H5T_IEEE_F64LE</a></div><div class="ttdeci">#define H5T_IEEE_F64LE</div><div class="ttdef"><b>Definition</b> H5Tpublic.h:271</div></div>
</div><!-- fragment --><p>How can you determine the path to the attribute? This can be done by looking at the file contents with the <code style="background-color:whitesmoke;">-n 1</code> option: </p><div class="fragment"><div class="line">h5dump -n 1 OMI-Aura.he5</div>
</div><!-- fragment --><p>Below is a portion of the output for this command: </p><div class="fragment"><div class="line">HDF5 <span class="stringliteral">"OMI-Aura.he5"</span> {</div>
<div class="line">FILE_CONTENTS {</div>
<div class="line"> group /</div>
<div class="line"> group /HDFEOS</div>
<div class="line"> group /HDFEOS/ADDITIONAL</div>
<div class="line"> group /HDFEOS/ADDITIONAL/FILE_ATTRIBUTES</div>
<div class="line"> attribute /HDFEOS/ADDITIONAL/FILE_ATTRIBUTES/EndUTC</div>
<div class="line"> attribute /HDFEOS/ADDITIONAL/FILE_ATTRIBUTES/GranuleDay</div>
<div class="line"> attribute /HDFEOS/ADDITIONAL/FILE_ATTRIBUTES/GranuleDayOfYear</div>
<div class="line"> attribute /HDFEOS/ADDITIONAL/FILE_ATTRIBUTES/GranuleMonth</div>
<div class="line"> attribute /HDFEOS/ADDITIONAL/FILE_ATTRIBUTES/GranuleYear</div>
<div class="line"> attribute /HDFEOS/ADDITIONAL/FILE_ATTRIBUTES/InstrumentName</div>
<div class="line"> attribute /HDFEOS/ADDITIONAL/FILE_ATTRIBUTES/OrbitNumber</div>
<div class="line"> attribute /HDFEOS/ADDITIONAL/FILE_ATTRIBUTES/OrbitPeriod</div>
<div class="line"> attribute /HDFEOS/ADDITIONAL/FILE_ATTRIBUTES/PGEVersion</div>
<div class="line"> attribute /HDFEOS/ADDITIONAL/FILE_ATTRIBUTES/Period</div>
<div class="line"> attribute /HDFEOS/ADDITIONAL/FILE_ATTRIBUTES/ProcessLevel</div>
<div class="line"> attribute /HDFEOS/ADDITIONAL/FILE_ATTRIBUTES/StartUTC</div>
<div class="line"> attribute /HDFEOS/ADDITIONAL/FILE_ATTRIBUTES/TAI93At0zOfGranule</div>
<div class="line"> </div>
<div class="line"> ...</div>
</div><!-- fragment --><p>There can be multiple objects or attributes with the same name in a file. How can you make sure you are finding the correct object or attribute? You can first determine how many attributes there are with a specified name, and then examine the paths to them.</p>
<p>The <code style="background-color:whitesmoke;">-N</code> option can be used to display all objects or attributes with a given name. For example, there are four attributes with the name <code style="background-color:whitesmoke;">ScaleFactor</code> in the <code style="background-color:whitesmoke;">OMI-Aura.he5</code> file, as can be seen below with the <code style="background-color:whitesmoke;">-N</code> option: </p><div class="fragment"><div class="line">h5dump -N ScaleFactor OMI-Aura.he5</div>
</div><!-- fragment --><p>It outputs: </p><div class="fragment"><div class="line">HDF5 <span class="stringliteral">"OMI-Aura.he5"</span> {</div>
<div class="line">ATTRIBUTE <span class="stringliteral">"ScaleFactor"</span> {</div>
<div class="line"> DATATYPE <a class="code hl_define" href="group___p_d_t_i_e_e_e.html#ga3f9c2185ec16632fab8c20ec7a63178e">H5T_IEEE_F64LE</a></div>
<div class="line"> DATASPACE SIMPLE { ( 1 ) / ( 1 ) }</div>
<div class="line"> DATA {</div>
<div class="line"> (0): 1</div>
<div class="line"> }</div>
<div class="line">}</div>
<div class="line">ATTRIBUTE <span class="stringliteral">"ScaleFactor"</span> {</div>
<div class="line"> DATATYPE <a class="code hl_define" href="group___p_d_t_i_e_e_e.html#ga3f9c2185ec16632fab8c20ec7a63178e">H5T_IEEE_F64LE</a></div>
<div class="line"> DATASPACE SIMPLE { ( 1 ) / ( 1 ) }</div>
<div class="line"> DATA {</div>
<div class="line"> (0): 1</div>
<div class="line"> }</div>
<div class="line">}</div>
<div class="line">ATTRIBUTE <span class="stringliteral">"ScaleFactor"</span> {</div>
<div class="line"> DATATYPE <a class="code hl_define" href="group___p_d_t_i_e_e_e.html#ga3f9c2185ec16632fab8c20ec7a63178e">H5T_IEEE_F64LE</a></div>
<div class="line"> DATASPACE SIMPLE { ( 1 ) / ( 1 ) }</div>
<div class="line"> DATA {</div>
<div class="line"> (0): 1</div>
<div class="line"> }</div>
<div class="line">}</div>
<div class="line">ATTRIBUTE <span class="stringliteral">"ScaleFactor"</span> {</div>
<div class="line"> DATATYPE <a class="code hl_define" href="group___p_d_t_i_e_e_e.html#ga3f9c2185ec16632fab8c20ec7a63178e">H5T_IEEE_F64LE</a></div>
<div class="line"> DATASPACE SIMPLE { ( 1 ) / ( 1 ) }</div>
<div class="line"> DATA {</div>
<div class="line"> (0): 1</div>
<div class="line"> }</div>
<div class="line">}</div>
<div class="line">}</div>
</div><!-- fragment --><h2><a class="anchor" id="subsecViewToolsViewAttr_h5ls"></a>
h5ls</h2>
<p>If you include the <code style="background-color:whitesmoke;">-v</code> (verbose) option for <code style="background-color:whitesmoke;">h5ls</code>, you will see all of the attributes for the specified file, dataset or group. You cannot display individual attributes.</p>
<h1><a class="anchor" id="secViewToolsViewSub"></a>
Dataset Subset</h1>
<h2><a class="anchor" id="subsecViewToolsViewSub_h5dump"></a>
h5dump</h2>
<p>If you have a very large dataset, you may wish to subset or see just a portion of the dataset. This can be done with the following <code style="background-color:whitesmoke;">h5dump</code> options. </p><table class="doxtable">
<tr>
<th>Option </th><th>Description </th></tr>
<tr>
<td>-d D, –dataset=D </td><td>Dataset D </td></tr>
<tr>
<td>-s START, –start=START </td><td>Offset or start of subsetting selection </td></tr>
<tr>
<td>-S STRIDE, –stride=STRIDE </td><td>Stride (sampling along a dimension). The default (unspecified, or 1) selects every element along a dimension, a value of 2 selects every other element, a value of 3 selects every third element, ... </td></tr>
<tr>
<td>-c COUNT, –count=COUNT </td><td>Number of blocks to include in the selection </td></tr>
<tr>
<td>-k BLOCK, –block=BLOCK </td><td>Size of the block in a hyperslab. The default (unspecified, or 1) is for the block size to be the size of a single element. </td></tr>
</table>
<p>The <code style="background-color:whitesmoke;">START (s)</code>, <code style="background-color:whitesmoke;">STRIDE (S)</code>, <code style="background-color:whitesmoke;">COUNT (c)</code>, and <code style="background-color:whitesmoke;">BLOCK (k)</code> options define the shape and size of the selection. They are arrays with the same number of dimensions as the rank of the dataset's dataspace, and they all work together to define the selection. A change to one of these arrays can affect the others.</p>
<p>When specifying these h5dump options, a comma is used as the delimiter for each dimension in the option value. For example, with a 2-dimensional dataset, the option value is specified as "H,W", where H is the height and W is the width. If the offset is 0 for both dimensions, then <code style="background-color:whitesmoke;">START</code> would be specified as follows: </p><div class="fragment"><div class="line">-s <span class="stringliteral">"0,0"</span></div>
</div><!-- fragment --><p>There is also a shorthand way to specify these options with brackets at the end of the dataset name: </p><div class="fragment"><div class="line">-d DATASETNAME[s;S;c;k]</div>
</div><!-- fragment --><p>Multiple dimensions are separated by commas. For example, a subset for a 2-dimensional dataset would be specified as follows: </p><div class="fragment"><div class="line">-d DATASETNAME[s,s;S,S;c,c;k,k]</div>
</div><!-- fragment --><p>For a detailed understanding of how selections works, see 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> API in the <a class="el" href="_r_m.html">HDF5 Reference Manual</a>.</p>
<p>The dataset SolarZenithAngle in the OMI-Aura.he5 file can be used to illustrate these options. This dataset is a 2-dimensional dataset of size 720 (height) x 1440 (width). Too much data will be displayed by simply viewing the specified dataset with the <code style="background-color:whitesmoke;">-d</code> option: </p><div class="fragment"><div class="line">h5dump -d <span class="stringliteral">"HDFEOS/GRIDS/OMI Column Amount O3/Data Fields/SolarZenithAngle"</span> OMI-Aura.he5</div>
</div><!-- fragment --><p>Subsetting narrows down the output that is displayed. In the following example, the first 15x10 elements (-c "15,10") are specified, beginning with position (0,0) (-s "0,0"): </p><div class="fragment"><div class="line">h5dump -A 0 -d <span class="stringliteral">"HDFEOS/GRIDS/OMI Column Amount O3/Data Fields/SolarZenithAngle"</span> -s <span class="stringliteral">"0,0"</span> -c <span class="stringliteral">"15,10"</span> -w 0 OMI-Aura.he5</div>
</div><!-- fragment --><p>If using the shorthand method, specify: </p><div class="fragment"><div class="line">h5dump -A 0 -d <span class="stringliteral">"HDFEOS/GRIDS/OMI Column Amount O3/Data Fields/SolarZenithAngle[0,0;;15,10;]"</span> -w 0 OMI-Aura.he5</div>
</div><!-- fragment --><p>Where, the <code style="background-color:whitesmoke;">-d</code> option must be specified before subsetting options (if not using the shorthand method).</p>
<p>The <code style="background-color:whitesmoke;">-A 0</code> option suppresses the printing of attributes.</p>
<p>The <code style="background-color:whitesmoke;">-w 0</code> option sets the number of columns of output to the maximum allowed value (65535). This ensures that there are enough columns specified for displaying the data.</p>
<p>Either command displays: </p><div class="fragment"><div class="line">HDF5 <span class="stringliteral">"OMI-Aura.he5"</span> {</div>
<div class="line">DATASET <span class="stringliteral">"HDFEOS/GRIDS/OMI Column Amount O3/Data Fields/SolarZenithAngle"</span> {</div>
<div class="line"> DATATYPE <a class="code hl_define" href="group___p_d_t_i_e_e_e.html#ga994ce9ffdd2c77a9352b102a883503ea">H5T_IEEE_F32LE</a></div>
<div class="line"> DATASPACE SIMPLE { ( 720, 1440 ) / ( 720, 1440 ) }</div>
<div class="line"> SUBSET {</div>
<div class="line"> START ( 0, 0 );</div>
<div class="line"> STRIDE ( 1, 1 );</div>
<div class="line"> COUNT ( 15, 10 );</div>
<div class="line"> BLOCK ( 1, 1 );</div>
<div class="line"> DATA {</div>
<div class="line"> (0,0): 79.403, 79.403, 79.403, 79.403, 79.403, 79.403, 79.403, 79.403, 79.403, 79.403,</div>
<div class="line"> (1,0): 79.071, 79.071, 79.071, 79.071, 79.071, 79.071, 79.071, 79.071, 79.071, 79.071,</div>
<div class="line"> (2,0): 78.867, 78.867, 78.867, 78.867, 78.867, 78.867, 78.867, 78.867, 78.867, 78.867,</div>
<div class="line"> (3,0): 78.632, 78.632, 78.632, 78.632, 78.632, 78.632, 78.632, 78.632, 78.632, 78.632,</div>
<div class="line"> (4,0): 78.429, 78.429, 78.429, 78.429, 78.429, 78.429, 78.429, 78.429, 78.429, 78.429,</div>
<div class="line"> (5,0): 78.225, 78.225, 78.225, 78.225, 78.225, 78.225, 78.225, 78.225, 78.225, 78.225,</div>
<div class="line"> (6,0): 78.021, 78.021, 78.021, 78.021, 78.021, 78.021, 78.021, 78.021, 78.021, 78.021,</div>
<div class="line"> (7,0): 77.715, 77.715, 77.715, 77.715, 77.715, 77.715, 77.715, 77.715, 77.715, 77.715,</div>
<div class="line"> (8,0): 77.511, 77.511, 77.511, 77.511, 77.511, 77.511, 77.511, 77.511, 77.511, 77.511,</div>
<div class="line"> (9,0): 77.658, 77.658, 77.658, 77.307, 77.307, 77.307, 77.307, 77.307, 77.307, 77.307,</div>
<div class="line"> (10,0): 77.556, 77.556, 77.556, 77.556, 77.556, 77.556, 77.556, 77.556, 77.102, 77.102,</div>
<div class="line"> (11,0): 78.408, 78.408, 78.408, 78.408, 78.408, 78.408, 78.408, 78.408, 77.102, 77.102,</div>
<div class="line"> (12,0): 76.34, 78.413, 78.413, 78.413, 78.413, 78.413, 78.413, 78.413, 78.413, 78.413,</div>
<div class="line"> (13,0): 78.107, 78.107, 78.107, 78.107, 78.107, 78.107, 78.107, 78.107, 78.107, 77.195,</div>
<div class="line"> (14,0): 78.005, 78.005, 78.005, 78.005, 78.005, 78.005, 76.991, 76.991, 76.991, 76.991</div>
<div class="line"> }</div>
<div class="line"> }</div>
<div class="line">}</div>
<div class="line">}</div>
</div><!-- fragment --><p>What if we wish to read three rows of three elements at a time (-c "3,3"), where each element is a 2 x 3 block (-k "2,3") and we wish to begin reading from the second row (-s "1,0")?</p>
<p>You can do that with the following command: </p><div class="fragment"><div class="line">h5dump -A 0 -d <span class="stringliteral">"HDFEOS/GRIDS/OMI Column Amount O3/Data Fields/SolarZenithAngle"</span> </div>
<div class="line"> -s <span class="stringliteral">"1,0"</span> -S <span class="stringliteral">"2,3"</span> -c <span class="stringliteral">"3,3"</span> -k <span class="stringliteral">"2,3"</span> -w 0 OMI-Aura.he5</div>
</div><!-- fragment --><p>In this case, the stride must be specified as 2 by 3 (or larger) to accommodate the reading of 2 by 3 blocks. If it is smaller, the command will fail with the error, </p><div class="fragment"><div class="line">h5dump error: wrong subset selection; blocks overlap.</div>
</div><!-- fragment --><p>The output of the above command is shown below: </p><div class="fragment"><div class="line">HDF5 <span class="stringliteral">"OMI-Aura.he5"</span> {</div>
<div class="line">DATASET <span class="stringliteral">"HDFEOS/GRIDS/OMI Column Amount O3/Data Fields/SolarZenithAngle"</span> {</div>
<div class="line"> DATATYPE <a class="code hl_define" href="group___p_d_t_i_e_e_e.html#ga994ce9ffdd2c77a9352b102a883503ea">H5T_IEEE_F32LE</a></div>
<div class="line"> DATASPACE SIMPLE { ( 720, 1440 ) / ( 720, 1440 ) }</div>
<div class="line"> SUBSET {</div>
<div class="line"> START ( 1, 0 );</div>
<div class="line"> STRIDE ( 2, 3 );</div>
<div class="line"> COUNT ( 3, 3 );</div>
<div class="line"> BLOCK ( 2, 3 );</div>
<div class="line"> DATA {</div>
<div class="line"> (1,0): 79.071, 79.071, 79.071, 79.071, 79.071, 79.071, 79.071, 79.071, 79.071,</div>
<div class="line"> (2,0): 78.867, 78.867, 78.867, 78.867, 78.867, 78.867, 78.867, 78.867, 78.867,</div>
<div class="line"> (3,0): 78.632, 78.632, 78.632, 78.632, 78.632, 78.632, 78.632, 78.632, 78.632,</div>
<div class="line"> (4,0): 78.429, 78.429, 78.429, 78.429, 78.429, 78.429, 78.429, 78.429, 78.429,</div>
<div class="line"> (5,0): 78.225, 78.225, 78.225, 78.225, 78.225, 78.225, 78.225, 78.225, 78.225,</div>
<div class="line"> (6,0): 78.021, 78.021, 78.021, 78.021, 78.021, 78.021, 78.021, 78.021, 78.021</div>
<div class="line"> }</div>
<div class="line"> }</div>
<div class="line">}</div>
<div class="line">}</div>
</div><!-- fragment --><h1><a class="anchor" id="secViewToolsViewDtypes"></a>
Datatypes</h1>
<h2><a class="anchor" id="subsecViewToolsViewDtypes_h5dump"></a>
h5dump</h2>
<p>The following datatypes are discussed, using the output of <code style="background-color:whitesmoke;">h5dump</code> with HDF5 files from the <a class="el" href="_ex_a_p_i.html">Examples by API</a> page: </p><ul>
<li>
<a class="el" href="#subsubsecViewToolsViewDtypes_array">Array</a> </li>
<li>
<a class="el" href="#subsubsecViewToolsViewDtypes_objref">Object Reference</a> </li>
<li>
<a class="el" href="#subsubsecViewToolsViewDtypes_regref">Region Reference</a> </li>
<li>
<a class="el" href="#subsubsecViewToolsViewDtypes_string">String</a> </li>
</ul>
<h3><a class="anchor" id="subsubsecViewToolsViewDtypes_array"></a>
Array</h3>
<p>Users have been confused by the difference between an Array datatype (<a class="el" href="_h5_tpublic_8h.html#a071841985f647f69516dbe77d93167f2a547a4451911e912127f300ab15113854">H5T_ARRAY</a>) and a dataset that (has a dataspace that) is an array.</p>
<p>Typically, these users want a dataset that has a simple datatype (like integer or float) that is an array, like the following dataset <code style="background-color:whitesmoke;">/DS1</code>. It has a datatype of <a class="el" href="group___p_d_t_s_t_d.html#ga8db8c9c2bcc457f9f8526c8fcb81218b">H5T_STD_I32LE</a> (32-bit Little-Endian Integer) and is a 4 by 7 array: </p><div class="fragment"><div class="line">$ h5dump h5ex_d_rdwr.h5</div>
<div class="line">HDF5 <span class="stringliteral">"h5ex_d_rdwr.h5"</span> {</div>
<div class="line">GROUP <span class="stringliteral">"/"</span> {</div>
<div class="line"> DATASET <span class="stringliteral">"DS1"</span> {</div>
<div class="line"> DATATYPE <a class="code hl_define" href="group___p_d_t_s_t_d.html#ga8db8c9c2bcc457f9f8526c8fcb81218b">H5T_STD_I32LE</a></div>
<div class="line"> DATASPACE SIMPLE { ( 4, 7 ) / ( 4, 7 ) }</div>
<div class="line"> DATA {</div>
<div class="line"> (0,0): 0, -1, -2, -3, -4, -5, -6,</div>
<div class="line"> (1,0): 0, 0, 0, 0, 0, 0, 0,</div>
<div class="line"> (2,0): 0, 1, 2, 3, 4, 5, 6,</div>
<div class="line"> (3,0): 0, 2, 4, 6, 8, 10, 12</div>
<div class="line"> }</div>
<div class="line"> }</div>
<div class="line">}</div>
<div class="line">} </div>
</div><!-- fragment --><p>Contrast that with the following dataset that has both an Array datatype and is an array: </p><div class="fragment"><div class="line">$ h5dump h5ex_t_array.h5</div>
<div class="line">HDF5 <span class="stringliteral">"h5ex_t_array.h5"</span> {</div>
<div class="line">GROUP <span class="stringliteral">"/"</span> {</div>
<div class="line"> DATASET <span class="stringliteral">"DS1"</span> {</div>
<div class="line"> DATATYPE <a class="code hl_enumvalue" href="_h5_tpublic_8h.html#a071841985f647f69516dbe77d93167f2a547a4451911e912127f300ab15113854">H5T_ARRAY</a> { [3][5] <a class="code hl_define" href="group___p_d_t_s_t_d.html#ga591a85b894eab3e3ab1a2ccd9b3be565">H5T_STD_I64LE</a> }</div>
<div class="line"> DATASPACE SIMPLE { ( 4 ) / ( 4 ) }</div>
<div class="line"> DATA {</div>
<div class="line"> (0): [ 0, 0, 0, 0, 0,</div>
<div class="line"> 0, -1, -2, -3, -4,</div>
<div class="line"> 0, -2, -4, -6, -8 ],</div>
<div class="line"> (1): [ 0, 1, 2, 3, 4,</div>
<div class="line"> 1, 1, 1, 1, 1,</div>
<div class="line"> 2, 1, 0, -1, -2 ],</div>
<div class="line"> (2): [ 0, 2, 4, 6, 8,</div>
<div class="line"> 2, 3, 4, 5, 6,</div>
<div class="line"> 4, 4, 4, 4, 4 ],</div>
<div class="line"> (3): [ 0, 3, 6, 9, 12,</div>
<div class="line"> 3, 5, 7, 9, 11,</div>
<div class="line"> 6, 7, 8, 9, 10 ]</div>
<div class="line"> }</div>
<div class="line"> }</div>
<div class="line">}</div>
<div class="line">}</div>
<div class="ttc" id="a_h5_tpublic_8h_html_a071841985f647f69516dbe77d93167f2a547a4451911e912127f300ab15113854"><div class="ttname"><a href="_h5_tpublic_8h.html#a071841985f647f69516dbe77d93167f2a547a4451911e912127f300ab15113854">H5T_ARRAY</a></div><div class="ttdeci">@ H5T_ARRAY</div><div class="ttdef"><b>Definition</b> H5Tpublic.h:42</div></div>
<div class="ttc" id="agroup___p_d_t_s_t_d_html_ga591a85b894eab3e3ab1a2ccd9b3be565"><div class="ttname"><a href="group___p_d_t_s_t_d.html#ga591a85b894eab3e3ab1a2ccd9b3be565">H5T_STD_I64LE</a></div><div class="ttdeci">#define H5T_STD_I64LE</div><div class="ttdef"><b>Definition</b> H5Tpublic.h:320</div></div>
</div><!-- fragment --><p>In this file, dataset <code style="background-color:whitesmoke;">/DS1</code> has a datatype of </p><div class="fragment"><div class="line"><a class="code hl_enumvalue" href="_h5_tpublic_8h.html#a071841985f647f69516dbe77d93167f2a547a4451911e912127f300ab15113854">H5T_ARRAY</a> { [3][5] <a class="code hl_define" href="group___p_d_t_s_t_d.html#ga591a85b894eab3e3ab1a2ccd9b3be565">H5T_STD_I64LE</a> }</div>
</div><!-- fragment --><p> and it also has a dataspace of </p><div class="fragment"><div class="line">SIMPLE { ( 4 ) / ( 4 ) }</div>
</div><!-- fragment --><p> In other words, it is an array of four elements, in which each element is a 3 by 5 array of <a class="el" href="group___p_d_t_s_t_d.html#ga591a85b894eab3e3ab1a2ccd9b3be565">H5T_STD_I64LE</a>.</p>
<p>This dataset is much more complex. Also note that subsetting cannot be done on Array datatypes.</p>
<p>See this <a href="https://portal.hdfgroup.org/display/knowledge/H5T_ARRAY+Datatype">FAQ</a> for more information on the Array datatype.</p>
<h3><a class="anchor" id="subsubsecViewToolsViewDtypes_objref"></a>
Object Reference</h3>
<p>An Object Reference is a reference to an entire object (dataset, group, or named datatype). A dataset with an Object Reference datatype consists of one or more Object References. An Object Reference dataset can be used as an index to an HDF5 file.</p>
<p>The <code style="background-color:whitesmoke;">/DS1</code> dataset in the following file (<code style="background-color:whitesmoke;">h5ex_t_objref.h5</code>) is an Object Reference dataset. It contains two references, one to group <code style="background-color:whitesmoke;">/G1</code> and the other to dataset <code style="background-color:whitesmoke;">/DS2</code>: </p><div class="fragment"><div class="line">$ h5dump h5ex_t_objref.h5</div>
<div class="line">HDF5 <span class="stringliteral">"h5ex_t_objref.h5"</span> {</div>
<div class="line">GROUP <span class="stringliteral">"/"</span> {</div>
<div class="line"> DATASET <span class="stringliteral">"DS1"</span> {</div>
<div class="line"> DATATYPE <a class="code hl_enumvalue" href="_h5_tpublic_8h.html#a071841985f647f69516dbe77d93167f2a5850e0b9353a5e7aeb615fb943d4e9cd">H5T_REFERENCE</a> { H5T_STD_REF_OBJECT }</div>
<div class="line"> DATASPACE SIMPLE { ( 2 ) / ( 2 ) }</div>
<div class="line"> DATA {</div>
<div class="line"> (0): GROUP 1400 /G1 , DATASET 800 /DS2</div>
<div class="line"> }</div>
<div class="line"> }</div>
<div class="line"> DATASET <span class="stringliteral">"DS2"</span> {</div>
<div class="line"> DATATYPE <a class="code hl_define" href="group___p_d_t_s_t_d.html#ga8db8c9c2bcc457f9f8526c8fcb81218b">H5T_STD_I32LE</a></div>
<div class="line"> DATASPACE NULL</div>
<div class="line"> DATA {</div>
<div class="line"> }</div>
<div class="line"> }</div>
<div class="line"> GROUP <span class="stringliteral">"G1"</span> {</div>
<div class="line"> }</div>
<div class="line">}</div>
<div class="line">}</div>
<div class="ttc" id="a_h5_tpublic_8h_html_a071841985f647f69516dbe77d93167f2a5850e0b9353a5e7aeb615fb943d4e9cd"><div class="ttname"><a href="_h5_tpublic_8h.html#a071841985f647f69516dbe77d93167f2a5850e0b9353a5e7aeb615fb943d4e9cd">H5T_REFERENCE</a></div><div class="ttdeci">@ H5T_REFERENCE</div><div class="ttdef"><b>Definition</b> H5Tpublic.h:39</div></div>
</div><!-- fragment --><h3><a class="anchor" id="subsubsecViewToolsViewDtypes_regref"></a>
Region Reference</h3>
<p>A Region Reference is a reference to a selection within a dataset. A selection can be either individual elements or a hyperslab. In <code style="background-color:whitesmoke;">h5dump</code> you will see the name of the dataset along with the elements or slab that is selected. A dataset with a Region Reference datatype consists of one or more Region References.</p>
<p>An example of a Region Reference dataset (<code style="background-color:whitesmoke;">h5ex_t_regref.h5</code>) can be found on the <a class="el" href="_ex_a_p_i.html">Examples by API</a> page, under Datatypes. If you examine this dataset with <code style="background-color:whitesmoke;">h5dump</code> you will see that <code style="background-color:whitesmoke;">/DS1</code> is a Region Reference dataset as indicated by its datatype, highlighted in bold below: </p><div class="fragment"><div class="line">$ h5dump h5ex_t_regref.h5</div>
<div class="line">HDF5 <span class="stringliteral">"h5ex_t_regref.h5"</span> {</div>
<div class="line">GROUP <span class="stringliteral">"/"</span> {</div>
<div class="line"> DATASET <span class="stringliteral">"DS1"</span> {</div>
<div class="line"> DATATYPE <a class="code hl_enumvalue" href="_h5_tpublic_8h.html#a071841985f647f69516dbe77d93167f2a5850e0b9353a5e7aeb615fb943d4e9cd">H5T_REFERENCE</a> { <a class="code hl_define" href="group___p_d_t_s_t_d.html#gaf5cb0d5cec3d40d8b3ac27512f86895e">H5T_STD_REF_DSETREG</a> }</div>
<div class="line"> DATASPACE SIMPLE { ( 2 ) / ( 2 ) }</div>
<div class="line"> DATA {</div>
<div class="line"> DATASET /DS2 {(0,1), (2,11), (1,0), (2,4)},</div>
<div class="line"> DATASET /DS2 {(0,0)-(0,2), (0,11)-(0,13), (2,0)-(2,2), (2,11)-(2,13)}</div>
<div class="line"> }</div>
<div class="line"> }</div>
<div class="line"> DATASET <span class="stringliteral">"DS2"</span> {</div>
<div class="line"> DATATYPE <a class="code hl_define" href="group___p_d_t_s_t_d.html#gaeaa5eb139424ba27d5af8925f1aa9593">H5T_STD_I8LE</a></div>
<div class="line"> DATASPACE SIMPLE { ( 3, 16 ) / ( 3, 16 ) }</div>
<div class="line"> DATA {</div>
<div class="line"> (0,0): 84, 104, 101, 32, 113, 117, 105, 99, 107, 32, 98, 114, 111, 119,</div>
<div class="line"> (0,14): 110, 0,</div>
<div class="line"> (1,0): 102, 111, 120, 32, 106, 117, 109, 112, 115, 32, 111, 118, 101,</div>
<div class="line"> (1,13): 114, 32, 0,</div>
<div class="line"> (2,0): 116, 104, 101, 32, 53, 32, 108, 97, 122, 121, 32, 100, 111, 103,</div>
<div class="line"> (2,14): 115, 0</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_gaeaa5eb139424ba27d5af8925f1aa9593"><div class="ttname"><a href="group___p_d_t_s_t_d.html#gaeaa5eb139424ba27d5af8925f1aa9593">H5T_STD_I8LE</a></div><div class="ttdeci">#define H5T_STD_I8LE</div><div class="ttdef"><b>Definition</b> H5Tpublic.h:290</div></div>
<div class="ttc" id="agroup___p_d_t_s_t_d_html_gaf5cb0d5cec3d40d8b3ac27512f86895e"><div class="ttname"><a href="group___p_d_t_s_t_d.html#gaf5cb0d5cec3d40d8b3ac27512f86895e">H5T_STD_REF_DSETREG</a></div><div class="ttdeci">#define H5T_STD_REF_DSETREG</div><div class="ttdef"><b>Definition</b> H5Tpublic.h:410</div></div>
</div><!-- fragment --><p>It contains two Region References: </p><ul>
<li>A selection of four individual elements in dataset <code style="background-color:whitesmoke;">/DS2 : (0,1), (2,11), (1,0), (2,4)</code> See 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> API in the <a class="el" href="_u_g.html">HDF5 User Guide</a> for information on selecting individual elements. </li>
<li>A selection of these blocks in dataset <code style="background-color:whitesmoke;">/DS2 : (0,0)-(0,2), (0,11)-(0,13), (2,0)-(2,2), (2,11)-(2,13)</code> See 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> API in the <a class="el" href="_u_g.html">HDF5 User Guide</a> for how to do hyperslab selection.</li>
</ul>
<p>If you look at the code that creates the dataset (<code style="background-color:whitesmoke;">h5ex_t_regref.c</code>) you will see that the first reference is created with these calls: </p><div class="fragment"><div class="line">status = <a class="code hl_function" href="group___h5_s.html#ga2f4407dd73d0ec37e5d9e80e4382483d">H5Sselect_elements</a> (space, <a class="code hl_enumvalue" href="_h5_spublic_8h.html#a10093bab27cc5720efdab3186993da0fab90faf3dc59ecf6f28197ef471141550">H5S_SELECT_SET</a>, 4, coords[0]);</div>
<div class="line">status = <a class="code hl_function" href="group___h5_r.html#ga0ac6997b5de26b11d91a95de2869950d">H5Rcreate</a> (&wdata[0], file, DATASET2, <a class="code hl_define" href="_h5_rpublic_8h.html#a2a28c48c03a4616a02f9157fca4b2df0">H5R_DATASET_REGION</a>, space);</div>
<div class="ttc" id="a_h5_rpublic_8h_html_a2a28c48c03a4616a02f9157fca4b2df0"><div class="ttname"><a href="_h5_rpublic_8h.html#a2a28c48c03a4616a02f9157fca4b2df0">H5R_DATASET_REGION</a></div><div class="ttdeci">#define H5R_DATASET_REGION</div><div class="ttdef"><b>Definition</b> H5Rpublic.h:639</div></div>
<div class="ttc" id="a_h5_spublic_8h_html_a10093bab27cc5720efdab3186993da0fab90faf3dc59ecf6f28197ef471141550"><div class="ttname"><a href="_h5_spublic_8h.html#a10093bab27cc5720efdab3186993da0fab90faf3dc59ecf6f28197ef471141550">H5S_SELECT_SET</a></div><div class="ttdeci">@ H5S_SELECT_SET</div><div class="ttdef"><b>Definition</b> H5Spublic.h:87</div></div>
<div class="ttc" id="agroup___h5_r_html_ga0ac6997b5de26b11d91a95de2869950d"><div class="ttname"><a href="group___h5_r.html#ga0ac6997b5de26b11d91a95de2869950d">H5Rcreate</a></div><div class="ttdeci">herr_t H5Rcreate(void *ref, hid_t loc_id, const char *name, H5R_type_t ref_type, hid_t space_id)</div><div class="ttdoc">Creates a reference.</div></div>
<div class="ttc" id="agroup___h5_s_html_ga2f4407dd73d0ec37e5d9e80e4382483d"><div class="ttname"><a href="group___h5_s.html#ga2f4407dd73d0ec37e5d9e80e4382483d">H5Sselect_elements</a></div><div class="ttdeci">herr_t H5Sselect_elements(hid_t space_id, H5S_seloper_t op, size_t num_elem, const hsize_t *coord)</div><div class="ttdoc">Selects array elements to be included in the selection for a dataspace.</div></div>
</div><!-- fragment --><p>where the buffer containing the coordinates to select is: </p><div class="fragment"><div class="line">coords[4][2] = { {0, 1},</div>
<div class="line"> {2, 11},</div>
<div class="line"> {1, 0},</div>
<div class="line"> {2, 4} },</div>
</div><!-- fragment --><p>The second reference is created by calling, </p><div class="fragment"><div class="line">status = <a class="code hl_function" href="group___h5_s.html#ga6adfdf1b95dc108a65bf66e97d38536d">H5Sselect_hyperslab</a> (space, <a class="code hl_enumvalue" href="_h5_spublic_8h.html#a10093bab27cc5720efdab3186993da0fab90faf3dc59ecf6f28197ef471141550">H5S_SELECT_SET</a>, start, stride, count, block);</div>
<div class="line">status = <a class="code hl_function" href="group___h5_r.html#ga0ac6997b5de26b11d91a95de2869950d">H5Rcreate</a> (&wdata[1], file, DATASET2, <a class="code hl_define" href="_h5_rpublic_8h.html#a2a28c48c03a4616a02f9157fca4b2df0">H5R_DATASET_REGION</a>, space);</div>
<div class="ttc" id="agroup___h5_s_html_ga6adfdf1b95dc108a65bf66e97d38536d"><div class="ttname"><a href="group___h5_s.html#ga6adfdf1b95dc108a65bf66e97d38536d">H5Sselect_hyperslab</a></div><div class="ttdeci">herr_t H5Sselect_hyperslab(hid_t space_id, H5S_seloper_t op, const hsize_t start[], const hsize_t stride[], const hsize_t count[], const hsize_t block[])</div><div class="ttdoc">Selects a hyperslab region to add to the current selected region.</div></div>
</div><!-- fragment --><p> where start, stride, count, and block have these values: </p><div class="fragment"><div class="line">start[2] = {0, 0},</div>
<div class="line">stride[2] = {2, 11},</div>
<div class="line">count[2] = {2, 2},</div>
<div class="line">block[2] = {1, 3};</div>
</div><!-- fragment --><p>These start, stride, count, and block values will select the elements shown in bold in the dataset: </p><div class="fragment"><div class="line">84 104 101 32 113 117 105 99 107 32 98 114 111 119 110 0</div>
<div class="line">102 111 120 32 106 117 109 112 115 32 111 118 101 114 32 0</div>
<div class="line">116 104 101 32 53 32 108 97 122 121 32 100 111 103 115 0</div>
</div><!-- fragment --><p>If you use <code style="background-color:whitesmoke;">h5dump</code> to select a subset of dataset <code style="background-color:whitesmoke;">/DS2</code> with these start, stride, count, and block values, you will see that the same elements are selected: </p><div class="fragment"><div class="line">$ h5dump -d <span class="stringliteral">"/DS2"</span> -s <span class="stringliteral">"0,0"</span> -S <span class="stringliteral">"2,11"</span> -c <span class="stringliteral">"2,2"</span> -k <span class="stringliteral">"1,3"</span> h5ex_t_regref.h5</div>
<div class="line">HDF5 <span class="stringliteral">"h5ex_t_regref.h5"</span> {</div>
<div class="line">DATASET <span class="stringliteral">"/DS2"</span> {</div>
<div class="line"> DATATYPE <a class="code hl_define" href="group___p_d_t_s_t_d.html#gaeaa5eb139424ba27d5af8925f1aa9593">H5T_STD_I8LE</a></div>
<div class="line"> DATASPACE SIMPLE { ( 3, 16 ) / ( 3, 16 ) }</div>
<div class="line"> SUBSET {</div>
<div class="line"> START ( 0, 0 );</div>
<div class="line"> STRIDE ( 2, 11 );</div>
<div class="line"> COUNT ( 2, 2 );</div>
<div class="line"> BLOCK ( 1, 3 );</div>
<div class="line"> DATA {</div>
<div class="line"> (0,0): 84, 104, 101, 114, 111, 119,</div>
<div class="line"> (2,0): 116, 104, 101, 100, 111, 103</div>
<div class="line"> }</div>
<div class="line"> }</div>
<div class="line">}</div>
<div class="line">}</div>
</div><!-- fragment --><p>For more information on selections, see the tutorial topic on <a class="el" href="_l_b_dset_sub_r_w.html">Reading From or Writing To a Subset of a Dataset</a>. Also see the <a class="el" href="#secViewToolsViewSub">Dataset Subset</a> tutorial topic on using <code style="background-color:whitesmoke;">h5dump</code> to view a subset.</p>
<h3><a class="anchor" id="subsubsecViewToolsViewDtypes_string"></a>
String</h3>
<p>There are two types of string data, fixed length strings and variable length strings.</p>
<p>Below is the <code style="background-color:whitesmoke;">h5dump</code> output for two files that have the same strings written to them. In one file, the strings are fixed in length, and in the other, the strings have different sizes (and are variable in size).</p>
<p><em>Dataset of Fixed Length Strings</em> </p><div class="fragment"><div class="line">HDF5 <span class="stringliteral">"h5ex_t_string.h5"</span> {</div>
<div class="line">GROUP <span class="stringliteral">"/"</span> {</div>
<div class="line"> DATASET <span class="stringliteral">"DS1"</span> {</div>
<div class="line"> DATATYPE <a class="code hl_enumvalue" href="_h5_tpublic_8h.html#a071841985f647f69516dbe77d93167f2a2de5d7919fe54466b7cf6a6c0b4265fa">H5T_STRING</a> {</div>
<div class="line"> STRSIZE 7;</div>
<div class="line"> STRPAD <a class="code hl_enumvalue" href="_h5_tpublic_8h.html#ad2ab726f3bd28222a2ffb91c6bbc3514a3f73f8dae99444798f5efd7d2d2a5e5c">H5T_STR_SPACEPAD</a>;</div>
<div class="line"> CSET <a class="code hl_enumvalue" href="_h5_tpublic_8h.html#a03755b8370672668ddc7063add28e71aa27383e03d1cad9b4c32d8611a145d663">H5T_CSET_ASCII</a>;</div>
<div class="line"> CTYPE <a class="code hl_define" href="group___p_d_t_s.html#ga7f6b6959fefe56d2e871659110936d2d">H5T_C_S1</a>;</div>
<div class="line"> }</div>
<div class="line"> DATASPACE SIMPLE { ( 4 ) / ( 4 ) }</div>
<div class="line"> DATA {</div>
<div class="line"> (0): <span class="stringliteral">"Parting"</span>, <span class="stringliteral">"is such"</span>, <span class="stringliteral">"sweet "</span>, <span class="stringliteral">"sorrow."</span></div>
<div class="line"> }</div>
<div class="line"> }</div>
<div class="line">}</div>
<div class="line">}</div>
<div class="ttc" id="a_h5_tpublic_8h_html_ad2ab726f3bd28222a2ffb91c6bbc3514a3f73f8dae99444798f5efd7d2d2a5e5c"><div class="ttname"><a href="_h5_tpublic_8h.html#ad2ab726f3bd28222a2ffb91c6bbc3514a3f73f8dae99444798f5efd7d2d2a5e5c">H5T_STR_SPACEPAD</a></div><div class="ttdeci">@ H5T_STR_SPACEPAD</div><div class="ttdef"><b>Definition</b> H5Tpublic.h:122</div></div>
</div><!-- fragment --><p><em>Dataset of Variable Length Strings</em> </p><div class="fragment"><div class="line">HDF5 <span class="stringliteral">"h5ex_t_vlstring.h5"</span> {</div>
<div class="line">GROUP <span class="stringliteral">"/"</span> {</div>
<div class="line"> DATASET <span class="stringliteral">"DS1"</span> {</div>
<div class="line"> DATATYPE <a class="code hl_enumvalue" href="_h5_tpublic_8h.html#a071841985f647f69516dbe77d93167f2a2de5d7919fe54466b7cf6a6c0b4265fa">H5T_STRING</a> {</div>
<div class="line"> STRSIZE <a class="code hl_define" href="_h5_tpublic_8h.html#a5185e14efde13b48249fe391324331bc">H5T_VARIABLE</a>;</div>
<div class="line"> STRPAD <a class="code hl_enumvalue" href="_h5_tpublic_8h.html#ad2ab726f3bd28222a2ffb91c6bbc3514a3f73f8dae99444798f5efd7d2d2a5e5c">H5T_STR_SPACEPAD</a>;</div>
<div class="line"> CSET <a class="code hl_enumvalue" href="_h5_tpublic_8h.html#a03755b8370672668ddc7063add28e71aa27383e03d1cad9b4c32d8611a145d663">H5T_CSET_ASCII</a>;</div>
<div class="line"> CTYPE <a class="code hl_define" href="group___p_d_t_s.html#ga7f6b6959fefe56d2e871659110936d2d">H5T_C_S1</a>;</div>
<div class="line"> }</div>
<div class="line"> DATASPACE SIMPLE { ( 4 ) / ( 4 ) }</div>
<div class="line"> DATA {</div>
<div class="line"> (0): <span class="stringliteral">"Parting"</span>, <span class="stringliteral">"is such"</span>, <span class="stringliteral">"sweet"</span>, <span class="stringliteral">"sorrow."</span></div>
<div class="line"> }</div>
<div class="line"> }</div>
<div class="line">}</div>
<div class="line">}</div>
<div class="ttc" id="a_h5_tpublic_8h_html_a5185e14efde13b48249fe391324331bc"><div class="ttname"><a href="_h5_tpublic_8h.html#a5185e14efde13b48249fe391324331bc">H5T_VARIABLE</a></div><div class="ttdeci">#define H5T_VARIABLE</div><div class="ttdef"><b>Definition</b> H5Tpublic.h:207</div></div>
</div><!-- fragment --><p>You might wonder which to use. Some comments to consider are included below. </p><ul>
<li>In general, a variable length string dataset is more complex than a fixed length string. If you don't specifically need a variable length type, then just use the fixed length string. </li>
<li>A variable length dataset consists of pointers to heaps in different locations in the file. For this reason, a variable length dataset cannot be compressed. (Basically, the pointers get compressed and not the actual data!) If compression is needed, then do not use variable length types. </li>
<li>If you need to create an array of of different length strings, you can either use fixed length strings along with compression, or use a variable length string.</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="_view_tools_command.html">Command-line Tools</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>
|
