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
|
<HTML><HEAD>
<TITLE>HDF5 Tutorial - Creating an HDF5 File
</TITLE>
</HEAD>
<body bgcolor="#ffffff">
<!-- BEGIN MAIN BODY -->
<A HREF="http://www.ncsa.uiuc.edu/"><img border=0
src="http://www.ncsa.uiuc.edu/Images/NCSAhome/footerlogo.gif"
width=78 height=27 alt="NCSA"><P></A>
[ <A HREF="title.html"><I>HDF5 Tutorial Top</I></A> ]
<H1>
<BIG><BIG><BIG><FONT COLOR="#c101cd">Creating an HDF5 file</FONT>
</BIG></BIG></BIG></H1>
<hr noshade size=1>
<BODY>
<H2>Contents:</H2>
<UL>
<LI> <A HREF="#def">What is an HDF5 file</A>?
<LI>Programming Example
<UL>
<LI> <A HREF="#desc">Description</A>
<LI> <A HREF="#rem">Remarks</A>
<LI> <A HREF="#fc">File Contents</A>
<LI> <A HREF="#ddl">File Definition in DDL</A>
</UL>
</UL>
<HR>
<A NAME="def">
<H2>What is an HDF5 file?</h2>
<P>
An HDF5 file is a binary file which contains scientific data and supporting
metadata. The two primary objects stored in an HDF5 file are groups and
datasets. Groups and datasets will be discussed in the other sessions.
<P>
To create a file, the program application must specify a file name, file
access mode, file creation property list, and file access property list.
<P>
<UL>
<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.
<P>
The user-block is a fixed length block of data located at the beginning
of the file which is ignored by the HDF5 library and may be used to store
any data information found to be useful to applications.
<P>
For more details, see the HDF5 documentation. In this tutorial,
the default file metadata is used.
<P>
<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. See the HDF5 User's Guide for details. The default
file access property is used in this tutorial.
</UL>
<P>
The steps to create and close an HDF5 file are as follows:
<OL>
<LI> Specify the file creation and access property lists if necessary.
<LI> Create a file.
<LI> Close the file and close the property lists if necessary.
</OL>
To create an HDF5 file, the calling program must contain the following calls:
<PRE>
file_id = H5Fcreate(filename, access_mode, create_id, access_id);
H5Fclose(file_id);
</PRE>
<P>
<H2>Programming Example</H2>
<A NAME="desc">
<H3><U>Description</U></H3>
The following example demonstrates how to create and close an HDF5 file.
It creates a file called 'file.h5', and then closes the file.<BR>
[ <A HREF="examples/h5_crtfile.c">Download h5_crtfile.c</A> ]
<PRE>
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
#include <hdf5.h>
#define FILE "file.h5"
main() {
hid_t file_id; /* file identifier */
herr_t status;
/* Create a new file using default properties. */
file_id = H5Fcreate(FILE, H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT);
/* Terminate access to the file. */
status = H5Fclose(file_id);
}
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
</PRE>
<A NAME="rem">
<H3><U>Remarks</U></H3>
<UL>
<LI>The include file 'hdf5.h' contains definitions and declarations, and it must
be included in any file that uses the HDF5 library.
<P>
<LI>H5Fcreate creates an HDF5 file and returns the file identifier.
<PRE>
hid_t H5Fcreate (const char *name, unsigned flags, hid_t create_id,
hid_t access_id)
</PRE>
<UL>
<LI> The first parameter specifies the name of the file to be created.
<P>
<LI> The second parameter specifies the file access mode. H5F_ACC_TRUNC will
truncate a file if it already exists.
<P>
<LI> The third parameter specifies the file creation property list.
H5P_DEFAULT indicates that the default file creation property list is
used.
<P>
<LI> The last parameter of H5Fcreate specifies the file access property list.
H5P_DEFAULT indicates that the default file access property list is used.
</UL>
<P>
<LI> When a file is no longer accessed by a program, H5Fclose must be called to
release the resource used by the file. This call is mandatory.
<PRE>
herr_t H5Fclose (hid_t file_id)
</PRE>
<P>
<LI>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 '/'.
</UL>
<A NAME="fc">
<H3><U>File Contents</U></H3>
HDF has developed tools to examine the contents of HDF5 files. The tool used
in this tutorial is the HDF5 dumper, h5dump. h5dump is a tool that displays
the file contents in human readable form to an ASCII file in DDL. DDL (Data
Description Language) is a language that describes HDF5 objects in Backus-Naur
Form. To view the file contents, type:
<PRE>
<B>h5dump <filename></B>
</PRE>
Figure 4.1 describes the file contents of 'file.h5' using a directed graph.
Each HDF5 object is represented by a rectangle and the arrows indicate
the structure of the contents. In Fig. 4.2, 'file.h5' contains
a group object named '/' (the root group).
<P>
<B>Fig. 4.1</B> <I>Contents of 'file.h5'</I>
<PRE>
<!--
<IMG src="fileh5.jpg" width="205" height="208"></PRE> -->
<IMG src="img001.gif"></PRE>
Figure 4.2 is the text-description of 'file.h5' generated by h5dump. The HDF5
file called 'file.h5' contains a group called '/'.
<P>
<B> Fig. 4.2</B> <I>'file.h5' in DDL</I>
<PRE>
HDF5 "file.h5" {
GROUP "/" {
}
}
</PRE>
<A NAME="ddl">
<h3><U>File Definition in DDL</U></H3>
Figure 4.3 is 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 HDF5 User's Guide. See the
<A HREF="references.html">References</A> section of this tutorial.
<P>
<B> Fig. 4.3</B> <I>HDF5 File Definition</I>
<P>
The explanation of the symbols used in the DDL:
<PRE>
::= defined as
<tname> a token with the name <I>tname</I>
<a> | <b> one of <a> or <b>
<a>* zero or more occurrences of <a>
</PRE>
The simplified DDL file definition:
<PRE>
<file> ::= HDF5 "<file_name>" { <root_group> }
<root_group> ::= GROUP "/" { <group_attribute>* <group_member>* }
<group_attribute> ::= <attribute>
<group_member> ::= <group> | <dataset>
</PRE>
<!-- BEGIN FOOTER INFO -->
<P><hr noshade size=1>
<font face="arial,helvetica" size="-1">
<a href="http://www.ncsa.uiuc.edu/"><img border=0
src="http://www.ncsa.uiuc.edu/Images/NCSAhome/footerlogo.gif"
width=78 height=27 alt="NCSA"><br>
The National Center for Supercomputing Applications</A><br>
<a href="http://www.uiuc.edu/">University of Illinois
at Urbana-Champaign</a><br>
<br>
<!-- <A HREF="helpdesk.mail.html"> -->
<A HREF="mailto:hdfhelp@ncsa.uiuc.edu">
hdfhelp@ncsa.uiuc.edu</A>
<BR> <H6>Last Modified: August 27, 1999</H6><BR>
<!-- modified by Barbara Jones - bljones@ncsa.uiuc.edu -->
</FONT>
<BR>
<!-- <A HREF="mailto:hdfhelp@ncsa.uiuc.edu"> -->
</BODY>
</HTML>
|
