This chapter discusses how to find  names and object types of HDF5 group members.

HDF5 Group interface has a function H5Giterate to iterate over the group members.
Operation on each group member can be performed during iteration process.  
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 iteration procedure.

The following steps are invloved:


0. Write an operator function which will be used during iteration process.
   HDF5 Library defines operator function signature and return values.
1. Open the group to iterate through.  
2. Use H5Giterate to iterate through all group or just few members of the group.

In this example we iterate through the members of root group. Operator function
displays member's names and their object types, i.e. if the object is a group,
dataset, or named datatype.
 


++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

#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;
 }
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Output of this program is:


 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 
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

Note:

1. Operator function in this example is called file_info.
   The signature of operator function is as follows:

  herr_t *(H5G_operator_t) (hid_group_id, const char* name, void *operator_data) 

      * The first parameter is a group identifier for the group being iterated
        over. It is passed to the operator by the iterator function H5Giterate.
      * The second parameter is a name of a current object. The name is
        passed to the operator function by the HDF5 Library.
      * The third parameter is an operator data. It is passed to and from
        operator by the iterator H5Giterate.

       Operator function in this example just prints a name and a 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 named datatype object's
       name can be used to open datatype and query its properties. 

  Operator return value defines the behavior of iterator.
      * Zero return value causes the iterator to continue, returning
        zero when all group members have been processed.
      * Positive value causes the iterator to immediately return that
        value, indicating short-circuit success. The iterator can be restarted
        at the next group member.
      * 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 operator function returns 0, that causes iterator
   to continue and go through all group members.

2. Function H5Gget_objinfo is used to determine the type of the object. 
   It is also returns 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);

       * First two arguments specify the object by its location and name.
         This example uses group identifier and name relative to the group
         to specify the object. 
       * Third argument is a flag  which says if a symbolic link
         should be followed. 0 value indicates that information should be 
         returned for the link itself, but not about the object it points to.
         Root group in this example does not have objects that are
         links, so this flag is not important for our example.
       * Fourth argumnet is a buffer to return information.
         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, or H5G_LINK.

3. H5Giterate function has the following signature:

   int H5Giterate(hid_t loc_id, const char *name , idx,
                  H5G_operator_t operator, void * operator_data) 
   * First parameter is a group for the group being iterated over.
   * Second parameter is a group name.
   * Third parameter specifies that iteration begins with the idx object
     in the group and the next element to be processed is returned in 
     idx 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 non-zero
     value.
   * Forth parametr is an operator function.
   * Fifth argument is operator data. We used NULL since no data was passed 
     to and from operator. 




