304 lines
9.6 KiB
HTML
304 lines
9.6 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</A>
|
|
<LI>Programming Example
|
|
<UL>
|
|
<LI> <A HREF="#desc">Description</A>
|
|
<LI> <A HREF="#rem">Remarks</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</H2>
|
|
This section discusses how to find names and object types of HDF5 group
|
|
members.
|
|
<P>
|
|
The HDF5 Group interface has a function, H5Giterate, to iterate over the
|
|
group members.
|
|
<P>
|
|
Operations on each group member can be performed during the iteration process.
|
|
The operator function and its data are passed 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> Use H5Giterate to iterate through the group or just a few members of
|
|
the group.
|
|
</OL>
|
|
<H2> Programming Example</H2>
|
|
<A NAME="desc">
|
|
<H3><U>Description</U></H3>
|
|
In this example we iterate through the members of the root group. The
|
|
operator function displays the members' names and their object types.
|
|
The object type can be a group, dataset, or named datatype.
|
|
[ <A HREF="examples/h5_iterate.c">Download h5_iterate.c</A> ]
|
|
<PRE>
|
|
|
|
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
|
|
|
|
#include <hdf5.h>
|
|
|
|
#define FILE "iterate.h5"
|
|
#define FALSE 0
|
|
|
|
/* 1-D dataset with fixed dimensions */
|
|
#define SPACE1_NAME "Space1"
|
|
#define SPACE1_RANK 1
|
|
#define SPACE1_DIM1 4
|
|
|
|
herr_t file_info(hid_t loc_id, const char *name, void *opdata);
|
|
/* Operator function */
|
|
int
|
|
main(void) {
|
|
hid_t file; /* HDF5 File IDs */
|
|
hid_t dataset; /* Dataset ID */
|
|
hid_t group; /* Group ID */
|
|
hid_t sid; /* Dataspace ID */
|
|
hid_t tid; /* Datatype ID */
|
|
hsize_t dims[] = {SPACE1_DIM1};
|
|
herr_t ret; /* Generic return value */
|
|
|
|
/* Compound datatype */
|
|
typedef struct s1_t {
|
|
unsigned int a;
|
|
unsigned int b;
|
|
float c;
|
|
} s1_t;
|
|
|
|
/* Create file */
|
|
file = H5Fcreate(FILE, H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT);
|
|
|
|
/* Create dataspace for datasets */
|
|
sid = H5Screate_simple(SPACE1_RANK, dims, NULL);
|
|
|
|
/* Create a group */
|
|
group=H5Gcreate(file,"Group1",-1);
|
|
|
|
/* Close a group */
|
|
ret = H5Gclose(group);
|
|
|
|
/* Create a dataset */
|
|
dataset=H5Dcreate(file,"Dataset1",H5T_STD_U32LE,sid,H5P_DEFAULT);
|
|
|
|
/* Close Dataset */
|
|
ret = H5Dclose(dataset);
|
|
|
|
/* Create a datatype */
|
|
tid = H5Tcreate (H5T_COMPOUND, sizeof(s1_t));
|
|
|
|
/* Insert fields */
|
|
ret=H5Tinsert (tid, "a", HOFFSET(s1_t,a), H5T_NATIVE_INT);
|
|
|
|
ret=H5Tinsert (tid, "b", HOFFSET(s1_t,b), H5T_NATIVE_INT);
|
|
|
|
ret=H5Tinsert (tid, "c", HOFFSET(s1_t,c), H5T_NATIVE_FLOAT);
|
|
|
|
/* Save datatype for later */
|
|
ret=H5Tcommit (file, "Datatype1", tid);
|
|
|
|
/* Close datatype */
|
|
ret = H5Tclose(tid);
|
|
|
|
/* Iterate through the file to see members of the root group */
|
|
|
|
printf(" Objects in the root group are:\n");
|
|
printf("\n");
|
|
|
|
H5Giterate(file, "/", NULL, file_info, NULL);
|
|
|
|
/* Close file */
|
|
ret = H5Fclose(file);
|
|
|
|
return 0;
|
|
}
|
|
|
|
/*
|
|
* Operator function.
|
|
*/
|
|
herr_t file_info(hid_t loc_id, const char *name, void *opdata)
|
|
{
|
|
H5G_stat_t statbuf;
|
|
|
|
/*
|
|
* Get type of the object and display its name and type.
|
|
* The name of the object is passed to this function by
|
|
* the Library. Some magic :-)
|
|
*/
|
|
H5Gget_objinfo(loc_id, name, FALSE, &statbuf);
|
|
switch (statbuf.type) {
|
|
case H5G_GROUP:
|
|
printf(" Object with name %s is a group \n", name);
|
|
break;
|
|
case H5G_DATASET:
|
|
printf(" Object with name %s is a dataset \n", name);
|
|
break;
|
|
case H5G_TYPE:
|
|
printf(" Object with name %s is a named datatype \n", name);
|
|
break;
|
|
default:
|
|
printf(" Unable to identify an object ");
|
|
}
|
|
return 0;
|
|
}
|
|
|
|
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
|
|
</PRE>
|
|
The output of this program is:
|
|
<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>
|
|
<A NAME="rem">
|
|
<H3><U>Remarks</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 first parameter is a group identifier for the group being iterated
|
|
over. It is passed to the operator by the iterator function, H5Giterate.
|
|
<LI> The second parameter is the name of the current object. The name is
|
|
passed to the operator function by the HDF5 library.
|
|
<LI> The third parameter is the operator data. It is passed to and from
|
|
the operator by the iterator, H5Giterate.
|
|
|
|
The operator function in this example just 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.
|
|
</UL>
|
|
<P>
|
|
The operator return value defines the behavior of the iterator.
|
|
<UL>
|
|
<LI>A zero return value causes the iterator to continue, returning
|
|
zero when all group members have been processed.
|
|
<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.
|
|
<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 H5Gget_objinfo 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 first two 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.
|
|
<LI> The third argument is a flag which indicates whether a
|
|
symbolic link should be followed or not. A zero value indicates
|
|
that information should be returned for the link itself, but not
|
|
about the object it points to.
|
|
The root group in this example does not have objects that are
|
|
links, so this flag is not important for our example.
|
|
<LI> The fourth argument is a buffer to return information in.
|
|
Type information is returned into the field "type" of the
|
|
H5G_stat_t data structure (statbuf.type). Possible values are:
|
|
H5G_GROUP, H5G_DATASET, H5G_TYPE, and H5G_LINK.
|
|
</UL>
|
|
<P>
|
|
<LI> The H5Giterate function has the following signature:
|
|
<PRE>
|
|
int H5Giterate(hid_t loc_id, const char *name , idx,
|
|
H5G_operator_t operator, void * operator_data)
|
|
</PRE>
|
|
<UL>
|
|
<LI> The first parameter is the group for the group being iterated over.
|
|
<LI> The second parameter is the group name.
|
|
<LI> The third parameter specifies that iteration begins with the
|
|
<I>idx</I> object in the group and the next element to be processed
|
|
is returned in the <I>idx</I> parameter. 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 fourth parameter is an operator function.
|
|
<LI> The fifth argument is the operator data. We used NULL since no
|
|
data was passed to and from the operator.
|
|
</UL>
|
|
</UL>
|
|
|
|
<!--
|
|
<A NAME="fc">
|
|
<H3><U>File Contents</U></H3>
|
|
-->
|
|
|
|
|
|
|
|
|
|
|
|
<!-- 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>
|
|
|
|
|
|
|