HDF5 Tutorial:   Advanced Topics
Iterating over Group Members (HDF5 1.6)

Contents:

• How to Iterate over Group Members Using C
• How to Iterate over Group Members Using FORTRAN
• Programming Example
  • Description
  • Remarks for C Example
  • Remarks for FORTRAN Example

How to Iterate over Group Members Using C

The HDF5 Group interface includes the H5Giterate function, which iterates over the group members.

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.

The following steps are involved:

1. Write an operator function which will be used during the iteration process. The HDF5 library defines the operator function signature and return values.
2. Open the group to iterate through.
3. Iterate through the group or just a few members of the group.

How to Iterate Over Group Members using FORTRAN

• hgn_members_f returns the number of group members.
• h5gget_obj_info_idx_f returns the name and type of the group member, which is identified by its index.

Programming Example

Description

[ C example ] - h5_iterate.c
[ FORTRAN example ] - grpit.f90

Following is the output from these examples:

Output from C Example

  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 

 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

Remarks for C Example

• The operator function in this example is called file_info. The signature of the operator function is as follows:

      herr_t *(H5G_operator_t) (hid group_id, const char* name, 
               void *operator_data)
  

  • The group_id parameter is a group identifier for the group being iterated over. It is passed to the operator by the iterator function, H5Giterate.

  • The name parameter is the name of the current object. The name is passed to the operator function by the HDF5 library.

  • The operator_data parameter is the operator data. It is passed to and from the operator by the iterator, H5Giterate.

  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.

  The operator return value defines the behavior of the iterator.

  • A zero return value causes the iterator to continue, returning zero when all group members have been processed.

  • 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.

  • A negative value causes the iterator to immediately return that value, indicating failure. The iterator can be restarted at the next group member.

  In this example the operator function returns 0, which causes the iterator to continue and go through all group members.

• 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.

  The signature of this function is as follows:

       herr_t H5Gget_objinfo (hid_t loc_id, const char * name, 
                              hbool_t follow_link, 
                              H5G_stat_t *statbuf)
  

  • The loc_id and name 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.

  • The follow_link 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.

    The root group in this example does not have objects that are links, so this flag is not important for our example.

  • The statbuf argument is the buffer in which to return information. Type information is returned into the field type of the H5G_stat_t data structure (statbuf.type). Valid values are H5G_GROUP (1), H5G_DATASET (2), H5G_TYPE (3), and H5G_LINK (0).

• The H5Giterate function has the following signature:

      int H5Giterate (hid_t loc_id, const char *name , int *idx,
                      H5G_operator_t operator, void * operator_data) 
  

  • The loc_id parameter is the group identifier for the group being iterated over.
  • The name parameter is the group name.
  • The idx parameter is an index specifying that iteration begins with the idx-th object in the group. Upon the function's return, the index of the next element to be processed is returned in idx. 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.
  • The operator parameter is the operator function.
  • The operator_data argument is the operator data. We used NULL since no data was passed to or from the operator.

Remarks for FORTRAN Example

• This program creates an HDF5 file with groups in it and then uses h5gn_members_f to get the number of members in each group and h5gget_obj_idx_f to obtain the group member's name and type.

• The number of members in a group are obtained with the h5gn_members_f call:

      h5gn_members_f (loc_id, name, nmembers, hdferr)
       
              loc_id    IN: INTEGER (HID_T) 
              name      IN: CHARACTER (LEN=*) 
              nmembers OUT: INTEGER
              hdferr   OUT: INTEGER 
  

  • The loc_id parameter is the file or group identifier.
  • The name parameter is the name of the group to obtain the number of members in.
  • The number of members in the group is returned in nmembers.
  • The hdferr parameter contains the return code from the call: 0 if successful and -1 otherwise.

• The name of each group and its type are obtained with the h5gget_obj_info_idx_f call:

      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
   

  • The loc_id parameter is the file or group identifier.
  • The name parameter is the name of the group.
  • The idx parameter is the index of the member object.
  • The obj_name parameter is the name of the object that gets returned.
  • The obj_type parameter is the object type that gets returned. Valid values are as follows:

            H5G_LINK_F     (0)
            H5G_GROUP_F    (1) 
            H5G_DATASET_F  (2) 
            H5G_TYPE_F     (3)
    

  • The hdferr parameter contains the return code from the call: 0 if successful and -1 otherwise.