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
|
<!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 Editing 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.2908dd1</span>
</div>
<div id="projectbrief">API Reference</div>
</td>
<td> <div id="MSearchBox" class="MSearchBoxInactive">
<span class="left">
<span id="MSearchSelect" onmouseover="return searchBox.OnSearchSelectShow()" onmouseout="return searchBox.OnSearchSelectHide()"> </span>
<input type="text" id="MSearchField" value="" placeholder="Search" accesskey="S"
onfocus="searchBox.OnSearchFieldFocus(true)"
onblur="searchBox.OnSearchFieldFocus(false)"
onkeyup="searchBox.OnSearchFieldChange(event)"/>
</span><span class="right">
<a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.svg" alt=""/></a>
</span>
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.10.0 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt MIT */
var searchBox = new SearchBox("searchBox", "search/",'.html');
/* @license-end */
</script>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
<div id="nav-tree">
<div id="nav-tree-contents">
<div id="nav-sync" class="sync"></div>
</div>
</div>
<div id="splitbar" style="-moz-user-select:none;"
class="ui-resizable-handle">
</div>
</div>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt MIT */
$(function(){initNavTree('_view_tools_edit.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 Editing 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="secViewToolsEditTOC"></a>
Contents</h1>
<ul>
<li>
<a class="el" href="#secViewToolsEditRemove">Remove Inaccessible Objects and Unused Space in a File</a> </li>
<li>
<a class="el" href="#secViewToolsEditChange">Change a Dataset's Storage Layout</a> </li>
<li>
<a class="el" href="#secViewToolsEditApply">Apply Compression Filter to a Dataset</a> </li>
<li>
<a class="el" href="#secViewToolsEditCopy">Copy Objects to Another File</a> </li>
<li>
<a class="el" href="#secViewToolsEditAdd">Add or Remove User Block from File</a> </li>
</ul>
<h1><a class="anchor" id="secViewToolsEditRemove"></a>
Remove Inaccessible Objects and Unused Space in a File</h1>
<p>HDF5 files may accumulate unused space when they are read and rewritten to or if objects are deleted within them. With many edits and deletions this unused space can add up to a sizable amount.</p>
<p>The <code style="background-color:whitesmoke;">h5repack</code> tool can be used to remove unused space in an HDF5 file. If no options other than the input and output HDF5 files are specified on the <code style="background-color:whitesmoke;">h5repack</code> command line, it will write the file to the new file, getting rid of the unused space: </p><div class="fragment"><div class="line">h5repack <input file> <output file></div>
</div><!-- fragment --><h1><a class="anchor" id="secViewToolsEditChange"></a>
Change a Dataset's Storage Layout</h1>
<p>The <code style="background-color:whitesmoke;">h5repack</code> utility can be used to change a dataset's storage layout. By default, the storage layout of a dataset is defined at creation time and it cannot be changed. However, with h5repack you can write an HDF5 file to a new file and change the layout for objects in the new file.</p>
<p>The <code style="background-color:whitesmoke;">-l</code> option in <code style="background-color:whitesmoke;">h5repack</code> is used to change the layout for an object. The string following the <code style="background-color:whitesmoke;">-l</code> option defines the layout type and parameters for specified objects (or all objects): </p><div class="fragment"><div class="line">h5repack -l [list of objects:]<layout type>=<layout parameters> <input file> <output file></div>
</div><!-- fragment --><p>If no object is specified, then everything in the input file will be written to the output file with the specified layout type and parameters. If objects are specified then everything in the input file will be written to the output file as is, except for those specified objects. They will be written to the output file with the given layout type and parameters.</p>
<p>Following is a description of the dataset layouts and the <code style="background-color:whitesmoke;">h5repack</code> options to use to change a dataset: </p><table class="doxtable">
<tr>
<th>Storage Layout</th><th>h5repack Option</th><th>Description </th></tr>
<tr>
<td>Contiguous <br />
</td><td>CONTI </td><td>Data is stored physically together </td></tr>
<tr>
<td>Chunked </td><td>CHUNK=DIM[xDIM...xDIM] </td><td>Data is stored in DIM[xDIM...xDIM] chunks </td></tr>
<tr>
<td>Compact </td><td>COMPA </td><td>Data is stored in the header of the object (less I/O) </td></tr>
</table>
<p>If you type <code style="background-color:whitesmoke;">h5repack -h</code> on the command line, you will see a detailed usage statement with examples of modifying the layout.</p>
<p>In the following example, the dataset <code style="background-color:whitesmoke;">/dset</code> in the file dset.h5 is contiguous, as shown by the <code style="background-color:whitesmoke;">h5dump -pH</code> command. The <code style="background-color:whitesmoke;">h5repack</code> utility writes dset.h5 to a new file, dsetrpk.h5, where the dataset <code style="background-color:whitesmoke;">dset</code> is chunked. This can be seen by examining the resulting dsetrpk.h5 file with <code style="background-color:whitesmoke;">h5dump</code>, as shown: </p><div class="fragment"><div class="line">$ h5dump -pH dset.h5</div>
<div class="line">HDF5 <span class="stringliteral">"dset.h5"</span> {</div>
<div class="line">GROUP <span class="stringliteral">"/"</span> {</div>
<div class="line"> DATASET <span class="stringliteral">"dset"</span> {</div>
<div class="line"> DATATYPE <a class="code hl_define" href="group___p_d_t_s_t_d.html#ga37e8a6be7ee64587c2a282b965019bb8">H5T_STD_I32BE</a></div>
<div class="line"> DATASPACE SIMPLE { ( 4, 6 ) / ( 4, 6 ) }</div>
<div class="line"> STORAGE_LAYOUT {</div>
<div class="line"> CONTIGUOUS</div>
<div class="line"> SIZE 96</div>
<div class="line"> OFFSET 1400</div>
<div class="line"> }</div>
<div class="line"> FILTERS {</div>
<div class="line"> NONE</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#aab70b464cf3c5fc931dce0c4fe98b3d2a7c5fcb6f9c8adecf455939c3d625b7e8">H5D_ALLOC_TIME_LATE</a></div>
<div class="line"> }</div>
<div class="line"> }</div>
<div class="line">}</div>
<div class="line">}</div>
<div class="line"> </div>
<div class="line">$ h5repack -l dset:CHUNK=4x6 dset.h5 dsetrpk.h5</div>
<div class="line"> </div>
<div class="line">$ h5dump -pH dsetrpk.h5</div>
<div class="line">HDF5 <span class="stringliteral">"dsetrpk.h5"</span> {</div>
<div class="line">GROUP <span class="stringliteral">"/"</span> {</div>
<div class="line"> DATASET <span class="stringliteral">"dset"</span> {</div>
<div class="line"> DATATYPE <a class="code hl_define" href="group___p_d_t_s_t_d.html#ga37e8a6be7ee64587c2a282b965019bb8">H5T_STD_I32BE</a></div>
<div class="line"> DATASPACE SIMPLE { ( 4, 6 ) / ( 4, 6 ) }</div>
<div class="line"> STORAGE_LAYOUT {</div>
<div class="line"> CHUNKED ( 4, 6 )</div>
<div class="line"> SIZE 96</div>
<div class="line"> }</div>
<div class="line"> FILTERS {</div>
<div class="line"> NONE</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="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_aab70b464cf3c5fc931dce0c4fe98b3d2a7c5fcb6f9c8adecf455939c3d625b7e8"><div class="ttname"><a href="_h5_dpublic_8h.html#aab70b464cf3c5fc931dce0c4fe98b3d2a7c5fcb6f9c8adecf455939c3d625b7e8">H5D_ALLOC_TIME_LATE</a></div><div class="ttdeci">@ H5D_ALLOC_TIME_LATE</div><div class="ttdef"><b>Definition</b> H5Dpublic.h:78</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_ga37e8a6be7ee64587c2a282b965019bb8"><div class="ttname"><a href="group___p_d_t_s_t_d.html#ga37e8a6be7ee64587c2a282b965019bb8">H5T_STD_I32BE</a></div><div class="ttdeci">#define H5T_STD_I32BE</div><div class="ttdef"><b>Definition</b> H5Tpublic.h:305</div></div>
</div><!-- fragment --><p>There can be many reasons that the storage layout needs to be changed for a dataset. For example, there may be a performance issue with a dataset due to a small chunk size.</p>
<h1><a class="anchor" id="secViewToolsEditApply"></a>
Apply Compression Filter to a Dataset</h1>
<p>The <code style="background-color:whitesmoke;">h5repack</code> utility can be used to compress or remove compression from a dataset in a file. By default, compression cannot be added to or removed from a dataset once it has been created. However, with <code style="background-color:whitesmoke;">h5repack</code> you can write a file to a new file and specify a compression filter to apply to a dataset or datasets in the new file.</p>
<p>To apply a filter to an object in an HDF5 file, specify the <code style="background-color:whitesmoke;">-f</code> option, where the string following the <code style="background-color:whitesmoke;">-f</code> option defines the filter and its parameters (if there are any) to apply to a given object or objects: </p><div class="fragment"><div class="line">h5repack -f [list of objects:]<name of filter>=<filter parameters> <input file> <output file></div>
</div><!-- fragment --><p>If no objects are specified then everything in the input file will be written to the output file with the filter and parameters specified. If objects are specified, then everything in the input file will be written to the output file as is, except for the specified objects. They will be written to the output file with the filter and parameters specified.</p>
<p>If you type <code style="background-color:whitesmoke;">h5repack –help</code> on the command line, you will see a detailed usage statement with examples of modifying a filter. There are actually numerous filters that you can apply to a dataset: </p><table class="doxtable">
<tr>
<th>Filter</th><th>Options </th></tr>
<tr>
<td>GZIP compression (levels 1-9) </td><td>GZIP=<deflation level> </td></tr>
<tr>
<td>SZIP compression </td><td>SZIP=<pixels per block,coding> </td></tr>
<tr>
<td>Shuffle filter </td><td>SHUF </td></tr>
<tr>
<td>Checksum filter </td><td>FLET </td></tr>
<tr>
<td>NBIT compression </td><td>NBIT </td></tr>
<tr>
<td>HDF5 Scale/Offset filter </td><td>SOFF=<scale_factor,scale_type> </td></tr>
<tr>
<td>User defined filter </td><td>UD=<filter_number,cd_value_count,value_1[,value_2,...,value_N]> </td></tr>
<tr>
<td>Remove ALL filters </td><td>NONE </td></tr>
</table>
<p>Be aware that a dataset must be chunked to apply compression to it. If the dataset is not already chunked, then <code style="background-color:whitesmoke;">h5repack</code> will apply chunking to it. Both chunking and compression cannot be applied to a dataset at the same time with <code style="background-color:whitesmoke;">h5repack</code>.</p>
<p>In the following example, </p><ul>
<li><em>h5dump</em> lists the properties for the objects in <em>dset.h5</em>. Note that the dataset <em>dset</em> is contiguous. </li>
<li><em>h5repack</em> writes dset.h5 into a new file <em>dsetrpk.h5</em>, applying GZIP Level 5 compression to the dataset <em>/dset</em> in dsetrpk.h5. </li>
<li><em>h5dump</em> lists the properties for the new <em>dsetrpk.h5</em> file. Note that <em>/dset</em> is both compressed and chunked.</li>
</ul>
<p><em>Example</em> </p><div class="fragment"><div class="line">$ h5dump -pH dset.h5</div>
<div class="line">HDF5 <span class="stringliteral">"dset.h5"</span> {</div>
<div class="line">GROUP <span class="stringliteral">"/"</span> {</div>
<div class="line"> DATASET <span class="stringliteral">"dset"</span> {</div>
<div class="line"> DATATYPE <a class="code hl_define" href="group___p_d_t_s_t_d.html#ga37e8a6be7ee64587c2a282b965019bb8">H5T_STD_I32BE</a></div>
<div class="line"> DATASPACE SIMPLE { ( 12, 18 ) / ( 12, 18 ) }</div>
<div class="line"> STORAGE_LAYOUT {</div>
<div class="line"> CONTIGUOUS</div>
<div class="line"> SIZE 864</div>
<div class="line"> OFFSET 1400</div>
<div class="line"> }</div>
<div class="line"> FILTERS {</div>
<div class="line"> NONE</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#aab70b464cf3c5fc931dce0c4fe98b3d2a7c5fcb6f9c8adecf455939c3d625b7e8">H5D_ALLOC_TIME_LATE</a></div>
<div class="line"> }</div>
<div class="line"> }</div>
<div class="line">}</div>
<div class="line">}</div>
<div class="line"> </div>
<div class="line">$ h5repack -f dset:GZIP=5 dset.h5 dsetrpk.h5</div>
<div class="line"> </div>
<div class="line">$ h5dump -pH dsetrpk.h5</div>
<div class="line">HDF5 <span class="stringliteral">"dsetrpk.h5"</span> {</div>
<div class="line">GROUP <span class="stringliteral">"/"</span> {</div>
<div class="line"> DATASET <span class="stringliteral">"dset"</span> {</div>
<div class="line"> DATATYPE <a class="code hl_define" href="group___p_d_t_s_t_d.html#ga37e8a6be7ee64587c2a282b965019bb8">H5T_STD_I32BE</a></div>
<div class="line"> DATASPACE SIMPLE { ( 12, 18 ) / ( 12, 18 ) }</div>
<div class="line"> STORAGE_LAYOUT {</div>
<div class="line"> CHUNKED ( 12, 18 )</div>
<div class="line"> SIZE 160 (5.400:1 COMPRESSION)</div>
<div class="line"> }</div>
<div class="line"> FILTERS {</div>
<div class="line"> COMPRESSION DEFLATE { LEVEL 5 }</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="line">}</div>
</div><!-- fragment --><h1><a class="anchor" id="secViewToolsEditCopy"></a>
Copy Objects to Another File</h1>
<p>The <code style="background-color:whitesmoke;">h5copy</code> utility can be used to copy an object or objects from one HDF5 file to another or to a different location in the same file. It uses the <a class="el" href="group___h5_o.html#gaa94449be6f67f499be5ddd3fc44f4225" title="Copies an object in an HDF5 file.">H5Ocopy</a> and <a class="el" href="group___h5_l.html#gafd4624f1c040d5f1df36cb1e6986aac6" title="Creates an identical copy of a link with the same creation time and target. The new link can have a d...">H5Lcopy</a> APIs in HDF5.</p>
<p>Following are some of the options that can be used with <code style="background-color:whitesmoke;">h5copy</code>. </p><table class="doxtable">
<tr>
<th>h5copy Options</th><th>Description </th></tr>
<tr>
<td>-i, –input </td><td>Input file name </td></tr>
<tr>
<td>-o, –output </td><td>Output file name </td></tr>
<tr>
<td>-s, –source </td><td>Source object name </td></tr>
<tr>
<td>-d, –destination </td><td>Destination object name </td></tr>
<tr>
<td>-p, –parents </td><td>Make parent groups as needed </td></tr>
<tr>
<td>-v, –verbose </td><td>Verbose mode </td></tr>
<tr>
<td>-f, –flag </td><td>Flag type </td></tr>
</table>
<p>For a complete list of options and information on using <code style="background-color:whitesmoke;">h5copy</code>, type: </p><div class="fragment"><div class="line">h5copy --help</div>
</div><!-- fragment --><p>In the example below, the dataset <code style="background-color:whitesmoke;">/MyGroup/Group_A/dset2</code> in <code style="background-color:whitesmoke;">groups.h5</code> gets copied to the root ("<code style="background-color:whitesmoke;">/</code>") group of a new file, <code style="background-color:whitesmoke;">newgroup.h5</code>, with the name <code style="background-color:whitesmoke;">dset3</code>: </p><div class="fragment"><div class="line">$h5dump -H groups.h5</div>
<div class="line">HDF5 <span class="stringliteral">"groups.h5"</span> {</div>
<div class="line">GROUP <span class="stringliteral">"/"</span> {</div>
<div class="line"> GROUP <span class="stringliteral">"MyGroup"</span> {</div>
<div class="line"> GROUP <span class="stringliteral">"Group_A"</span> {</div>
<div class="line"> DATASET <span class="stringliteral">"dset2"</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 { ( 2, 10 ) / ( 2, 10 ) }</div>
<div class="line"> }</div>
<div class="line"> }</div>
<div class="line"> GROUP <span class="stringliteral">"Group_B"</span> {</div>
<div class="line"> }</div>
<div class="line"> DATASET <span class="stringliteral">"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="line">}</div>
<div class="line">}</div>
<div class="line"> </div>
<div class="line">$ h5copy -i groups.h5 -o newgroup.h5 -s /MyGroup/Group_A/dset2 -d /dset3</div>
<div class="line"> </div>
<div class="line">$ h5dump -H newgroup.h5</div>
<div class="line">HDF5 <span class="stringliteral">"newgroup.h5"</span> {</div>
<div class="line">GROUP <span class="stringliteral">"/"</span> {</div>
<div class="line"> DATASET <span class="stringliteral">"dset3"</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 { ( 2, 10 ) / ( 2, 10 ) }</div>
<div class="line"> }</div>
<div class="line">}</div>
<div class="line">}</div>
</div><!-- fragment --><p>There are also <code style="background-color:whitesmoke;">h5copy</code> flags that can be specified with the <code style="background-color:whitesmoke;">-f</code> option. In the example below, the <code style="background-color:whitesmoke;">-f shallow</code> option specifies to copy only the immediate members of the group <code style="background-color:whitesmoke;">/MyGroup</code> from the <code style="background-color:whitesmoke;">groups.h5</code> file mentioned above to a new file <code style="background-color:whitesmoke;">mygrouponly.h5</code>: </p><div class="fragment"><div class="line">h5copy -v -i groups.h5 -o mygrouponly.h5 -s /MyGroup -d /MyGroup -f shallow</div>
</div><!-- fragment --><p>The output of the above command is shown below. The verbose option <code style="background-color:whitesmoke;">-v</code> describes the action that was taken, as shown in the highlighted text. </p><div class="fragment"><div class="line">Copying file <groups.h5> and <span class="keywordtype">object</span> </MyGroup> to file <mygrouponly.h5> and <span class="keywordtype">object</span> </MyGroup></div>
<div class="line">Using shallow flag</div>
<div class="line"> </div>
<div class="line">$ h5dump -H mygrouponly.h5</div>
<div class="line">HDF5 <span class="stringliteral">"mygrouponly.h5"</span> {</div>
<div class="line">GROUP <span class="stringliteral">"/"</span> {</div>
<div class="line"> GROUP <span class="stringliteral">"MyGroup"</span> {</div>
<div class="line"> GROUP <span class="stringliteral">"Group_A"</span> {</div>
<div class="line"> }</div>
<div class="line"> GROUP <span class="stringliteral">"Group_B"</span> {</div>
<div class="line"> }</div>
<div class="line"> DATASET <span class="stringliteral">"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="line">}</div>
<div class="line">}</div>
</div><!-- fragment --><h1><a class="anchor" id="secViewToolsEditAdd"></a>
Add or Remove User Block from File</h1>
<p>The user block is a space in an HDF5 file that is not interpreted by the HDF5 library. It is a property list that can be added when creating a file. See the <a class="el" href="group___f_c_p_l.html#ga403bd982a2976c932237b186ed1cff4d" title="Sets user block size.">H5Pset_userblock</a> API in the <a class="el" href="_r_m.html">HDF5 Reference Manual</a> for more information regarding this property.</p>
<p>Once created in a file, the user block cannot be removed. However, you can use the <code style="background-color:whitesmoke;">h5jam</code> and <code style="background-color:whitesmoke;">h5unjam</code> utilities to add or remove a user block from a file into a new file.</p>
<p>These two utilities work similarly, except that <code style="background-color:whitesmoke;">h5jam</code> adds a user block to a file and <code style="background-color:whitesmoke;">h5unjam</code> removes the user block. You can also overwrite or delete a user block in a file.</p>
<p>Specify the <code style="background-color:whitesmoke;">-h</code> option to see a complete list of options that can be used with <code style="background-color:whitesmoke;">h5jam</code> and <code style="background-color:whitesmoke;">h5unjam</code>. For example: </p><div class="fragment"><div class="line">h5jam -h</div>
<div class="line">h5unjam -h</div>
</div><!-- fragment --><p>Below are the basic options for adding or removing a user block with <code style="background-color:whitesmoke;">h5jam</code> and <code style="background-color:whitesmoke;">h5unjam</code>:</p>
<table class="doxtable">
<tr>
<th>h5copy Options</th><th>Description </th></tr>
<tr>
<td>-i </td><td>Input File </td></tr>
<tr>
<td>-o </td><td>Output File </td></tr>
<tr>
<td>-u </td><td>File to add or remove from user block </td></tr>
</table>
<p>Let's say you wanted to add the program that creates an HDF5 file to its user block. As an example, you can take the <code style="background-color:whitesmoke;">h5_crtgrpar.c</code> program from the <a class="el" href="_l_b_examples.html">Examples from Learning the Basics</a> and add it to the file it creates, <code style="background-color:whitesmoke;">groups.h5</code>. This can be done with <code style="background-color:whitesmoke;">h5jam</code>, as follows: </p><div class="fragment"><div class="line">h5jam -i groups.h5 -u h5_crtgrpar.c -o groupsub.h5</div>
</div><!-- fragment --><p>You can actually view the file with more <code style="background-color:whitesmoke;">groupsub.h5</code> to see that the <code style="background-color:whitesmoke;">h5_crtgrpar.c</code> file is indeed included.</p>
<p>To remove the user block that was just added, type: </p><div class="fragment"><div class="line">h5unjam -i groupsub.h5 -u h5_crtgrparNEW.c -o groups-noub.h5</div>
</div><!-- fragment --><p>This writes the user block in the file <code style="background-color:whitesmoke;">groupsub.h5</code> into <code style="background-color:whitesmoke;">h5_crtgrparNEW.c</code>. The new HDF5 file, <code style="background-color:whitesmoke;">groups-noub.h5</code>, will not contain a user block.</p>
<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>
|
