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
|
<HTML><HEAD>
<TITLE>HDF5 Tutorial - Creating Groups using Absolute and Relative Names
</TITLE>
</HEAD>
<body bgcolor="#ffffff">
<!-- BEGIN MAIN BODY -->
[ <A HREF="title.html"><I>HDF5 Tutorial Top</I></A> ]
<H1>
<BIG><BIG><BIG><FONT COLOR="#c101cd">Creating Groups Using
Absolute and Relative Names</FONT>
</BIG></BIG></BIG></H1>
<hr noshade size=1>
<BODY>
<H2>Contents:</H2>
<UL>
<LI> <A HREF="#def">Absolute vs. Relative Names</A>
<LI> Programming Example
<UL>
<LI> <A HREF="#desc">Description</A>
<LI> <A HREF="#rem">Remarks</A>
<LI> <A HREF="#fc">File Contents</A>
</UL>
</UL>
<HR>
<A NAME="def">
<H2>Absolute vs. Relative Names</h2>
<P>
Recall that to create an HDF5 object, we have to specify the location where the
object is to be created. This location is determined by the identifier of an HDF5
object and the name of the object to be created. The name of the created
object can be either an absolute name or a name relative to the specified
identifier.
In the previous example, we used the file identifier and the absolute name
<code>/MyGroup</code> to create a group.
<P>
In this section, we discuss HDF5 names and show how to use absolute and
relative names.
<H3>Names</H3>
HDF5 object names are a slash-separated list of components. There are few
restrictions on names: component names may be any length except zero and may
contain any character except slash (<code>/</code>) and the null terminator.
A full name
may be composed of any number of component names separated by slashes, with any
of the component names being the special name <code>.</code> (a dot or period).
A name which begins with a slash is an absolute name which is accessed
beginning with the root group of the file;
all other names are relative names and and the named object is
accessed beginning with the specified group.
Multiple consecutive slashes in a full name are treated as single slashes
and trailing slashes are not significant. A special case is the name <code>/</code> (or
equivalent) which refers to the root group.
<P>
Functions which operate on names generally take a location identifier, which
can be either a file identifier or a group identifier, and perform the lookup
with respect to that location.
Several possibilities are described in the following table:
<center>
<table border="1" width=80% bordercolor="#000000" cellpadding="4">
<tr bgcolor="#ffcc99" bordercolor="#FFFFFF">
<td><b> Location Type </b></td>
<td><b>Object Name</b></td>
<td><b>Description</b></td>
</tr>
<tr bordercolor="#FFFFFF">
<td bgcolor="#99cccc" height="22">File identifier</td>
<td height="22" bgcolor="#CCCCCC">
<div align="center"><code>/foo/bar</code></div>
</td>
<td height="22">The object <code>bar</code> in group <code>foo</code>
in the root group. </td>
</tr>
<tr bordercolor="#FFFFFF">
<td bgcolor="#99cccc">Group identifier </td>
<td bgcolor="#CCCCCC">
<div align="center"><code>/foo/bar</code></div>
</td>
<td>The object <code>bar</code> in group <code>foo</code> in the
root group of the file containing the specified group.
In other words, the group identifier's only purpose is to
specify a file. </td>
</tr>
<tr bordercolor="#FFFFFF">
<td bgcolor="#99cccc">File identifier</td>
<td bgcolor="#CCCCCC">
<div align="center">/</div>
</td>
<td>The root group of the specified file.</td>
</tr>
<tr bordercolor="#FFFFFF">
<td bgcolor="#99cccc">Group identifier</td>
<td bgcolor="#CCCCCC">
<div align="center">/</div>
</td>
<td>The root group of the file containing the specified group.</td>
</tr>
<tr bordercolor="#FFFFFF">
<td bgcolor="#99cccc">Group identifier</td>
<td bgcolor="#CCCCCC">
<div align="center"><code>foo/bar</code></div>
</td>
<td>The object <code>bar</code> in group <code>foo</code> in
the specified group.</td>
</tr>
<tr bordercolor="#FFFFFF">
<td bgcolor="#99cccc">File identifier</td>
<td bgcolor="#CCCCCC">
<div align="center"><b>.</b></div>
</td>
<td>The root group of the file.</td>
</tr>
<tr bordercolor="#FFFFFF">
<td bgcolor="#99cccc">Group identifier</td>
<td bgcolor="#CCCCCC">
<div align="center"><b>.</b></div>
</td>
<td>The specified group.</td>
</tr>
<tr bordercolor="#FFFFFF">
<td bgcolor="#99cccc">Other identifier</td>
<td bgcolor="#CCCCCC">
<div align="center"><b>.</b></div>
</td>
<td>The specified object.</td>
</tr>
</table>
</center>
<P>
<H2> Programming Example</H2>
<A NAME="desc">
<H3><U>Description</U></H3>
The following example code shows how to create groups using absolute
and relative names. It creates three groups: the first two groups are
created using the file identifier and the group absolute names while the
third group is created using a group identifier and a name relative
to the specified group. <BR>
<UL>
[ <A HREF="examples/h5_crtgrpar.c">C Example</A> ] - <code>h5_crtgrpar.c</code><BR>
[ <A HREF="examples/grpsexample.f90">Fortran Example</A> ] - <code>grpsexample.f90</code><BR>
[ <A HREF="examples/java/CreateGroupAR.java">Java Example</A> ] - <code>CreateGroupAR.java</code>
</UL>
<B>NOTE:</B> To download a tar file of the examples, including a Makefile,
please go to the <A HREF="references.html">References</A> page.
<A NAME="rem">
<H3><U>Remarks</U></H3>
<UL>
<LI><code>H5Gcreate</code>/<code>h5gcreate_f</code> creates a group at the
location specified by a location identifier and a name.
The location identifier can be a file identifier or a group identifier
and the name can be relative or absolute.
<P>
<LI>The first <code>H5Gcreate</code>/<code>h5gcreate_f</code> creates the group
<code>MyGroup</code> in the root group of the specified file.
<P>
<LI>The second <code>H5Gcreate</code>/<code>h5gcreate_f</code> creates the group
<code>Group_A</code> in the group <code>MyGroup</code> in the root group
of the specified file. Note that the parent group (<code>MyGroup</code>)
already exists.
<P>
<LI>The third <code>H5Gcreate</code>/<code>h5gcreate_f</code> creates the group
<code>Group_B</code> in the specified group.
</UL>
<A NAME="fc">
<H3><U>File Contents</U></H3>
The file contents are shown below:
<P>
<B>Fig. 9.1</B> <I>The Contents of <code>groups.h5</code>
(<code>groupsf.h5</code> for FORTRAN)</I>
<P>
<!--<IMG src="groupsh5.jpg" width="285" height="383"></P> -->
<IMG src="img004.gif"></P>
<B> Fig. 9.2</B> <I><code>groups.h5</code> in DDL
(for FORTRAN, the name in the first line is <code>groupsf.h5</code>)</I>
<PRE>
HDF5 "groups.h5" {
GROUP "/" {
GROUP "MyGroup" {
GROUP "Group_A" {
}
GROUP "Group_B" {
}
}
}
}
</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="footer-ncsalogo.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>
<BR> <H6>Last Modified: June 22, 2001</H6><BR>
<!-- modified by Barbara Jones - bljones@ncsa.uiuc.edu -->
</FONT>
<BR>
<!-- <A HREF="mailto:hdfhelp@ncsa.uiuc.edu"> -->
</BODY>
</HTML>
|
