247 lines
7.5 KiB
HTML
247 lines
7.5 KiB
HTML
<HTML><HEAD>
|
|
<TITLE>HDF5 Tutorial - Creating Groups using Absolute/Relative Names
|
|
</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 Groups using
|
|
Absolute/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 Example 5, we used the file identifier and the absolute name "/MyGroup" to create a
|
|
group. The file identifier and the name "/" specifies the location where the group
|
|
"MyGroup" was created.
|
|
<P>
|
|
In this section, we discuss HDF5 names and show how to use absolute/relative
|
|
names by giving an example of creating groups in a file.
|
|
|
|
<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 ("/") 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 ".". A name which begins with a
|
|
slash is an absolute name which is accessed beginning with the root group of the
|
|
file while all other relative names are 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 "/" (or
|
|
equivalent) which refers to the root group.
|
|
<P>
|
|
Functions which operate on names generally take a location identifier which
|
|
is either a file ID or a group ID and perform the lookup with respect to that
|
|
location. Some possibilities are:
|
|
|
|
<table width="67%" border="1" 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 ID</td>
|
|
<td height="22" bgcolor="#CCCCCC">
|
|
<div align="center">/foo/bar</div>
|
|
</td>
|
|
<td height="22">The object bar in group foo in the root group. </td>
|
|
</tr>
|
|
<tr bordercolor="#FFFFFF">
|
|
<td bgcolor="#99cccc">Group ID </td>
|
|
<td bgcolor="#CCCCCC">
|
|
<div align="center">/foo/bar</div>
|
|
</td>
|
|
<td>The object bar in group foo in the root group of the file containing the
|
|
specified group. In other words, the group ID's only purpose is to supply
|
|
a file. </td>
|
|
</tr>
|
|
<tr bordercolor="#FFFFFF">
|
|
<td bgcolor="#99cccc">File ID</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 ID</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 ID</td>
|
|
<td bgcolor="#CCCCCC">
|
|
<div align="center">foo/bar</div>
|
|
</td>
|
|
<td>The object bar in group foo in the specified group.</td>
|
|
</tr>
|
|
<tr bordercolor="#FFFFFF">
|
|
<td bgcolor="#99cccc">File ID</td>
|
|
<td bgcolor="#CCCCCC">
|
|
<div align="center">.</div>
|
|
</td>
|
|
<td>The root group of the file.</td>
|
|
</tr>
|
|
<tr bordercolor="#FFFFFF">
|
|
<td bgcolor="#99cccc">Group ID</td>
|
|
<td bgcolor="#CCCCCC">
|
|
<div align="center">.</div>
|
|
</td>
|
|
<td>The specified group.</td>
|
|
</tr>
|
|
<tr bordercolor="#FFFFFF">
|
|
<td bgcolor="#99cccc">Other ID</td>
|
|
<td bgcolor="#CCCCCC">
|
|
<div align="center">.</div>
|
|
</td>
|
|
<td>The specified object.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
|
|
<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, and the
|
|
third group is created using a group identifier and the name relative
|
|
to the specified group. <BR>
|
|
[ <A HREF="examples/h5_crtgrpar.c">Download h5_crtgrpar.c</A> ]
|
|
|
|
<PRE>
|
|
|
|
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
|
|
|
|
#include <hdf5.h>
|
|
#define FILE "groups.h5"
|
|
|
|
main() {
|
|
|
|
hid_t file_id, group1_id, group2_id, group3_id; /* identifiers */
|
|
herr_t status;
|
|
|
|
/* Create a new file using default properties. */
|
|
file_id = H5Fcreate(FILE, H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT);
|
|
|
|
/* Create group "MyGroup" in the root group using absolute name. */
|
|
group1_id = H5Gcreate(file_id, "/MyGroup", 0);
|
|
|
|
/* Create group "Group_A" in group "MyGroup" using absolute name. */
|
|
group2_id = H5Gcreate(file_id, "/MyGroup/Group_A", 0);
|
|
|
|
/* Create group "Group_B" in group "MyGroup" using relative name. */
|
|
group3_id = H5Gcreate(group1_id, "Group_B", 0);
|
|
|
|
/* Close groups. */
|
|
status = H5Gclose(group1_id);
|
|
status = H5Gclose(group2_id);
|
|
status = H5Gclose(group3_id);
|
|
|
|
/* Close the file. */
|
|
status = H5Fclose(file_id);
|
|
}
|
|
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
|
|
</PRE>
|
|
|
|
|
|
<A NAME="rem">
|
|
<H3><U>Remarks</U></H3>
|
|
<UL>
|
|
<LI> H5Gcreate creates a group at the location specified by a location ID and a
|
|
name. The location ID can be a file ID or a group ID and the name can be
|
|
relative or absolute.
|
|
|
|
<LI> The first H5Gcreate creates the group 'MyGroup' in the root group of the
|
|
specified file.
|
|
|
|
<LI> The second H5Gcreate creates the group 'Group_A' in the group 'MyGroup'
|
|
in the root group of the specified file. Note that the parent group (MyGroup)
|
|
already exists.
|
|
|
|
<LI> The third H5Gcreate creates the group 'Group_B' 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 'groups.h5'</I>
|
|
<P>
|
|
<!--<IMG src="groupsh5.jpg" width="285" height="383"></P> -->
|
|
<IMG src="img004.gif"></P>
|
|
|
|
|
|
<B> Fig. 9.2</B> <I>'groups.h5' in DDL</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="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>
|
|
|
|
|
|
|