diff options
Diffstat (limited to 'doc/html/Tutor/iterate.html')
| -rw-r--r-- | doc/html/Tutor/iterate.html | 290 |
1 files changed, 0 insertions, 290 deletions
diff --git a/doc/html/Tutor/iterate.html b/doc/html/Tutor/iterate.html deleted file mode 100644 index 3311509..0000000 --- a/doc/html/Tutor/iterate.html +++ /dev/null @@ -1,290 +0,0 @@ -<HTML><HEAD> -<TITLE>HDF5 Tutorial - Iterating over Group Members -</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">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="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 --> -<!-- modified by Frank Baker - fbaker@ncsa.uiuc.edu --> -</FONT> -<BR> -<!-- <A HREF="mailto:hdfhelp@ncsa.uiuc.edu"> --> - -</BODY> -</HTML> - - - |