230 lines
7.4 KiB
HTML
230 lines
7.4 KiB
HTML
<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>
|
|
|
|
|
|
|