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
|
<!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: HDF5 Attributes</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.f73da83</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('_h5_a__u_g.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">HDF5 Attributes</div></div>
</div><!--header-->
<div class="contents">
<div class="textblock"><h1><a class="anchor" id="sec_attribute"></a>
HDF5 Attributes</h1>
<p>An HDF5 attribute is a small metadata object describing the nature and/or intended usage of a primary data object. A primary data object may be a dataset, group, or committed datatype.</p>
<h2><a class="anchor" id="subsec_attribute_intro"></a>
Introduction</h2>
<p>Attributes are assumed to be very small as data objects go, so storing them as standard HDF5 datasets would be quite inefficient. HDF5 attributes are therefore managed through a special attributes interface, <a class="el" href="group___h5_a.html">Attributes (H5A)</a>, which is designed to easily attach attributes to primary data objects as small datasets containing metadata information and to minimize storage requirements.</p>
<p>Consider, as examples of the simplest case, a set of laboratory readings taken under known temperature and pressure conditions of 18.0 degrees Celsius and 0.5 atmospheres, respectively. The temperature and pressure stored as attributes of the dataset could be described as the following name/value pairs: </p><ul>
<li>temp=18.0 </li>
<li>pressure=0.5</li>
</ul>
<p>While HDF5 attributes are not standard HDF5 datasets, they have much in common: </p><ul>
<li>An attribute has a user-defined dataspace and the included metadata has a user-assigned datatype </li>
<li>Metadata can be of any valid HDF5 datatype </li>
<li>Attributes are addressed by name</li>
</ul>
<p>But there are some very important differences: </p><ul>
<li>There is no provision for special storage such as compression or chunking </li>
<li>There is no partial I/O or sub-setting capability for attribute data </li>
<li>Attributes cannot be shared </li>
<li>Attributes cannot have attributes </li>
<li>Being small, an attribute is stored in the object header of the object it describes and is thus attached directly to that object</li>
</ul>
<h2><a class="anchor" id="subsec_error_H5A"></a>
Attribute Function Summaries</h2>
<dl class="section see"><dt>See also</dt><dd><a class="el" href="group___h5_a.html">Attributes (H5A)</a> reference manual</dd></dl>
<h2><a class="anchor" id="subsec_attribute_program"></a>
Programming Model for Attributes</h2>
<p>The figure below shows the UML model for an HDF5 attribute and its associated dataspace and datatype. </p><table class="doxtable">
<tr>
<td><div class="image">
<img src="UML_Attribute.jpg" alt=""/>
<div class="caption">
The UML model for an HDF5 attribute</div></div>
</td></tr>
</table>
<p>Creating an attribute is similar to creating a dataset. To create an attribute, the application must specify the object to which the attribute is attached, the datatype and dataspace of the attribute data, and the attribute creation property list.</p>
<p>The following steps are required to create and write an HDF5 attribute: </p><ul>
<li>Obtain the object identifier for the attribute's primary data object </li>
<li>Define the characteristics of the attribute and specify the attribute creation property list <ul>
<li>
Define the datatype </li>
<li>
Define the dataspace </li>
<li>
Specify the attribute creation property list</li>
</ul>
</li>
<li>Create the attribute </li>
<li>Write the attribute data (optional) </li>
<li>Close the attribute (and datatype, dataspace, and attribute creation property list, if necessary) </li>
<li>Close the primary data object (if appropriate)</li>
</ul>
<p>The following steps are required to open and read/write an existing attribute. Since HDF5 attributes allow no partial I/O, you need specify only the attribute and the attribute's memory datatype to read it: </p><ul>
<li>Obtain the object identifier for the attribute's primary data object </li>
<li>Obtain the attribute's name or index </li>
<li>Open the attribute </li>
<li>Get attribute dataspace and datatype (optional) </li>
<li>Specify the attribute's memory type </li>
<li>Read and/or write the attribute data </li>
<li>Close the attribute </li>
<li>Close the primary data object (if appropriate)</li>
</ul>
<table class="doxtable">
<tr>
<th>Create</th><th>Update </th></tr>
<tr valign="top">
<td><div class="fragment"><div class="line"><span class="lineno"> 14</span> {</div>
<div class="line"><span class="lineno"> 15</span> __label__ fail_acpl, fail_attr, fail_file;</div>
<div class="line"><span class="lineno"> 16</span> <a class="code hl_typedef" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> file, acpl, fspace, attr;</div>
<div class="line"><span class="lineno"> 17</span> </div>
<div class="line"><span class="lineno"> 18</span> <span class="keywordtype">unsigned</span> mode = <a class="code hl_define" href="_h5_fpublic_8h.html#a5a2d6726f9ad8d2bca8df2b817e5ad6a">H5F_ACC_TRUNC</a>;</div>
<div class="line"><span class="lineno"> 19</span> <span class="keywordtype">char</span> file_name[] = <span class="stringliteral">"f1.h5"</span>;</div>
<div class="line"><span class="lineno"> 20</span> <span class="comment">// attribute names can be arbitrary Unicode strings</span></div>
<div class="line"><span class="lineno"> 21</span> <span class="keywordtype">char</span> attr_name[] = <span class="stringliteral">"Χαρακτηριστικό"</span>;</div>
<div class="line"><span class="lineno"> 22</span> </div>
<div class="line"><span class="lineno"> 23</span> <span class="keywordflow">if</span> ((file = <a class="code hl_function" href="group___h5_f.html#gae64b51ee9ac0781bc4ccc599d98387f4">H5Fcreate</a>(file_name, mode, <a class="code hl_define" href="_h5_ppublic_8h.html#afa85e97bfbf9bf1c58e39263846c568f">H5P_DEFAULT</a>, <a class="code hl_define" href="_h5_ppublic_8h.html#afa85e97bfbf9bf1c58e39263846c568f">H5P_DEFAULT</a>)) == <a class="code hl_define" href="_h5_ipublic_8h.html#a01eab13dccc91afd6909d74dccb780ba">H5I_INVALID_HID</a>) {</div>
<div class="line"><span class="lineno"> 24</span> ret_val = EXIT_FAILURE;</div>
<div class="line"><span class="lineno"> 25</span> <span class="keywordflow">goto</span> fail_file;</div>
<div class="line"><span class="lineno"> 26</span> }</div>
<div class="line"><span class="lineno"> 27</span> <span class="keywordflow">if</span> ((acpl = <a class="code hl_function" href="group___p_l_c_r.html#gaf1b11da01d4d45d788c45f8bc5f0cbfa">H5Pcreate</a>(<a class="code hl_define" href="_h5_ppublic_8h.html#aa0102211c679e031e2e9831b66c48a12">H5P_ATTRIBUTE_CREATE</a>)) == <a class="code hl_define" href="_h5_ipublic_8h.html#a01eab13dccc91afd6909d74dccb780ba">H5I_INVALID_HID</a>) {</div>
<div class="line"><span class="lineno"> 28</span> ret_val = EXIT_FAILURE;</div>
<div class="line"><span class="lineno"> 29</span> <span class="keywordflow">goto</span> fail_acpl;</div>
<div class="line"><span class="lineno"> 30</span> }</div>
<div class="line"><span class="lineno"> 31</span> <span class="comment">// use UTF-8 encoding for the attribute name</span></div>
<div class="line"><span class="lineno"> 32</span> <span class="keywordflow">if</span> (<a class="code hl_function" href="group___a_c_p_l.html#gad4fa8e2d17236786f770cf17eef908cc">H5Pset_char_encoding</a>(acpl, <a class="code hl_enumvalue" href="_h5_tpublic_8h.html#a03755b8370672668ddc7063add28e71aa41685667f69bf81eb7de5dd5f452e658">H5T_CSET_UTF8</a>) < 0) {</div>
<div class="line"><span class="lineno"> 33</span> ret_val = EXIT_FAILURE;</div>
<div class="line"><span class="lineno"> 34</span> <span class="keywordflow">goto</span> fail_fspace;</div>
<div class="line"><span class="lineno"> 35</span> }</div>
<div class="line"><span class="lineno"> 36</span> <span class="comment">// create a scalar (singleton) attribute</span></div>
<div class="line"><span class="lineno"> 37</span> <span class="keywordflow">if</span> ((fspace = <a class="code hl_function" href="group___h5_s.html#gabee514327cba34ca9951b24fa14fb083">H5Screate</a>(<a class="code hl_enumvalue" href="_h5_spublic_8h.html#ae53f3c6a52563646fbac9ead8ecdbf0aaf6a34a2439db8aa7bb63ed0c4aaa5eb8">H5S_SCALAR</a>)) == <a class="code hl_define" href="_h5_ipublic_8h.html#a01eab13dccc91afd6909d74dccb780ba">H5I_INVALID_HID</a>) {</div>
<div class="line"><span class="lineno"> 38</span> ret_val = EXIT_FAILURE;</div>
<div class="line"><span class="lineno"> 39</span> <span class="keywordflow">goto</span> fail_fspace;</div>
<div class="line"><span class="lineno"> 40</span> }</div>
<div class="line"><span class="lineno"> 41</span> <span class="comment">// create an attribute on the root group</span></div>
<div class="line"><span class="lineno"> 42</span> <span class="keywordflow">if</span> ((attr = <a class="code hl_function" href="group___h5_a.html#ga4f4e5248c09f689633079ed8afc0b308">H5Acreate2</a>(file, attr_name, <a class="code hl_define" href="group___p_d_t_s_t_d.html#ga8db8c9c2bcc457f9f8526c8fcb81218b">H5T_STD_I32LE</a>, fspace, acpl, <a class="code hl_define" href="_h5_ppublic_8h.html#afa85e97bfbf9bf1c58e39263846c568f">H5P_DEFAULT</a>)) ==</div>
<div class="line"><span class="lineno"> 43</span> <a class="code hl_define" href="_h5_ipublic_8h.html#a01eab13dccc91afd6909d74dccb780ba">H5I_INVALID_HID</a>) {</div>
<div class="line"><span class="lineno"> 44</span> ret_val = EXIT_FAILURE;</div>
<div class="line"><span class="lineno"> 45</span> <span class="keywordflow">goto</span> fail_attr;</div>
<div class="line"><span class="lineno"> 46</span> }</div>
<div class="line"><span class="lineno"> 47</span> </div>
<div class="line"><span class="lineno"> 48</span> <a class="code hl_function" href="group___h5_a.html#gaef4394b661e2c930879e9868e122bdda">H5Aclose</a>(attr);</div>
<div class="line"><span class="lineno"> 49</span>fail_attr:</div>
<div class="line"><span class="lineno"> 50</span> <a class="code hl_function" href="group___h5_s.html#ga2b53128a39c8f104c1c9c2a91590fcc1">H5Sclose</a>(fspace);</div>
<div class="line"><span class="lineno"> 51</span>fail_fspace:</div>
<div class="line"><span class="lineno"> 52</span> <a class="code hl_function" href="group___p_l_c_r.html#ga5dce61149211d3ef319452aa598887fb">H5Pclose</a>(acpl);</div>
<div class="line"><span class="lineno"> 53</span>fail_acpl:</div>
<div class="line"><span class="lineno"> 54</span> <a class="code hl_function" href="group___h5_f.html#gac55cd91d80822e4f8c2a7f04ea71b124">H5Fclose</a>(file);</div>
<div class="line"><span class="lineno"> 55</span>fail_file:;</div>
<div class="line"><span class="lineno"> 56</span> }</div>
</div><!-- fragment --> </td><td><div class="fragment"><div class="line"><span class="lineno"> 91</span> {</div>
<div class="line"><span class="lineno"> 92</span> __label__ fail_attr, fail_file;</div>
<div class="line"><span class="lineno"> 93</span> <a class="code hl_typedef" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> file, attr;</div>
<div class="line"><span class="lineno"> 94</span> </div>
<div class="line"><span class="lineno"> 95</span> <span class="keywordtype">unsigned</span> mode = <a class="code hl_define" href="_h5_fpublic_8h.html#a402673dec5c537b27a49a9a8bd6140b4">H5F_ACC_RDWR</a>;</div>
<div class="line"><span class="lineno"> 96</span> <span class="keywordtype">char</span> file_name[] = <span class="stringliteral">"f1.h5"</span>;</div>
<div class="line"><span class="lineno"> 97</span> <span class="keywordtype">char</span> attr_name[] = <span class="stringliteral">"Χαρακτηριστικό"</span>;</div>
<div class="line"><span class="lineno"> 98</span> <span class="keywordtype">int</span> value = 1234;</div>
<div class="line"><span class="lineno"> 99</span> </div>
<div class="line"><span class="lineno"> 100</span> <span class="keywordflow">if</span> ((file = <a class="code hl_function" href="group___h5_f.html#gaa3f4f877b9bb591f3880423ed2bf44bc">H5Fopen</a>(file_name, mode, <a class="code hl_define" href="_h5_ppublic_8h.html#afa85e97bfbf9bf1c58e39263846c568f">H5P_DEFAULT</a>)) == <a class="code hl_define" href="_h5_ipublic_8h.html#a01eab13dccc91afd6909d74dccb780ba">H5I_INVALID_HID</a>) {</div>
<div class="line"><span class="lineno"> 101</span> ret_val = EXIT_FAILURE;</div>
<div class="line"><span class="lineno"> 102</span> <span class="keywordflow">goto</span> fail_file;</div>
<div class="line"><span class="lineno"> 103</span> }</div>
<div class="line"><span class="lineno"> 104</span> <span class="keywordflow">if</span> ((attr = <a class="code hl_function" href="group___h5_a.html#ga59863b205b6d93b2145f0fbca49656f7">H5Aopen</a>(file, attr_name, <a class="code hl_define" href="_h5_ppublic_8h.html#afa85e97bfbf9bf1c58e39263846c568f">H5P_DEFAULT</a>)) == <a class="code hl_define" href="_h5_ipublic_8h.html#a01eab13dccc91afd6909d74dccb780ba">H5I_INVALID_HID</a>) {</div>
<div class="line"><span class="lineno"> 105</span> ret_val = EXIT_FAILURE;</div>
<div class="line"><span class="lineno"> 106</span> <span class="keywordflow">goto</span> fail_attr;</div>
<div class="line"><span class="lineno"> 107</span> }</div>
<div class="line"><span class="lineno"> 108</span> <span class="comment">// update the attribute value</span></div>
<div class="line"><span class="lineno"> 109</span> <span class="keywordflow">if</span> (<a class="code hl_function" href="group___h5_a.html#gab70871e205d57450c83efd9912be2b5c">H5Awrite</a>(attr, <a class="code hl_define" href="group___p_d_t_n_a_t.html#ga3cf93ffc6782be68070ef8e00f219ec2">H5T_NATIVE_INT</a>, &value) < 0)</div>
<div class="line"><span class="lineno"> 110</span> ret_val = EXIT_FAILURE;</div>
<div class="line"><span class="lineno"> 111</span> </div>
<div class="line"><span class="lineno"> 112</span> <a class="code hl_function" href="group___h5_a.html#gaef4394b661e2c930879e9868e122bdda">H5Aclose</a>(attr);</div>
<div class="line"><span class="lineno"> 113</span>fail_attr:</div>
<div class="line"><span class="lineno"> 114</span> <a class="code hl_function" href="group___h5_f.html#gac55cd91d80822e4f8c2a7f04ea71b124">H5Fclose</a>(file);</div>
<div class="line"><span class="lineno"> 115</span>fail_file:;</div>
<div class="line"><span class="lineno"> 116</span> }</div>
</div><!-- fragment --> </td></tr>
<tr>
<th>Read</th><th>Delete </th></tr>
<tr valign="top">
<td><div class="fragment"><div class="line"><span class="lineno"> 60</span> {</div>
<div class="line"><span class="lineno"> 61</span> __label__ fail_attr, fail_file;</div>
<div class="line"><span class="lineno"> 62</span> <a class="code hl_typedef" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> file, attr;</div>
<div class="line"><span class="lineno"> 63</span> </div>
<div class="line"><span class="lineno"> 64</span> <span class="keywordtype">unsigned</span> mode = <a class="code hl_define" href="_h5_fpublic_8h.html#a1c406ffa89f4acf5a332144a2683d394">H5F_ACC_RDONLY</a>;</div>
<div class="line"><span class="lineno"> 65</span> <span class="keywordtype">char</span> file_name[] = <span class="stringliteral">"f1.h5"</span>;</div>
<div class="line"><span class="lineno"> 66</span> <span class="keywordtype">char</span> attr_name[] = <span class="stringliteral">"Χαρακτηριστικό"</span>;</div>
<div class="line"><span class="lineno"> 67</span> <span class="keywordtype">int</span> value;</div>
<div class="line"><span class="lineno"> 68</span> </div>
<div class="line"><span class="lineno"> 69</span> <span class="keywordflow">if</span> ((file = <a class="code hl_function" href="group___h5_f.html#gaa3f4f877b9bb591f3880423ed2bf44bc">H5Fopen</a>(file_name, mode, <a class="code hl_define" href="_h5_ppublic_8h.html#afa85e97bfbf9bf1c58e39263846c568f">H5P_DEFAULT</a>)) == <a class="code hl_define" href="_h5_ipublic_8h.html#a01eab13dccc91afd6909d74dccb780ba">H5I_INVALID_HID</a>) {</div>
<div class="line"><span class="lineno"> 70</span> ret_val = EXIT_FAILURE;</div>
<div class="line"><span class="lineno"> 71</span> <span class="keywordflow">goto</span> fail_file;</div>
<div class="line"><span class="lineno"> 72</span> }</div>
<div class="line"><span class="lineno"> 73</span> <span class="keywordflow">if</span> ((attr = <a class="code hl_function" href="group___h5_a.html#ga59863b205b6d93b2145f0fbca49656f7">H5Aopen</a>(file, attr_name, <a class="code hl_define" href="_h5_ppublic_8h.html#afa85e97bfbf9bf1c58e39263846c568f">H5P_DEFAULT</a>)) == <a class="code hl_define" href="_h5_ipublic_8h.html#a01eab13dccc91afd6909d74dccb780ba">H5I_INVALID_HID</a>) {</div>
<div class="line"><span class="lineno"> 74</span> ret_val = EXIT_FAILURE;</div>
<div class="line"><span class="lineno"> 75</span> <span class="keywordflow">goto</span> fail_attr;</div>
<div class="line"><span class="lineno"> 76</span> }</div>
<div class="line"><span class="lineno"> 77</span> <span class="comment">// read the attribute value</span></div>
<div class="line"><span class="lineno"> 78</span> <span class="keywordflow">if</span> (<a class="code hl_function" href="group___h5_a.html#gaacb27a997f7c98e8a833d0fd63b58f1c">H5Aread</a>(attr, <a class="code hl_define" href="group___p_d_t_n_a_t.html#ga3cf93ffc6782be68070ef8e00f219ec2">H5T_NATIVE_INT</a>, &value) < 0)</div>
<div class="line"><span class="lineno"> 79</span> ret_val = EXIT_FAILURE;</div>
<div class="line"><span class="lineno"> 80</span> </div>
<div class="line"><span class="lineno"> 81</span> <span class="comment">// do something w/ the attribute value</span></div>
<div class="line"><span class="lineno"> 82</span> </div>
<div class="line"><span class="lineno"> 83</span> <a class="code hl_function" href="group___h5_a.html#gaef4394b661e2c930879e9868e122bdda">H5Aclose</a>(attr);</div>
<div class="line"><span class="lineno"> 84</span>fail_attr:</div>
<div class="line"><span class="lineno"> 85</span> <a class="code hl_function" href="group___h5_f.html#gac55cd91d80822e4f8c2a7f04ea71b124">H5Fclose</a>(file);</div>
<div class="line"><span class="lineno"> 86</span>fail_file:;</div>
<div class="line"><span class="lineno"> 87</span> }</div>
</div><!-- fragment --> </td><td><div class="fragment"><div class="line"><span class="lineno"> 120</span> {</div>
<div class="line"><span class="lineno"> 121</span> __label__ fail_attr, fail_file;</div>
<div class="line"><span class="lineno"> 122</span> <a class="code hl_typedef" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> file;</div>
<div class="line"><span class="lineno"> 123</span> </div>
<div class="line"><span class="lineno"> 124</span> <span class="keywordtype">unsigned</span> mode = <a class="code hl_define" href="_h5_fpublic_8h.html#a402673dec5c537b27a49a9a8bd6140b4">H5F_ACC_RDWR</a>;</div>
<div class="line"><span class="lineno"> 125</span> <span class="keywordtype">char</span> file_name[] = <span class="stringliteral">"f1.h5"</span>;</div>
<div class="line"><span class="lineno"> 126</span> <span class="keywordtype">char</span> attr_name[] = <span class="stringliteral">"Χαρακτηριστικό"</span>;</div>
<div class="line"><span class="lineno"> 127</span> </div>
<div class="line"><span class="lineno"> 128</span> <span class="keywordflow">if</span> ((file = <a class="code hl_function" href="group___h5_f.html#gaa3f4f877b9bb591f3880423ed2bf44bc">H5Fopen</a>(file_name, mode, <a class="code hl_define" href="_h5_ppublic_8h.html#afa85e97bfbf9bf1c58e39263846c568f">H5P_DEFAULT</a>)) == <a class="code hl_define" href="_h5_ipublic_8h.html#a01eab13dccc91afd6909d74dccb780ba">H5I_INVALID_HID</a>) {</div>
<div class="line"><span class="lineno"> 129</span> ret_val = EXIT_FAILURE;</div>
<div class="line"><span class="lineno"> 130</span> <span class="keywordflow">goto</span> fail_file;</div>
<div class="line"><span class="lineno"> 131</span> }</div>
<div class="line"><span class="lineno"> 132</span> <span class="comment">// delete the attribute</span></div>
<div class="line"><span class="lineno"> 133</span> <span class="keywordflow">if</span> (<a class="code hl_function" href="group___h5_a.html#gada9fa3d6db52329f1fd55662de6ff6ba">H5Adelete</a>(file, attr_name) < 0) {</div>
<div class="line"><span class="lineno"> 134</span> ret_val = EXIT_FAILURE;</div>
<div class="line"><span class="lineno"> 135</span> <span class="keywordflow">goto</span> fail_attr;</div>
<div class="line"><span class="lineno"> 136</span> }</div>
<div class="line"><span class="lineno"> 137</span> </div>
<div class="line"><span class="lineno"> 138</span>fail_attr:</div>
<div class="line"><span class="lineno"> 139</span> <a class="code hl_function" href="group___h5_f.html#gac55cd91d80822e4f8c2a7f04ea71b124">H5Fclose</a>(file);</div>
<div class="line"><span class="lineno"> 140</span>fail_file:;</div>
<div class="line"><span class="lineno"> 141</span> }</div>
</div><!-- fragment --> </td></tr>
</table>
<h2><a class="anchor" id="subsec_attribute_work"></a>
Working with Attributes</h2>
<h3><a class="anchor" id="subsubsec_attribute_work_struct"></a>
The Structure of an Attribute</h3>
<p>An attribute has two parts: name and value(s).</p>
<p>HDF5 attributes are sometimes discussed as name/value pairs in the form name=value.</p>
<p>An attribute's name is a null-terminated ASCII or UTF-8 character string. Each attribute attached to an object has a unique name.</p>
<p>The value portion of the attribute contains one or more data elements of the same datatype.</p>
<p>HDF5 attributes have all the characteristics of HDF5 datasets except that there is no partial I/O capability. In other words, attributes can be written and read only in full with no sub-setting.</p>
<h3><a class="anchor" id="subsubsec_attribute_work_create"></a>
Creating, Writing, and Reading Attributes</h3>
<p>If attributes are used in an HDF5 file, these functions will be employed: <a class="el" href="group___h5_a.html#ga4a76e4e5ab6eb0fd2aa7990d38d55f24">H5Acreate</a>, <a class="el" href="group___h5_a.html#gab70871e205d57450c83efd9912be2b5c">H5Awrite</a>, and <a class="el" href="group___h5_a.html#gaacb27a997f7c98e8a833d0fd63b58f1c">H5Aread</a>. <a class="el" href="group___h5_a.html#ga4a76e4e5ab6eb0fd2aa7990d38d55f24">H5Acreate</a> and <a class="el" href="group___h5_a.html#gab70871e205d57450c83efd9912be2b5c">H5Awrite</a> are used together to place the attribute in the file. If an attribute is to be used and is not currently in memory, <a class="el" href="group___h5_a.html#gaacb27a997f7c98e8a833d0fd63b58f1c">H5Aread</a> generally comes into play usually in concert with one each of the H5Aget_* and H5Aopen_* functions.</p>
<p>To create an attribute, call H5Acreate: </p><div class="fragment"><div class="line"><a class="code hl_typedef" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> <a class="code hl_define" href="group___h5_a.html#ga4a76e4e5ab6eb0fd2aa7990d38d55f24">H5Acreate</a> (<a class="code hl_typedef" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> loc_id, <span class="keyword">const</span> <span class="keywordtype">char</span> *name,</div>
<div class="line"> <a class="code hl_typedef" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> type_id, <a class="code hl_typedef" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> space_id, <a class="code hl_typedef" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> create_plist,</div>
<div class="line"> <a class="code hl_typedef" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> access_plist)</div>
<div class="ttc" id="a_h5_ipublic_8h_html_a0045db7ff9c22ad35db6ae91662e1943"><div class="ttname"><a href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a></div><div class="ttdeci">int64_t hid_t</div><div class="ttdef"><b>Definition</b> H5Ipublic.h:60</div></div>
<div class="ttc" id="agroup___h5_a_html_ga4a76e4e5ab6eb0fd2aa7990d38d55f24"><div class="ttname"><a href="group___h5_a.html#ga4a76e4e5ab6eb0fd2aa7990d38d55f24">H5Acreate</a></div><div class="ttdeci">#define H5Acreate</div><div class="ttdef"><b>Definition</b> H5version.h:868</div></div>
</div><!-- fragment --><p> loc_id identifies the object (dataset, group, or committed datatype) to which the attribute is to be attached. name, type_id, space_id, and create_plist convey, respectively, the attribute's name, datatype, dataspace, and attribute creation property list. The attribute's name must be locally unique: it must be unique within the context of the object to which it is attached.</p>
<p><a class="el" href="group___h5_a.html#ga4a76e4e5ab6eb0fd2aa7990d38d55f24">H5Acreate</a> creates the attribute in memory. The attribute does not exist in the file until <a class="el" href="group___h5_a.html#gab70871e205d57450c83efd9912be2b5c">H5Awrite</a> writes it there.</p>
<p>To write or read an attribute, call H5Awrite or H5Aread, respectively: </p><div class="fragment"><div class="line"><a class="code hl_typedef" href="_h5public_8h.html#a3b079ecf932a5c599499cf7e298af160">herr_t</a> <a class="code hl_function" href="group___h5_a.html#gab70871e205d57450c83efd9912be2b5c">H5Awrite</a> (<a class="code hl_typedef" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> attr_id, <a class="code hl_typedef" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> mem_type_id, <span class="keyword">const</span> <span class="keywordtype">void</span> *buf)</div>
<div class="line"><a class="code hl_typedef" href="_h5public_8h.html#a3b079ecf932a5c599499cf7e298af160">herr_t</a> <a class="code hl_function" href="group___h5_a.html#gaacb27a997f7c98e8a833d0fd63b58f1c">H5Aread</a> (<a class="code hl_typedef" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> attr_id, <a class="code hl_typedef" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> mem_type_id, <span class="keywordtype">void</span> *buf)</div>
<div class="ttc" id="a_h5public_8h_html_a3b079ecf932a5c599499cf7e298af160"><div class="ttname"><a href="_h5public_8h.html#a3b079ecf932a5c599499cf7e298af160">herr_t</a></div><div class="ttdeci">int herr_t</div><div class="ttdef"><b>Definition</b> H5public.h:235</div></div>
<div class="ttc" id="agroup___h5_a_html_gaacb27a997f7c98e8a833d0fd63b58f1c"><div class="ttname"><a href="group___h5_a.html#gaacb27a997f7c98e8a833d0fd63b58f1c">H5Aread</a></div><div class="ttdeci">herr_t H5Aread(hid_t attr_id, hid_t type_id, void *buf)</div><div class="ttdoc">Reads the value of an attribute.</div></div>
<div class="ttc" id="agroup___h5_a_html_gab70871e205d57450c83efd9912be2b5c"><div class="ttname"><a href="group___h5_a.html#gab70871e205d57450c83efd9912be2b5c">H5Awrite</a></div><div class="ttdeci">herr_t H5Awrite(hid_t attr_id, hid_t type_id, const void *buf)</div><div class="ttdoc">Writes data to an attribute.</div></div>
</div><!-- fragment --><p> attr_id identifies the attribute while mem_type_id identifies the in-memory datatype of the attribute data.</p>
<p><a class="el" href="group___h5_a.html#gab70871e205d57450c83efd9912be2b5c">H5Awrite</a> writes the attribute data from the buffer buf to the file. <a class="el" href="group___h5_a.html#gaacb27a997f7c98e8a833d0fd63b58f1c">H5Aread</a> reads attribute data from the file into buf.</p>
<p>The HDF5 Library converts the metadata between the in-memory datatype, mem_type_id, and the in-file datatype, defined when the attribute was created, without user intervention.</p>
<h3><a class="anchor" id="subsubsec_attribute_work_access"></a>
Accessing Attributes by Name or Index</h3>
<p>Attributes can be accessed by name or index value. The use of an index value makes it possible to iterate through all of the attributes associated with a given object.</p>
<p>To access an attribute by its name, use the <a class="el" href="group___h5_a.html#gadb49a0b5b9798d2e944d877adba8ae10">H5Aopen_by_name</a> function. <a class="el" href="group___h5_a.html#gadb49a0b5b9798d2e944d877adba8ae10">H5Aopen_by_name</a> returns an attribute identifier that can then be used by any function that must access an attribute such as <a class="el" href="group___h5_a.html#gaacb27a997f7c98e8a833d0fd63b58f1c">H5Aread</a>. Use the function <a class="el" href="group___h5_a.html#ga05e195aabab8c623b1c52009aeb99674">H5Aget_name</a> to determine an attribute's name.</p>
<p>To access an attribute by its index value, use the <a class="el" href="group___h5_a.html#gab1451cdff4f77dcf9feaee83c8179b2d">H5Aopen_by_idx</a> function. To determine an attribute index value when it is not already known, use the H5Oget_info function. <a class="el" href="group___h5_a.html#gab1451cdff4f77dcf9feaee83c8179b2d">H5Aopen_by_idx</a> is generally used in the course of opening several attributes for later access. Use <a class="el" href="group___h5_a.html#gab9dcfc543cd4282f32b8ea19e08ffa6c">H5Aiterate</a> if the intent is to perform the same operation on every attribute attached to an object.</p>
<h3><a class="anchor" id="subsubsec_attribute_work_info"></a>
Obtaining Information Regarding an Object's Attributes</h3>
<p>In the course of working with HDF5 attributes, one may need to obtain any of several pieces of information: </p><ul>
<li>An attribute name </li>
<li>The dataspace of an attribute </li>
<li>The datatype of an attribute </li>
<li>The number of attributes attached to an object</li>
</ul>
<p>To obtain an attribute's name, call H5Aget_name with an attribute identifier, attr_id: </p><div class="fragment"><div class="line"><a class="code hl_typedef" href="_h5public_8h.html#af629ed855824cf5955b54529adf78ad6">ssize_t</a> <a class="code hl_function" href="group___h5_a.html#ga05e195aabab8c623b1c52009aeb99674">H5Aget_name</a> (<a class="code hl_typedef" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> attr_id, <span class="keywordtype">size_t</span> buf_size, <span class="keywordtype">char</span> *buf)</div>
<div class="ttc" id="a_h5public_8h_html_af629ed855824cf5955b54529adf78ad6"><div class="ttname"><a href="_h5public_8h.html#af629ed855824cf5955b54529adf78ad6">ssize_t</a></div><div class="ttdeci">int ssize_t</div><div class="ttdef"><b>Definition</b> H5public.h:279</div></div>
<div class="ttc" id="agroup___h5_a_html_ga05e195aabab8c623b1c52009aeb99674"><div class="ttname"><a href="group___h5_a.html#ga05e195aabab8c623b1c52009aeb99674">H5Aget_name</a></div><div class="ttdeci">ssize_t H5Aget_name(hid_t attr_id, size_t buf_size, char *buf)</div><div class="ttdoc">Gets an attribute name.</div></div>
</div><!-- fragment --><p> As with other attribute functions, attr_id identifies the attribute; buf_size defines the size of the buffer; and buf is the buffer to which the attribute's name will be read.</p>
<p>If the length of the attribute name, and hence the value required for buf_size, is unknown, a first call to <a class="el" href="group___h5_a.html#ga05e195aabab8c623b1c52009aeb99674">H5Aget_name</a> will return that size. If the value of buf_size used in that first call is too small, the name will simply be truncated in buf. A second <a class="el" href="group___h5_a.html#ga05e195aabab8c623b1c52009aeb99674">H5Aget_name</a> call can then be used to retrieve the name in an appropriately-sized buffer.</p>
<p>To determine the dataspace or datatype of an attribute, call <a class="el" href="group___h5_a.html#ga9e21e544119d03f9342530b45a71d74d">H5Aget_space</a> or <a class="el" href="group___h5_a.html#ga0b070b714b2e535df2e1cb3005026a44">H5Aget_type</a>, respectively: </p><div class="fragment"><div class="line"><a class="code hl_typedef" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> <a class="code hl_function" href="group___h5_a.html#ga9e21e544119d03f9342530b45a71d74d">H5Aget_space</a> (<a class="code hl_typedef" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> attr_id) <a class="code hl_typedef" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> <a class="code hl_function" href="group___h5_a.html#ga0b070b714b2e535df2e1cb3005026a44">H5Aget_type</a> (<a class="code hl_typedef" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> attr_id) </div>
<div class="ttc" id="agroup___h5_a_html_ga0b070b714b2e535df2e1cb3005026a44"><div class="ttname"><a href="group___h5_a.html#ga0b070b714b2e535df2e1cb3005026a44">H5Aget_type</a></div><div class="ttdeci">hid_t H5Aget_type(hid_t attr_id)</div><div class="ttdoc">Gets an attribute's datatype.</div></div>
<div class="ttc" id="agroup___h5_a_html_ga9e21e544119d03f9342530b45a71d74d"><div class="ttname"><a href="group___h5_a.html#ga9e21e544119d03f9342530b45a71d74d">H5Aget_space</a></div><div class="ttdeci">hid_t H5Aget_space(hid_t attr_id)</div><div class="ttdoc">Gets a copy of the dataspace for an attribute.</div></div>
</div><!-- fragment --><p> <a class="el" href="group___h5_a.html#ga9e21e544119d03f9342530b45a71d74d">H5Aget_space</a> returns the dataspace identifier for the attribute attr_id. <a class="el" href="group___h5_a.html#ga0b070b714b2e535df2e1cb3005026a44">H5Aget_type</a> returns the datatype identifier for the attribute attr_id.</p>
<p>To determine the number of attributes attached to an object, use the <a class="el" href="group___h5_o.html#gaf4f302a33faba9e1c2b5f64c62ca4ed5">H5Oget_info</a> function. The function signature is below. </p><div class="fragment"><div class="line"><a class="code hl_typedef" href="_h5public_8h.html#a3b079ecf932a5c599499cf7e298af160">herr_t</a> <a class="code hl_define" href="group___h5_o.html#gaf4f302a33faba9e1c2b5f64c62ca4ed5">H5Oget_info</a>( <a class="code hl_typedef" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> object_id, <a class="code hl_define" href="_h5version_8h.html#a5f76b0cdd6d68d61f11e46d4f06e50d4">H5O_info_t</a> *object_info ) </div>
<div class="ttc" id="a_h5version_8h_html_a5f76b0cdd6d68d61f11e46d4f06e50d4"><div class="ttname"><a href="_h5version_8h.html#a5f76b0cdd6d68d61f11e46d4f06e50d4">H5O_info_t</a></div><div class="ttdeci">#define H5O_info_t</div><div class="ttdef"><b>Definition</b> H5version.h:1310</div></div>
<div class="ttc" id="agroup___h5_o_html_gaf4f302a33faba9e1c2b5f64c62ca4ed5"><div class="ttname"><a href="group___h5_o.html#gaf4f302a33faba9e1c2b5f64c62ca4ed5">H5Oget_info</a></div><div class="ttdeci">#define H5Oget_info</div><div class="ttdef"><b>Definition</b> H5version.h:1097</div></div>
</div><!-- fragment --><p> The number of attributes will be returned in the object_info buffer. This is generally the preferred first step in determining attribute index values. If the call returns N, the attributes attached to the object object_id have index values of 0 through N-1.</p>
<h3><a class="anchor" id="subsubsec_attribute_work_iterate"></a>
Iterating across an Object's Attributes</h3>
<p>It is sometimes useful to be able to perform the identical operation across all of the attributes attached to an object. At the simplest level, you might just want to open each attribute. At a higher level, you might wish to perform a rather complex operation on each attribute as you iterate across the set.</p>
<p>To iterate an operation across the attributes attached to an object, one must make a series of calls to <a class="el" href="group___h5_a.html#gab9dcfc543cd4282f32b8ea19e08ffa6c">H5Aiterate</a> </p><div class="fragment"><div class="line"><a class="code hl_typedef" href="_h5public_8h.html#a3b079ecf932a5c599499cf7e298af160">herr_t</a> <a class="code hl_define" href="group___h5_a.html#gab9dcfc543cd4282f32b8ea19e08ffa6c">H5Aiterate</a> (<a class="code hl_typedef" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> obj_id, <a class="code hl_enumeration" href="_h5public_8h.html#a8203c78e10ab2d89d8bce688a31afad3">H5_index_t</a> index_type,</div>
<div class="line"> <a class="code hl_enumeration" href="_h5public_8h.html#a6a6ddd1504d1ed61939d46d91d9441b9">H5_iter_order_t</a> order, <a class="code hl_typedef" href="_h5public_8h.html#a7f81cce70fb546af88da24d9285d3c1c">hsize_t</a> *n, <a class="code hl_typedef" href="_h5_apublic_8h.html#a28fef0ded9a6c0eb12334c0d15dc3e74">H5A_operator2_t</a> op,</div>
<div class="line"> <span class="keywordtype">void</span> *op_data)</div>
<div class="ttc" id="a_h5_apublic_8h_html_a28fef0ded9a6c0eb12334c0d15dc3e74"><div class="ttname"><a href="_h5_apublic_8h.html#a28fef0ded9a6c0eb12334c0d15dc3e74">H5A_operator2_t</a></div><div class="ttdeci">herr_t(* H5A_operator2_t)(hid_t location_id, const char *attr_name, const H5A_info_t *ainfo, void *op_data)</div><div class="ttdef"><b>Definition</b> H5Apublic.h:55</div></div>
<div class="ttc" id="a_h5public_8h_html_a6a6ddd1504d1ed61939d46d91d9441b9"><div class="ttname"><a href="_h5public_8h.html#a6a6ddd1504d1ed61939d46d91d9441b9">H5_iter_order_t</a></div><div class="ttdeci">H5_iter_order_t</div><div class="ttdef"><b>Definition</b> H5public.h:344</div></div>
<div class="ttc" id="a_h5public_8h_html_a7f81cce70fb546af88da24d9285d3c1c"><div class="ttname"><a href="_h5public_8h.html#a7f81cce70fb546af88da24d9285d3c1c">hsize_t</a></div><div class="ttdeci">uint64_t hsize_t</div><div class="ttdef"><b>Definition</b> H5public.h:297</div></div>
<div class="ttc" id="a_h5public_8h_html_a8203c78e10ab2d89d8bce688a31afad3"><div class="ttname"><a href="_h5public_8h.html#a8203c78e10ab2d89d8bce688a31afad3">H5_index_t</a></div><div class="ttdeci">H5_index_t</div><div class="ttdef"><b>Definition</b> H5public.h:367</div></div>
<div class="ttc" id="agroup___h5_a_html_gab9dcfc543cd4282f32b8ea19e08ffa6c"><div class="ttname"><a href="group___h5_a.html#gab9dcfc543cd4282f32b8ea19e08ffa6c">H5Aiterate</a></div><div class="ttdeci">#define H5Aiterate</div><div class="ttdef"><b>Definition</b> H5version.h:879</div></div>
</div><!-- fragment --><p> <a class="el" href="group___h5_a.html#gab9dcfc543cd4282f32b8ea19e08ffa6c">H5Aiterate</a> successively marches across all of the attributes attached to the object specified in loc_id, performing the operation(s) specified in op_func with the data specified in op_data on each attribute.</p>
<p>When <a class="el" href="group___h5_a.html#gab9dcfc543cd4282f32b8ea19e08ffa6c">H5Aiterate</a> is called, index contains the index of the attribute to be accessed in this call. When <a class="el" href="group___h5_a.html#gab9dcfc543cd4282f32b8ea19e08ffa6c">H5Aiterate</a> returns, index will contain the index of the next attribute. If the returned index is the null pointer, then all attributes have been processed, and the iterative process is complete.</p>
<p>op_func is a user-defined operation that adheres to the <a class="el" href="_h5version_8h.html#a04b85ea47893cb5538a75130533900a9">H5A_operator_t</a> prototype. This prototype and certain requirements imposed on the operator's behavior are described in the <a class="el" href="group___h5_a.html#gab9dcfc543cd4282f32b8ea19e08ffa6c">H5Aiterate</a> entry in the <a class="el" href="_r_m.html">HDF5 Reference Manual</a>.</p>
<p>op_data is also user-defined to meet the requirements of op_func. Beyond providing a parameter with which to pass this data, HDF5 provides no tools for its management and imposes no restrictions.</p>
<h3><a class="anchor" id="subsubsec_attribute_work_delete"></a>
Deleting an Attribute</h3>
<p>Once an attribute has outlived its usefulness or is no longer appropriate, it may become necessary to delete it.</p>
<p>To delete an attribute, call <a class="el" href="group___h5_a.html#gada9fa3d6db52329f1fd55662de6ff6ba">H5Adelete</a> </p><div class="fragment"><div class="line"><a class="code hl_typedef" href="_h5public_8h.html#a3b079ecf932a5c599499cf7e298af160">herr_t</a> <a class="code hl_function" href="group___h5_a.html#gada9fa3d6db52329f1fd55662de6ff6ba">H5Adelete</a> (<a class="code hl_typedef" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> loc_id, <span class="keyword">const</span> <span class="keywordtype">char</span> *name)</div>
<div class="ttc" id="agroup___h5_a_html_gada9fa3d6db52329f1fd55662de6ff6ba"><div class="ttname"><a href="group___h5_a.html#gada9fa3d6db52329f1fd55662de6ff6ba">H5Adelete</a></div><div class="ttdeci">herr_t H5Adelete(hid_t loc_id, const char *attr_name)</div><div class="ttdoc">Deletes an attribute from a specified location.</div></div>
</div><!-- fragment --><p> <a class="el" href="group___h5_a.html#gada9fa3d6db52329f1fd55662de6ff6ba">H5Adelete</a> removes the attribute name from the group, dataset, or committed datatype specified in loc_id.</p>
<p><a class="el" href="group___h5_a.html#gada9fa3d6db52329f1fd55662de6ff6ba">H5Adelete</a> must not be called if there are any open attribute identifiers on the object loc_id. Such a call can cause the internal attribute indexes to change; future writes to an open attribute would then produce unintended results.</p>
<h3><a class="anchor" id="subsubsec_attribute_work_close"></a>
Closing an Attribute</h3>
<p>As is the case with all HDF5 objects, once access to an attribute it is no longer needed, that attribute must be closed. It is best practice to close it as soon as practicable; it is mandatory that it be closed prior to the H5close call closing the HDF5 Library.</p>
<p>To close an attribute, call <a class="el" href="group___h5_a.html#gaef4394b661e2c930879e9868e122bdda">H5Aclose</a> </p><div class="fragment"><div class="line"><a class="code hl_typedef" href="_h5public_8h.html#a3b079ecf932a5c599499cf7e298af160">herr_t</a> <a class="code hl_function" href="group___h5_a.html#gaef4394b661e2c930879e9868e122bdda">H5Aclose</a> (<a class="code hl_typedef" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> attr_id)</div>
<div class="ttc" id="agroup___h5_a_html_gaef4394b661e2c930879e9868e122bdda"><div class="ttname"><a href="group___h5_a.html#gaef4394b661e2c930879e9868e122bdda">H5Aclose</a></div><div class="ttdeci">herr_t H5Aclose(hid_t attr_id)</div><div class="ttdoc">Closes the specified attribute.</div></div>
</div><!-- fragment --><p> <a class="el" href="group___h5_a.html#gaef4394b661e2c930879e9868e122bdda">H5Aclose</a> closes the specified attribute by terminating access to its identifier, attr_id.</p>
<h2><a class="anchor" id="subsec_attribute_special"></a>
Special Issues</h2>
<p>Some special issues for attributes are discussed below.</p>
<h4>Large Numbers of Attributes Stored in Dense Attribute Storage</h4>
<p>The dense attribute storage scheme was added in version 1.8 so that datasets, groups, and committed datatypes that have large numbers of attributes could be processed more quickly.</p>
<p>Attributes start out being stored in an object's header. This is known as compact storage. For more information, see "Storage Strategies."</p>
<p>As the number of attributes grows, attribute-related performance slows. To improve performance, dense attribute storage can be initiated with the H5Pset_attr_phase_change function. See the HDF5 Reference Manual for more information.</p>
<p>When dense attribute storage is enabled, a threshold is defined for the number of attributes kept in compact storage. When the number is exceeded, the library moves all of the attributes into dense storage at another location. The library handles the movement of attributes and the pointers between the locations automatically. If some of the attributes are deleted so that the number falls below the threshold, then the attributes are moved back to compact storage by the library.</p>
<p>The improvements in performance from using dense attribute storage are the result of holding attributes in a heap and indexing the heap with a B-tree.</p>
<p>Note that there are some disadvantages to using dense attribute storage. One is that this is a new feature. Datasets, groups, and committed datatypes that use dense storage cannot be read by applications built with earlier versions of the library. Another disadvantage is that attributes in dense storage cannot be compressed.</p>
<h4>Large Attributes Stored in Dense Attribute Storage</h4>
<p>We generally consider the maximum size of an attribute to be 64K bytes. The library has two ways of storing attributes larger than 64K bytes: in dense attribute storage or in a separate dataset. Using dense attribute storage is described in this section, and storing in a separate dataset is described in the next section.</p>
<p>To use dense attribute storage to store large attributes, set the number of attributes that will be stored in compact storage to 0 with the H5Pset_attr_phase_change function. This will force all attributes to be put into dense attribute storage and will avoid the 64KB size limitation for a single attribute in compact attribute storage.</p>
<p>The example code below illustrates how to create a large attribute that will be kept in dense storage.</p>
<table class="doxtable">
<tr>
<th>Create </th></tr>
<tr valign="top">
<td><div class="fragment"><div class="line"><span class="lineno"> 14</span> {</div>
<div class="line"><span class="lineno"> 15</span> __label__ fail_acpl, fail_attr, fail_file;</div>
<div class="line"><span class="lineno"> 16</span> <a class="code hl_typedef" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> file, acpl, fspace, attr;</div>
<div class="line"><span class="lineno"> 17</span> </div>
<div class="line"><span class="lineno"> 18</span> <span class="keywordtype">unsigned</span> mode = <a class="code hl_define" href="_h5_fpublic_8h.html#a5a2d6726f9ad8d2bca8df2b817e5ad6a">H5F_ACC_TRUNC</a>;</div>
<div class="line"><span class="lineno"> 19</span> <span class="keywordtype">char</span> file_name[] = <span class="stringliteral">"f1.h5"</span>;</div>
<div class="line"><span class="lineno"> 20</span> <span class="comment">// attribute names can be arbitrary Unicode strings</span></div>
<div class="line"><span class="lineno"> 21</span> <span class="keywordtype">char</span> attr_name[] = <span class="stringliteral">"Χαρακτηριστικό"</span>;</div>
<div class="line"><span class="lineno"> 22</span> </div>
<div class="line"><span class="lineno"> 23</span> <span class="keywordflow">if</span> ((file = <a class="code hl_function" href="group___h5_f.html#gae64b51ee9ac0781bc4ccc599d98387f4">H5Fcreate</a>(file_name, mode, <a class="code hl_define" href="_h5_ppublic_8h.html#afa85e97bfbf9bf1c58e39263846c568f">H5P_DEFAULT</a>, <a class="code hl_define" href="_h5_ppublic_8h.html#afa85e97bfbf9bf1c58e39263846c568f">H5P_DEFAULT</a>)) == <a class="code hl_define" href="_h5_ipublic_8h.html#a01eab13dccc91afd6909d74dccb780ba">H5I_INVALID_HID</a>) {</div>
<div class="line"><span class="lineno"> 24</span> ret_val = EXIT_FAILURE;</div>
<div class="line"><span class="lineno"> 25</span> <span class="keywordflow">goto</span> fail_file;</div>
<div class="line"><span class="lineno"> 26</span> }</div>
<div class="line"><span class="lineno"> 27</span> <span class="keywordflow">if</span> ((acpl = <a class="code hl_function" href="group___p_l_c_r.html#gaf1b11da01d4d45d788c45f8bc5f0cbfa">H5Pcreate</a>(<a class="code hl_define" href="_h5_ppublic_8h.html#aa0102211c679e031e2e9831b66c48a12">H5P_ATTRIBUTE_CREATE</a>)) == <a class="code hl_define" href="_h5_ipublic_8h.html#a01eab13dccc91afd6909d74dccb780ba">H5I_INVALID_HID</a>) {</div>
<div class="line"><span class="lineno"> 28</span> ret_val = EXIT_FAILURE;</div>
<div class="line"><span class="lineno"> 29</span> <span class="keywordflow">goto</span> fail_acpl;</div>
<div class="line"><span class="lineno"> 30</span> }</div>
<div class="line"><span class="lineno"> 31</span> <span class="comment">// use UTF-8 encoding for the attribute name</span></div>
<div class="line"><span class="lineno"> 32</span> <span class="keywordflow">if</span> (<a class="code hl_function" href="group___a_c_p_l.html#gad4fa8e2d17236786f770cf17eef908cc">H5Pset_char_encoding</a>(acpl, <a class="code hl_enumvalue" href="_h5_tpublic_8h.html#a03755b8370672668ddc7063add28e71aa41685667f69bf81eb7de5dd5f452e658">H5T_CSET_UTF8</a>) < 0) {</div>
<div class="line"><span class="lineno"> 33</span> ret_val = EXIT_FAILURE;</div>
<div class="line"><span class="lineno"> 34</span> <span class="keywordflow">goto</span> fail_fspace;</div>
<div class="line"><span class="lineno"> 35</span> }</div>
<div class="line"><span class="lineno"> 36</span> <span class="comment">// create a scalar (singleton) attribute</span></div>
<div class="line"><span class="lineno"> 37</span> <span class="keywordflow">if</span> ((fspace = <a class="code hl_function" href="group___h5_s.html#gabee514327cba34ca9951b24fa14fb083">H5Screate</a>(<a class="code hl_enumvalue" href="_h5_spublic_8h.html#ae53f3c6a52563646fbac9ead8ecdbf0aaf6a34a2439db8aa7bb63ed0c4aaa5eb8">H5S_SCALAR</a>)) == <a class="code hl_define" href="_h5_ipublic_8h.html#a01eab13dccc91afd6909d74dccb780ba">H5I_INVALID_HID</a>) {</div>
<div class="line"><span class="lineno"> 38</span> ret_val = EXIT_FAILURE;</div>
<div class="line"><span class="lineno"> 39</span> <span class="keywordflow">goto</span> fail_fspace;</div>
<div class="line"><span class="lineno"> 40</span> }</div>
<div class="line"><span class="lineno"> 41</span> <span class="comment">// create an attribute on the root group</span></div>
<div class="line"><span class="lineno"> 42</span> <span class="keywordflow">if</span> ((attr = <a class="code hl_function" href="group___h5_a.html#ga4f4e5248c09f689633079ed8afc0b308">H5Acreate2</a>(file, attr_name, <a class="code hl_define" href="group___p_d_t_s_t_d.html#ga8db8c9c2bcc457f9f8526c8fcb81218b">H5T_STD_I32LE</a>, fspace, acpl, <a class="code hl_define" href="_h5_ppublic_8h.html#afa85e97bfbf9bf1c58e39263846c568f">H5P_DEFAULT</a>)) ==</div>
<div class="line"><span class="lineno"> 43</span> <a class="code hl_define" href="_h5_ipublic_8h.html#a01eab13dccc91afd6909d74dccb780ba">H5I_INVALID_HID</a>) {</div>
<div class="line"><span class="lineno"> 44</span> ret_val = EXIT_FAILURE;</div>
<div class="line"><span class="lineno"> 45</span> <span class="keywordflow">goto</span> fail_attr;</div>
<div class="line"><span class="lineno"> 46</span> }</div>
<div class="line"><span class="lineno"> 47</span> </div>
<div class="line"><span class="lineno"> 48</span> <a class="code hl_function" href="group___h5_a.html#gaef4394b661e2c930879e9868e122bdda">H5Aclose</a>(attr);</div>
<div class="line"><span class="lineno"> 49</span>fail_attr:</div>
<div class="line"><span class="lineno"> 50</span> <a class="code hl_function" href="group___h5_s.html#ga2b53128a39c8f104c1c9c2a91590fcc1">H5Sclose</a>(fspace);</div>
<div class="line"><span class="lineno"> 51</span>fail_fspace:</div>
<div class="line"><span class="lineno"> 52</span> <a class="code hl_function" href="group___p_l_c_r.html#ga5dce61149211d3ef319452aa598887fb">H5Pclose</a>(acpl);</div>
<div class="line"><span class="lineno"> 53</span>fail_acpl:</div>
<div class="line"><span class="lineno"> 54</span> <a class="code hl_function" href="group___h5_f.html#gac55cd91d80822e4f8c2a7f04ea71b124">H5Fclose</a>(file);</div>
<div class="line"><span class="lineno"> 55</span>fail_file:;</div>
<div class="line"><span class="lineno"> 56</span> }</div>
</div><!-- fragment --> </td></tr>
</table>
<h4>Large Attributes Stored in a Separate Dataset</h4>
<p>In addition to dense attribute storage (see above), a large attribute can be stored in a separate dataset. In the figure below, DatasetA holds an attribute that is too large for the object header in Dataset1. By putting a pointer to DatasetA as an attribute in Dataset1, the attribute becomes available to those working with Dataset1. This way of handling large attributes can be used in situations where backward compatibility is important and where compression is important. Applications built with versions before 1.8.x can read large attributes stored in separate datasets. Datasets can be compressed while attributes cannot. </p><table class="doxtable">
<tr>
<td><div class="image">
<img src="Shared_Attribute.jpg" alt=""/>
<div class="caption">
A large or shared HDF5 attribute and its associated dataset(s)</div></div>
</td></tr>
</table>
<p>Note: In the figure above, DatasetA is an attribute of Dataset1 that is too large to store in Dataset1's header. DatasetA is associated with Dataset1 by means of an object reference pointer attached as an attribute to Dataset1. The attribute in DatasetA can be shared among multiple datasets by means of additional object reference pointers attached to additional datasets.</p>
<h4>Shared Attributes</h4>
<p>Attributes written and managed through the <a class="el" href="group___h5_a.html">Attributes (H5A)</a> interface cannot be shared. If shared attributes are required, they must be handled in the manner described above for large attributes and illustrated in the figure above.</p>
<h4>Attribute Names</h4>
<p>While any ASCII or UTF-8 character may be used in the name given to an attribute, it is usually wise to avoid the following kinds of characters: </p><ul>
<li>Commonly used separators or delimiters such as slash, backslash, colon, and semi-colon (\, /, :, ;) </li>
<li>Escape characters </li>
<li>Wild cards such as asterisk and question mark (*, ?) NULL can be used within a name, but HDF5 names are terminated with a NULL: whatever comes after the NULL will be ignored by HDF5.</li>
</ul>
<p>The use of ASCII or UTF-8 characters is determined by the character encoding property. See <a class="el" href="group___a_c_p_l.html#gad4fa8e2d17236786f770cf17eef908cc" title="Sets the character encoding used to encode link and attribute names.">H5Pset_char_encoding</a> in the <a class="el" href="_r_m.html">HDF5 Reference Manual</a>.</p>
<h4>No Special I/O or Storage</h4>
<p>HDF5 attributes have all the characteristics of HDF5 datasets except the following: </p><ul>
<li>Attributes are written and read only in full: there is no provision for partial I/O or sub-setting </li>
<li>No special storage capability is provided for attributes: there is no compression or chunking, and attributes are not extendable</li>
</ul>
<p>Previous Chapter <a class="el" href="_h5_s__u_g.html#sec_dataspace">HDF5 Dataspaces and Partial I/O</a> - Next Chapter <a class="el" href="_h5_e__u_g.html#sec_error">HDF5 Error Handling</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>
|
