mirror of
https://github.com/HDFGroup/hdf5.git
synced 2024-12-03 02:32:04 +08:00
203 lines
5.6 KiB
HTML
203 lines
5.6 KiB
HTML
<HTML><HEAD>
|
|
<TITLE>HDF5 Tutorial - Creating a Group
|
|
</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 a Group</FONT>
|
|
</BIG></BIG></BIG></H1>
|
|
|
|
<hr noshade size=1>
|
|
|
|
<BODY>
|
|
<H2>Contents:</H2>
|
|
<UL>
|
|
<LI> <A HREF="#def">What is a Group</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>What is a Group?</h2>
|
|
<P>
|
|
An HDF5 group is a structure containing zero or more HDF5 objects. The two
|
|
primary HDF5 objects are groups and datasets. To create a group, the calling
|
|
program must:
|
|
<OL>
|
|
<LI> Obtain the location identifier where the group is to be created.
|
|
<LI> Create the group.
|
|
<LI> Close the group.
|
|
</OL>
|
|
To create a group, the calling program must call
|
|
<code>H5Gcreate</code>/<code>h5gcreate_f</code>.
|
|
To close the group, <code>H5Gclose</code>/<code>h5gclose_f</code>
|
|
must be called. For example:
|
|
<P>
|
|
<I>C:</I>
|
|
<PRE>
|
|
group_id = H5Gcreate (loc_id, name, size_hint);
|
|
status = H5Gclose (group_id);
|
|
</PRE>
|
|
<I>FORTRAN:</I>
|
|
<PRE>
|
|
CALL h5gcreate_f (loc_id, name, group_id, error, size_hint=size)
|
|
<i>or</i>
|
|
CALL h5gcreate_f (loc_id, name, group_id, error)
|
|
|
|
|
|
CALL h5gclose_f (group_id, error)
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
<H2> Programming Example</H2>
|
|
<A NAME="desc">
|
|
<H3><U>Description</U></H3>
|
|
The following example shows how to create and close a group. It creates a file
|
|
called <code>group.h5</code> (<code>groupf.h5</code> for FORTRAN),
|
|
creates a group called <code>MyGroup</code> in the root group,
|
|
and then closes the group and file. <BR>
|
|
<UL>
|
|
[ <A HREF="examples/h5_crtgrp.c">C Example</A> ]
|
|
- <code>h5_crtgrp.c</code><BR>
|
|
[ <A HREF="examples/groupexample.f90">FORTRAN Example</A> ]
|
|
- <code>groupexample.f90</code><BR>
|
|
[ <A HREF="examples/java/CreateGroup.java">Java Example</A> ]
|
|
- <code>CreateGroup.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.
|
|
|
|
</PRE>
|
|
<A NAME="rem">
|
|
<H3><U>Remarks</U></H3>
|
|
<UL>
|
|
<LI><code>H5Gcreate</code>/<code>h5gcreate_f</code> creates
|
|
a new empty group, named <code>MyGroup</code> and located in the
|
|
root group, and returns a group identifier.
|
|
<P>
|
|
<I>C:</I>
|
|
<PRE>
|
|
hid_t H5Gcreate (hid_t loc_id, const char *name, size_t size_hint)
|
|
</PRE>
|
|
<I>FORTRAN:</I>
|
|
<PRE>
|
|
h5gcreate_f (loc_id, name, group_id, hdferr, size_hint)
|
|
|
|
loc_id INTEGER(HID_T)
|
|
name CHARACTER(LEN=*)
|
|
group_id INTEGER(HID_T)
|
|
hdferr INTEGER
|
|
(Possible values: 0 on success and -1 on failure)
|
|
size_hint INTEGER(SIZE_T), OPTIONAL
|
|
(Default value: OBJECT_NAMELEN_DEFAULT_F)
|
|
|
|
</PRE>
|
|
<UL>
|
|
<LI>The <I>loc_id</I> parameter specifies the location at which
|
|
to create the group.
|
|
<P>
|
|
<LI> The <I>name</I> parameter specifies the name of the group to be created.
|
|
<P>
|
|
<LI> The <I>size_hint</I> parameter specifies how much file space to
|
|
reserve to store the
|
|
names that will appear in the group. If a non-positive value is supplied,
|
|
then a default size is used. Passing a value of zero is usually adequate
|
|
since the library is able to dynamically resize the name heap.
|
|
<P>
|
|
<LI>In FORTRAN, the return value for the routine is passed in
|
|
<I>hdferr</I>: 0 if successful, -1 otherwise. The group identifier
|
|
is passed back in <I>group_id</I>. In C, the function returns a valid
|
|
group identifier if successful and a negative value otherwise.
|
|
|
|
</UL>
|
|
<P>
|
|
<LI><code>H5Gclose</code>/<code>h5gclose_f</code> closes the group.
|
|
This call is mandatory.
|
|
<P>
|
|
<I>C:</I>
|
|
<PRE>
|
|
herr_t H5Gclose (hid_t group_id)
|
|
</PRE>
|
|
<I>FORTRAN:</I>
|
|
<PRE>
|
|
h5gclose_f (group_id, hdferr)
|
|
|
|
group_id INTEGER(HID_T)
|
|
hdferr INTEGER
|
|
(Possible values: 0 on success and -1 on failure)
|
|
|
|
</PRE>
|
|
</UL>
|
|
|
|
<A NAME="fc">
|
|
<H3><U>File Contents</U></H3>
|
|
The contents of <code>group.h5</code> and the
|
|
definition of the group are shown below. (The FORTRAN program
|
|
creates the HDF5 file <code>groupf.h5</code> and the resulting DDL shows
|
|
<code>groupf.h5</code> in the first line.)
|
|
<P>
|
|
<table width="80%" border="1" bordercolor="#FFFFFF" cellpadding="6" cellspacing="6">
|
|
<tr valign=top>
|
|
<td width="43%"><b>Fig. 8.1</b> <i>The Contents of <code>group.h5</code>.</i>
|
|
</td>
|
|
<td width="10%">
|
|
</td>
|
|
<td width="47%"><b>Fig. 8.2</b> <i><code>group.h5</code> in DDL</i> </td>
|
|
</tr>
|
|
<tr bordercolor="#000000">
|
|
<!-- <td width="47%"><IMG src="grouph5.jpg" width="205" height="333"></td> -->
|
|
<td align=center><IMG src="img003.gif"></td>
|
|
<td bordercolor="#FFFFFF"> </td>
|
|
<td valign="top">
|
|
<pre>
|
|
HDF5 "group.h5" {
|
|
GROUP "/" {
|
|
GROUP "MyGroup" {
|
|
}
|
|
}
|
|
}
|
|
</pre>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
|
|
<!-- 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>
|
|
|
|
|
|
|