mirror of
https://github.com/HDFGroup/hdf5.git
synced 2025-02-23 16:20:57 +08:00
f0c8f8697e
Purpose:
[is this a bug fix? feature? ...]
Description:
[describe the bug, or describe the new feature, etc]
Solution:
[details about the changes, algorithm, etc...]
[Please as detail as you can since your own explanation is
better than others guessing it from the code.]
Platforms tested:
[machines you have tested the changed version. This is absolute
important. Test it out on at least two or three different platforms
such as Big-endian-32bit (SUN/IRIX), little-endian-32(LINUX) and
64-bit (IRIX64/UNICOS/DEC-ALPHA) would be good.]
294 lines
10 KiB
HTML
294 lines
10 KiB
HTML
<HTML><HEAD>
|
|
<TITLE>HDF5 Tutorial - Iterating over Group Members
|
|
</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">Iterating over Group Members</FONT>
|
|
</BIG></BIG></BIG></H1>
|
|
|
|
<hr noshade size=1>
|
|
|
|
<BODY>
|
|
<H2>Contents:</H2>
|
|
<UL>
|
|
<LI><A HREF="#def">How to Iterate over Group Members Using C </A>
|
|
<LI><A HREF="#deff">How to Iterate over Group Members Using FORTRAN</A>
|
|
<LI>Programming Example
|
|
<UL>
|
|
<LI> <A HREF="#desc">Description</A>
|
|
<LI> <A HREF="#remc">Remarks for C Example</A>
|
|
<LI> <A HREF="#remf">Remarks for FORTRAN Example</A>
|
|
<!--
|
|
<LI> <A HREF="#fc">File Contents</A>
|
|
<LI> <A HREF="#ddl">Dataset Definition in DDL</A>
|
|
-->
|
|
</UL>
|
|
</UL>
|
|
<HR>
|
|
<A NAME="def">
|
|
<H2>How to Iterate over Group Members Using C</H2>
|
|
This section discusses how to find names and object types of HDF5 group
|
|
members using C.
|
|
<P>
|
|
The HDF5 Group interface includes the <CODE>H5Giterate</CODE> function,
|
|
which iterates over the group members.
|
|
<P>
|
|
Operations on each group member can be performed during the iteration process
|
|
by passing the operator function and its data to the iterator as parameters.
|
|
There are no restrictions on what kind of operations can be performed on
|
|
group members during the iteration procedure.
|
|
<P>
|
|
The following steps are involved:
|
|
<OL>
|
|
|
|
<LI> Write an operator function which will be used during the iteration process.
|
|
The HDF5 library defines the operator function signature and return values.
|
|
<LI> Open the group to iterate through.
|
|
<LI> Iterate through the group or just a few members of the group.
|
|
</OL>
|
|
<A NAME="deff">
|
|
<H2>How to Iterate Over Group Members using FORTRAN</H2>
|
|
There is no FORTRAN call to iterate over group members.
|
|
Instead, this functionality is provided by two FORTRAN calls:
|
|
<ul>
|
|
<li><CODE>hgn_members_f</CODE> returns the number of group members.
|
|
<li><CODE>h5gget_obj_info_idx_f</CODE> returns the name and type of the
|
|
group member, which is identified by its index.
|
|
</ul>
|
|
<P>
|
|
<H2> Programming Example</H2>
|
|
<A NAME="desc">
|
|
<H3><U>Description</U></H3>
|
|
In this example we iterate through the members of the root group.
|
|
<UL>
|
|
[ <A HREF="examples/h5_iterate.c">C example</A> ]
|
|
- <code>h5_iterate.c</code><BR>
|
|
[ <A HREF="examples/grpit.f90">FORTRAN example</A> ]
|
|
- <code>grpit.f90</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.
|
|
<P>
|
|
Following is the output from these examples:
|
|
<P>
|
|
<I><U>Output from C Example</U></I>
|
|
<PRE>
|
|
Objects in the root group are:
|
|
|
|
Object with name Dataset1 is a dataset
|
|
Object with name Datatype1 is a named datatype
|
|
Object with name Group1 is a group
|
|
</PRE>
|
|
<I><U>Output from FORTRAN Example</U></I>
|
|
<PRE>
|
|
Number of root group member is 1
|
|
MyGroup 1
|
|
Number of group MyGroup member is 2
|
|
Group_A 1
|
|
dset1 2
|
|
Number of group MyGroup/Group_A member is 1
|
|
dset2 2
|
|
</PRE>
|
|
<A NAME="remc">
|
|
<H3><U>Remarks for C Example</U></H3>
|
|
<P>
|
|
<UL>
|
|
<LI> The operator function in this example is called <I>file_info</I>.
|
|
The signature of the operator function is as follows:
|
|
<PRE>
|
|
herr_t *(H5G_operator_t) (hid group_id, const char* name,
|
|
void *operator_data)
|
|
</PRE>
|
|
<UL>
|
|
<LI>The <em>group_id</em> parameter is a group identifier for the
|
|
group being iterated over.
|
|
It is passed to the operator by the iterator function,
|
|
<CODE>H5Giterate</CODE>.
|
|
<P>
|
|
<LI>The <em>name</em> parameter is the name of the current object.
|
|
The name is passed to the operator function by the HDF5 library.
|
|
<P>
|
|
<LI> The <em>operator_data</em> parameter is the operator data.
|
|
It is passed to and from
|
|
the operator by the iterator, <CODE>H5Giterate</CODE>.
|
|
</UL>
|
|
<P>
|
|
The operator function in this example simply prints the name and type
|
|
of the current object and then exits.
|
|
This information can also be used to open the object and perform
|
|
different operations or queries. For example a named datatype object's
|
|
name can be used to open the datatype and query its properties.
|
|
<P>
|
|
The operator return value defines the behavior of the iterator.
|
|
<UL>
|
|
<P>
|
|
<LI>A zero return value causes the iterator to continue, returning
|
|
zero when all group members have been processed.
|
|
<P>
|
|
<LI>A positive value causes the iterator to immediately return that
|
|
value, indicating a short-circuit success. The iterator can be restarted
|
|
at the next group member.
|
|
<P>
|
|
<LI>A negative value causes the iterator to immediately return that value,
|
|
indicating failure. The iterator can be restarted at the next group
|
|
member.
|
|
</UL>
|
|
<P>
|
|
In this example the operator function returns 0, which causes the iterator
|
|
to continue and go through all group members.
|
|
<P>
|
|
<LI>The function <CODE>H5Gget_objinfo</CODE> is used to determine the type of the object.
|
|
It also returns the modification time, number of hard links, and some
|
|
other information.
|
|
<P>
|
|
The signature of this function is as follows:
|
|
<PRE>
|
|
herr_t H5Gget_objinfo (hid_t loc_id, const char * name,
|
|
hbool_t follow_link,
|
|
H5G_stat_t *statbuf)
|
|
</PRE>
|
|
<UL>
|
|
<LI>The <em>loc_id</em> and <em>name</em> arguments
|
|
specify the object by its location and name.
|
|
This example uses the group identifier and name relative to the group
|
|
to specify the object.
|
|
<P>
|
|
<LI>The <em>follow_link</em> argument is a flag which indicates
|
|
whether a symbolic link should be followed. A zero value indicates
|
|
that information should be returned for the link itself, but not
|
|
about the object it points to.
|
|
<P>
|
|
The root group in this example does not have objects that are
|
|
links, so this flag is not important for our example.
|
|
<P>
|
|
<LI>The <em>statbuf</em> argument is the buffer in which to return
|
|
information.
|
|
Type information is returned into the field <em>type</em> of the
|
|
<CODE>H5G_stat_t</CODE> data structure (<code>statbuf.type</code>).
|
|
Valid values are
|
|
<CODE>H5G_GROUP</CODE>, <CODE>H5G_DATASET</CODE>,
|
|
<CODE>H5G_TYPE</CODE>, and <CODE>H5G_LINK</CODE>.
|
|
</UL>
|
|
<P>
|
|
<LI> The <CODE>H5Giterate</CODE> function has the following signature:
|
|
<PRE>
|
|
int H5Giterate (hid_t loc_id, const char *name , int *idx,
|
|
H5G_operator_t operator, void * operator_data)
|
|
</PRE>
|
|
<UL>
|
|
<LI> The <em>loc_id</em> parameter is the group identifier for the
|
|
group being iterated over.
|
|
<LI> The <em>name</em> parameter is the group name.
|
|
<LI> The <em>idx</em> parameter is an index specifying that iteration
|
|
begins with the <em>idx</em>-th object in the group.
|
|
Upon the function's return, the index of the next element
|
|
to be processed is returned in <I>idx</I>. In our example, NULL is
|
|
used to start at the first group member. Since no stopping point
|
|
is returned in this case, the iterator cannot be restarted if one
|
|
of the calls to its operator returns a non-zero value.
|
|
<LI> The <em>operator</em> parameter is the operator function.
|
|
<LI> The <em>operator_data</em> argument is the operator data.
|
|
We used NULL since no data was passed to or from the operator.
|
|
</UL>
|
|
</UL>
|
|
|
|
<A NAME="remf">
|
|
<H3><U>Remarks for FORTRAN Example</U></H3>
|
|
<P>
|
|
<UL>
|
|
<LI>This program creates an HDF5 file with groups in it and
|
|
then uses <CODE>h5gn_members_f</CODE> to get the number of members in
|
|
each group and <CODE>h5gget_obj_idx_f</CODE> to obtain the group member's
|
|
name and type.
|
|
<P>
|
|
<LI>The number of members in a group are obtained with the
|
|
<CODE>h5gn_members_f</CODE> call:
|
|
<PRE>
|
|
h5gn_members_f (loc_id, name, nmembers, hdferr)
|
|
|
|
loc_id IN: INTEGER (HID_T)
|
|
name IN: CHARACTER (LEN=*)
|
|
nmembers OUT: INTEGER
|
|
hdferr OUT: INTEGER
|
|
</PRE>
|
|
<UL>
|
|
<LI>The <I>loc_id</I> parameter is the file or group identifier.
|
|
<LI>The <I>name</I> parameter is the name of the group to obtain the number
|
|
of members in.
|
|
<LI>The number of members in the group is returned in <I>nmembers</I>.
|
|
<LI>The <I>hdferr</I> parameter contains the return code from the
|
|
call: 0 if successful and -1 otherwise.
|
|
</UL>
|
|
<P>
|
|
<LI>The name of each group and its type are obtained with the
|
|
<CODE>h5gget_obj_info_idx_f</CODE> call:
|
|
<PRE>
|
|
h5gget_obj_info_idx_f (loc_id, name, idx, &
|
|
obj_name, obj_type, hdferr)
|
|
|
|
loc_id IN: INTEGER (HID_T)
|
|
name IN: CHARACTER (LEN=*)
|
|
idx IN: INTEGER
|
|
obj_name OUT: CHARACTER (LEN=*)
|
|
obj_type OUT: INTEGER
|
|
hdferr OUT: INTEGER
|
|
</PRE>
|
|
<UL>
|
|
<LI>The <I>loc_id</I> parameter is the file or group identifier.
|
|
<LI>The <I>name</I> parameter is the name of the group.
|
|
<LI>The <I>idx</I> parameter is the index of the member object.
|
|
<LI>The <I>obj_name</I> parameter is the name of the object that gets returned.
|
|
<LI>The <I>obj_type</I> parameter is the object type that gets returned.
|
|
Valid values are as follows:
|
|
<PRE>
|
|
H5G_LINK_F
|
|
H5G_GROUP_F
|
|
H5G_DATASET_F
|
|
H5G_TYPE_F
|
|
</PRE>
|
|
<LI>The <I>hdferr</I> parameter contains the return code from the
|
|
call: 0 if successful and -1 otherwise.
|
|
</UL>
|
|
</UL>
|
|
|
|
|
|
|
|
|
|
<!-- 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>
|
|
<BR> <H6>Last Modified: March 16, 2001</H6><BR>
|
|
<!-- modified by Barbara Jones - bljones@ncsa.uiuc.edu -->
|
|
<!-- modified by Frank Baker - fbaker@ncsa.uiuc.edu -->
|
|
</FONT>
|
|
<BR>
|
|
<!-- <A HREF="mailto:hdfhelp@ncsa.uiuc.edu"> -->
|
|
|
|
</BODY>
|
|
</HTML>
|
|
|
|
|
|
|