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
|
<!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: Creating an HDF5 File</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.fe5d0d5</span>
</div>
<div id="projectbrief">API Reference</div>
</td>
<td> <div id="MSearchBox" class="MSearchBoxInactive">
<span class="left">
<span id="MSearchSelect" onmouseover="return searchBox.OnSearchSelectShow()" onmouseout="return searchBox.OnSearchSelectHide()"> </span>
<input type="text" id="MSearchField" value="" placeholder="Search" accesskey="S"
onfocus="searchBox.OnSearchFieldFocus(true)"
onblur="searchBox.OnSearchFieldFocus(false)"
onkeyup="searchBox.OnSearchFieldChange(event)"/>
</span><span class="right">
<a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.svg" alt=""/></a>
</span>
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.10.0 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt MIT */
var searchBox = new SearchBox("searchBox", "search/",'.html');
/* @license-end */
</script>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
<div id="nav-tree">
<div id="nav-tree-contents">
<div id="nav-sync" class="sync"></div>
</div>
</div>
<div id="splitbar" style="-moz-user-select:none;"
class="ui-resizable-handle">
</div>
</div>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt MIT */
$(function(){initNavTree('_l_b_file_create.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">Creating an HDF5 File</div></div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>Navigate back: <a class="el" href="index.html">Main</a> / <a class="el" href="_getting_started.html">Getting Started with HDF5</a> / <a class="el" href="_learn_basics.html">Learning the Basics</a> </p><hr />
<p>An HDF5 file is a binary file containing scientific data and supporting metadata. </p>
<h1><a class="anchor" id="secLBFileCreate"></a>
HDF5 File Access</h1>
<p>To create an HDF5 file, an application must specify not only a file name, but a file access mode, a file creation property list, and a file access property list. These terms are described below: </p><ul>
<li>
<b>File access mode:</b><br />
When creating a file, the file access mode specifies the action to take if the file already exists: <ul>
<li>
<a class="el" href="_h5_fpublic_8h.html#a5a2d6726f9ad8d2bca8df2b817e5ad6a">H5F_ACC_TRUNC</a> specifies that if the file already exists, the current contents will be deleted so that the application can rewrite the file with new data. </li>
<li>
<a class="el" href="_h5_fpublic_8h.html#a7a47250dc1435705233dca7297ba3d90">H5F_ACC_EXCL</a> specifies that the open will fail if the file already exists. If the file does not already exist, the file access parameter is ignored. </li>
</ul>
In either case, the application has both read and write access to the successfully created file. <br />
Note that there are two different access modes for opening existing files: <ul>
<li>
<a class="el" href="_h5_fpublic_8h.html#a1c406ffa89f4acf5a332144a2683d394">H5F_ACC_RDONLY</a> specifies that the application has read access but will not be allowed to write any data. </li>
<li>
<a class="el" href="_h5_fpublic_8h.html#a402673dec5c537b27a49a9a8bd6140b4">H5F_ACC_RDWR</a> specifies that the application has read and write access. </li>
</ul>
</li>
<li>
<b>File creation property list:</b><br />
The file creation property list is used to control the file metadata. File metadata contains information about the size of the user-block*, the size of various file data structures used by the HDF5 library, etc. In this tutorial, the default file creation property list, <a class="el" href="_h5_ppublic_8h.html#afa85e97bfbf9bf1c58e39263846c568f">H5P_DEFAULT</a>, is used.<br />
The user-block is a fixed-length block of data located at the beginning of the file which is ignored by the HDF5 library. The user-block may be used to store any data or information found to be useful to applications. </li>
<li>
<b>File access property list:</b><br />
The file access property list is used to control different methods of performing I/O on files. It also can be used to control how a file is closed (whether or not to delay the actual file close until all objects in a file are closed). The default file access property list, <a class="el" href="_h5_ppublic_8h.html#afa85e97bfbf9bf1c58e39263846c568f">H5P_DEFAULT</a>, is used in this tutorial. </li>
</ul>
<p>Please refer to the <a class="el" href="_h5_f__u_g.html#sec_file">The HDF5 File</a> section of the <a class="el" href="_u_g.html">HDF5 User Guide</a> and <a class="el" href="group___h5_f.html">Files (H5F)</a> section in the <a class="el" href="_r_m.html">HDF5 Reference Manual</a> for detailed information regarding file access/creation property lists and access modes.</p>
<p>The steps to create and close an HDF5 file are as follows: </p><ol>
<li>
Specify the file creation and access property lists, if necessary. </li>
<li>
Create the file. </li>
<li>
Close the file, and if necessary, close the property lists. </li>
</ol>
<h1><a class="anchor" id="secLBFileExample"></a>
Programming Example</h1>
<h2><a class="anchor" id="subsecLBFileExampleDesc"></a>
Description</h2>
<p>The following example code demonstrates how to create and close an HDF5 file.</p>
<p><em>C</em> </p><div class="fragment"><div class="line"><span class="preprocessor">#include "hdf5.h"</span></div>
<div class="line"><span class="preprocessor"> #define FILE "file.h5"</span></div>
<div class="line"> </div>
<div class="line"> <span class="keywordtype">int</span> main() {</div>
<div class="line"> </div>
<div class="line"> <a class="code hl_typedef" href="_h5_ipublic_8h.html#a0045db7ff9c22ad35db6ae91662e1943">hid_t</a> file_id; <span class="comment">/* file identifier */</span></div>
<div class="line"> <a class="code hl_typedef" href="_h5public_8h.html#a3b079ecf932a5c599499cf7e298af160">herr_t</a> status;</div>
<div class="line"> </div>
<div class="line"> <span class="comment">/* Create a new file using default properties. */</span></div>
<div class="line"> file_id = <a class="code hl_function" href="group___h5_f.html#gae64b51ee9ac0781bc4ccc599d98387f4">H5Fcreate</a>(FILE, <a class="code hl_define" href="_h5_fpublic_8h.html#a5a2d6726f9ad8d2bca8df2b817e5ad6a">H5F_ACC_TRUNC</a>, <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>);</div>
<div class="line"> </div>
<div class="line"> <span class="comment">/* Terminate access to the file. */</span></div>
<div class="line"> status = <a class="code hl_function" href="group___h5_f.html#gac55cd91d80822e4f8c2a7f04ea71b124">H5Fclose</a>(file_id); </div>
<div class="line"> }</div>
<div class="ttc" id="a_h5_fpublic_8h_html_a5a2d6726f9ad8d2bca8df2b817e5ad6a"><div class="ttname"><a href="_h5_fpublic_8h.html#a5a2d6726f9ad8d2bca8df2b817e5ad6a">H5F_ACC_TRUNC</a></div><div class="ttdeci">#define H5F_ACC_TRUNC</div><div class="ttdef"><b>Definition</b> H5Fpublic.h:50</div></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="a_h5_ppublic_8h_html_afa85e97bfbf9bf1c58e39263846c568f"><div class="ttname"><a href="_h5_ppublic_8h.html#afa85e97bfbf9bf1c58e39263846c568f">H5P_DEFAULT</a></div><div class="ttdeci">#define H5P_DEFAULT</div><div class="ttdef"><b>Definition</b> H5Ppublic.h:102</div></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_f_html_gac55cd91d80822e4f8c2a7f04ea71b124"><div class="ttname"><a href="group___h5_f.html#gac55cd91d80822e4f8c2a7f04ea71b124">H5Fclose</a></div><div class="ttdeci">herr_t H5Fclose(hid_t file_id)</div><div class="ttdoc">Terminates access to an HDF5 file.</div></div>
<div class="ttc" id="agroup___h5_f_html_gae64b51ee9ac0781bc4ccc599d98387f4"><div class="ttname"><a href="group___h5_f.html#gae64b51ee9ac0781bc4ccc599d98387f4">H5Fcreate</a></div><div class="ttdeci">hid_t H5Fcreate(const char *filename, unsigned flags, hid_t fcpl_id, hid_t fapl_id)</div><div class="ttdoc">Creates an HDF5 file.</div></div>
</div><!-- fragment --><p><em>Fortran</em> </p><div class="fragment"><div class="line"> PROGRAM FILEEXAMPLE</div>
<div class="line"> </div>
<div class="line"> USE HDF5 ! This <span class="keyword">module</span> contains all necessary modules </div>
<div class="line"> </div>
<div class="line"> IMPLICIT NONE</div>
<div class="line"> </div>
<div class="line"> CHARACTER(LEN=8), PARAMETER :: filename = "filef.h5" ! File name</div>
<div class="line"> INTEGER(HID_T) :: file_id ! File identifier</div>
<div class="line"> </div>
<div class="line"> INTEGER :: error ! Error flag</div>
<div class="line"> </div>
<div class="line">!</div>
<div class="line">! Initialize FORTRAN interface.</div>
<div class="line">!</div>
<div class="line"> CALL h5open_f (error)</div>
<div class="line"> !</div>
<div class="line"> ! Create a new file using default properties.</div>
<div class="line"> ! </div>
<div class="line"> CALL h5fcreate_f(filename, H5F_ACC_TRUNC_F, file_id, error)</div>
<div class="line"> </div>
<div class="line"> !</div>
<div class="line"> ! Terminate access to the file.</div>
<div class="line"> !</div>
<div class="line"> CALL h5fclose_f(file_id, error)</div>
<div class="line">!</div>
<div class="line">! Close FORTRAN interface.</div>
<div class="line">!</div>
<div class="line"> CALL h5close_f(error)</div>
<div class="line"> END PROGRAM FILEEXAMPLE</div>
</div><!-- fragment --><p>See <a class="el" href="_l_b_examples.html">Examples from Learning the Basics</a> for the examples used in the Learning the Basics tutorial.</p>
<p>For details on compiling an HDF5 application: [ <a class="el" href="_l_b_compiling.html">Compiling HDF5 Applications</a> ]</p>
<h2><a class="anchor" id="subsecLBFileExampleRem"></a>
Remarks</h2>
<ul>
<li><b>In C</b>: The include file <code style="background-color:whitesmoke;">hdf5.h</code> contains definitions and declarations and must be included in any program that uses the HDF5 library. <br />
<b>In FORTRAN</b>: The module <code style="background-color:whitesmoke;">HDF5</code> contains definitions and declarations and must be used in any program that uses the HDF5 library. Also note that <a class="el" href="group___h5.html#ga27fa33dc262dda95c5aa8df533837480" title="Initializes the HDF5 library.">H5open</a> MUST be called at the beginning of an HDF5 Fortran application (prior to any HDF5 calls) to initialize the library and variables. The <a class="el" href="group___h5.html#ga8a9fe81dcf66972ed75ea481e7750574" title="Flushes all data to disk, closes all open objects, and releases memory.">H5close</a> call MUST be at the end of the HDF5 Fortran application. </li>
<li><a class="el" href="group___h5_f.html#gae64b51ee9ac0781bc4ccc599d98387f4" title="Creates an HDF5 file.">H5Fcreate</a> creates an HDF5 file and returns the file identifier.<br />
For Fortran, the file creation property list and file access property list are optional. They can be omitted if the default values are to be used.<br />
The root group is automatically created when a file is created. Every file has a root group and the path name of the root group is always <code style="background-color:whitesmoke;">/</code>. </li>
<li><a class="el" href="group___h5_f.html#gac55cd91d80822e4f8c2a7f04ea71b124" title="Terminates access to an HDF5 file.">H5Fclose</a> terminates access to an HDF5 file.<br />
When an HDF5 file is no longer accessed by a program, <a class="el" href="group___h5_f.html#gac55cd91d80822e4f8c2a7f04ea71b124" title="Terminates access to an HDF5 file.">H5Fclose</a> must be called to release the resources used by the file. This call is mandatory.<br />
Note that if <a class="el" href="group___h5_f.html#gac55cd91d80822e4f8c2a7f04ea71b124" title="Terminates access to an HDF5 file.">H5Fclose</a> is called for a file, but one or more objects within the file remain open, those objects will remain accessible until they are individually closed. This can cause access problems for other users, if objects were inadvertently left open. A File Access property controls how the file is closed.</li>
</ul>
<h2><a class="anchor" id="subsecLBFileExampleCont"></a>
File Contents</h2>
<p>The HDF Group has developed tools for examining the contents of HDF5 files. The tool used throughout the HDF5 tutorial is the HDF5 dumper, <code style="background-color:whitesmoke;">h5dump</code>, which displays the file contents in human-readable form. The output of <code style="background-color:whitesmoke;">h5dump</code> is an ASCII display formatted according to the HDF5 DDL grammar. This grammar is defined, using Backus-Naur Form, in the <a class="el" href="_d_d_l_b_n_f110.html">DDL in BNF through HDF5 1.10</a>.</p>
<p>To view the HDF5 file contents, simply type: </p><div class="fragment"><div class="line">h5dump <filename></div>
</div><!-- fragment --><table class="doxtable">
<caption>Describe the file contents of file.h5 using a directed graph.</caption>
<tr>
<td><div class="image">
<img src="imgLBFile.gif" alt=""/>
</div>
</td></tr>
</table>
<p>The text description of <code style="background-color:whitesmoke;">file.h5</code>, as generated by <code style="background-color:whitesmoke;">h5dump</code>. The HDF5 file called <code style="background-color:whitesmoke;">file.h5</code> contains a group called <code style="background-color:whitesmoke;">/</code>, or the root group. (The file called <code style="background-color:whitesmoke;">filef.h5</code>, created by the FORTRAN version of the example, has the same output except that the filename shown is <code style="background-color:whitesmoke;">filef.h5</code>.) </p><div class="fragment"><div class="line">HDF5 <span class="stringliteral">"file.h5"</span> {</div>
<div class="line"> GROUP <span class="stringliteral">"/"</span> {</div>
<div class="line"> }</div>
<div class="line"> }</div>
</div><!-- fragment --><h2><a class="anchor" id="subsecLBFileExampleDDL"></a>
File Definition in DDL</h2>
<p>The simplified DDL file definition for creating an HDF5 file. For simplicity, a simplified DDL is used in this tutorial. A complete and more rigorous DDL can be found in the <a class="el" href="_d_d_l_b_n_f110.html">DDL in BNF through HDF5 1.10</a>.</p>
<p>The following symbol definitions are used in the DDL: </p><div class="fragment"><div class="line">::= defined as</div>
<div class="line"><tname> a token with the name tname</div>
<div class="line"><a> | <b> one of <a> or <b></div>
<div class="line"><a>* zero or more occurrences of <a></div>
</div><!-- fragment --><p>The simplified DDL for file definition is as follows: </p><div class="fragment"><div class="line"><file> ::= HDF5 <span class="stringliteral">"<file_name>"</span> { <root_group> }</div>
<div class="line"> </div>
<div class="line"><root_group> ::= GROUP <span class="stringliteral">"/"</span> { <group_attribute>* </div>
<div class="line"> <group_member>* }</div>
<div class="line"> </div>
<div class="line"><group_attribute> ::= <attribute></div>
<div class="line"> </div>
<div class="line"><group_member> ::= <group> | <dataset></div>
</div><!-- fragment --><p>Navigate back: <a class="el" href="index.html">Main</a> / <a class="el" href="_getting_started.html">Getting Started with HDF5</a> / <a class="el" href="_learn_basics.html">Learning the Basics</a> </p>
</div></div><!-- contents -->
</div><!-- PageDoc -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
<ul>
<li class="footer">Generated by
<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.10.0 </li>
</ul>
</div>
</body>
</html>
|
