• LINKS
• What is HDF5?
• Downloads
• Documentation
• Software using HDF5
• HDF5 Users
• Sample HDF5 Files
• Acknowledgments
• Licenses

Contents:

• Discovering what is in an HDF5 file
• Programming Examples:
  
  • Using the H5G API
  • Using H5Literate

Discovering what is in an HDF5 file

Until now, three ways have been mentioned that can be used to read an existing HDF5 file:

• The HDF-Java browser, HDFView, can be used to open and browse an HDF5 file.
• The h5dump utility can be used to display the contents of an HDF5 file.
• From an application, the H5Dopen function can open a specified dataset, which can then be read using H5Dread.

HDFView and h5dump are standalone tools which cannot be called within an application, and using H5Dopen and H5Dread require that you know the name of the HDF5 dataset. How would an application that has no prior knowledge of an HDF5 file, be able to determine or discover the contents of it, much like HDFView and h5dump?

The answer is that there are ways to discover the contents of an HDF5 file, by using the H5G, H5L and H5O APIs:

• The H5G interface (covered earlier) consists of routines for working with groups. A group is a structure that can be used to organize zero or more HDF5 objects, not unlike a Unix directory.

• The H5L interface consists of link routines. A link is a path between groups. The H5L interface allows objects to be accessed by use of these links.

• The H5O interface consists of routines for working with objects. Datasets, groups, and committed datatypes are all objects in HDF5.

Using just the H5G interface, you can drill your way down, starting from the root group, opening groups and objects until you reach all objects. Functions that enable this are:

• H5Gget_num_objs
• H5Gget_objname_by_idx
• H5Gget_objtype_by_idx

There are also specific H5O and H5L interface routines that simplify the process:

• H5Literate traverses the links in a specified group, in the order of the specified index, using a user-defined callback routine. (A callback function is one that will be called when a certain condition is met, at a certain point in the future.)

• H5Ovisit / H5Lvisit recursively visit all objects/links accessible from a specified object/group.

Programming Examples

Using the H5G API:

To use the H5G interface exclusively you would begin with the root group, open it, get the number of objects (NumObj) in the group (see H5Gget_num_objs), and then loop through all of the objects in the group (from 0 to (NumObj - 1)), accessing each by index (see H5Gget_objname_by_idx and H5Gget_objtype_by_idx). If an object is another group, you would then open that group and repeat the process until all objects have been accessed.

The example below gives an idea of what could be done. Simply pass in the name of the HDF5 file as a parameter to this program:

[ C Example ] -- h5getinfo.c

Using H5Literate:

To use H5Literate to see what was in a file, what would need to be done?

First, these questions must be answered:

• By what order should the links be sorted (name or creation)?
• By what order will the objects be inspected along an index (increasing, decreasing, or fastest available)?
• Will the iteration be interrupted and resumed and if yes, where?
• What information should be obtained or accessed during the process (done by the callback routine)?

Below is a line of C code, which uses H5Literate:

  status = H5Literate (file, H5_INDEX_NAME, H5_ITER_NATIVE, NULL, op_func, NULL);

It assumes:

• The links are sorted by index_name (H5_INDEX_NAME).
• The objects will be inspected along an index using the fastest available order (H5_ITER_NATIVE).
• The iteration will not be interrupted and resumed.
• The iteration will display the name and type of every object and nothing more.

In the above code, the fourth parameter (set to NULL) is used when interrupting an iteration. The last parameter (also set to NULL) allows information to be passed back.

Also in the above code, op_func is the name of the callback function. Following is an example of a callback function that does nothing more than check the object type and display the name of the object:

herr_t op_func (hid_t loc_id, const char *name, const H5L_info_t *info,
            void *operator_data)
{
    herr_t          status;
    H5O_info_t      infobuf;

    /*
     * Get type of the object and display its name and type.
     * The name of the object is passed to this function by
     * the Library.
     */
    status = H5Oget_info_by_name (loc_id, name, &infobuf, H5P_DEFAULT);
    switch (infobuf.type) {
        case H5O_TYPE_GROUP:
            printf ("  Group: %s\n", name);
            break;
        case H5O_TYPE_DATASET:
            printf ("  Dataset: %s\n", name);
            break;
        default:
            printf ( "  Unknown: %s\n", name);
    }

    return 0;
}

Under HDF5 Examples you will find Examples by API, where examples of using H5Literate and H5Ovisit/H5Lvisit are included. The h5ex_g_iterate example uses H5Literate as described above. It can be used with the files created in this tutorial, by simply modifying the name of the file that it opens. See:

[ C Example ] -- h5ex_g_iterate.c
[ F90 Example ] -- h5ex_g_iterate_F03.f90

- - Last modified:January 18th 2012