diff options
Diffstat (limited to 'doc/html/Tutor/crtgrpar.html')
| -rw-r--r-- | doc/html/Tutor/crtgrpar.html | 246 |
1 files changed, 246 insertions, 0 deletions
diff --git a/doc/html/Tutor/crtgrpar.html b/doc/html/Tutor/crtgrpar.html new file mode 100644 index 0000000..d5fbc66 --- /dev/null +++ b/doc/html/Tutor/crtgrpar.html @@ -0,0 +1,246 @@ +<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> + + + |