Re: [netcdf-hdf] canonical create of HDF5 file

Hi Ed,

On Jul 13, 2008, at 8:27 AM, Ed Hartnett wrote:

Howdy HDF5 Programmers!

Here's the way that netcdf-4 is creating HDF5 files. Any comments? Is
all the necessary? Is there something missing?


     hid_t fapl_id, fcpl_id, fileid, grpid;

     /* Create file access and create property lists. */
     if ((fapl_id = H5Pcreate(H5P_FILE_ACCESS)) < 0) ERR;
     if ((fcpl_id = H5Pcreate(H5P_FILE_CREATE)) < 0) ERR;

     /* Set latest_format in access propertly list. This ensures that
      * the latest, greatest, HDF5 versions are used in the file. */
if (H5Pset_libver_bounds(fapl_id, H5F_LIBVER_LATEST, H5F_LIBVER_LATEST) < 0) ERR;

     /* Set H5P_CRT_ORDER_TRACKED in the creation property list. This
      * turns on HDF5 creation ordering in the file. */
     if (H5Pset_link_creation_order(fcpl_id, (H5P_CRT_ORDER_TRACKED |
                                               H5P_CRT_ORDER_INDEXED)) < 0) ERR;
     if (H5Pset_attr_creation_order(fcpl_id, (H5P_CRT_ORDER_TRACKED |
                                               H5P_CRT_ORDER_INDEXED)) < 0) ERR;

     /* Create the file. */
if ((fileid = H5Fcreate(FILE_NAME, H5F_ACC_TRUNC, fcpl_id, fapl_id)) < 0) ERR;

     /* Open the root group. */
     if ((grpid = H5Gopen2(fileid, "/", H5P_DEFAULT)) < 0) ERR;

     /* Close up. */
     if (H5Pclose(fapl_id) < 0 ||
          H5Pclose(fcpl_id) < 0 ||
          H5Gclose(grpid) < 0 ||
          H5Fclose(fileid) < 0)
         ERR;

This looks fine to me, although the H5Pset_link_creation_order() and H5Pset_attr_creation_order() routines are actually turning on creation ordering for the root group, not the file per se.

How do I specify the libver_bounds for H5Pset_libver_bounds?

The function accepts a H5F_libver_t. But that is defined as an enum:

/* Library's file format versions */
typedef enum H5F_libver_t {
H5F_LIBVER_EARLIEST, /* Use the earliest possible format for storing objects */ H5F_LIBVER_LATEST /* Use the latest possible format available for storing objects*/
} H5F_libver_t;

How then do I specify that I want "1.8.1" to be the value for the
second parameter in the function?

As I read the documentation, if I don't do that, I will be committing
a Microsoftian error. Any time a user upgrades his HDF5 version, and
creates a netCDF-4 file, *all* his users will also have to upgrade
HDF5 to read the file, even if it uses none of the new features
available in that HDF5 release.

We don't want that, do we? So I need to set the first parameter to
1.8.1...

Currently, there's no way to do that, sorry. :-( Eventually, we will expand this API routine to accept more values, probably starting with something like H5F_LIBVER_1_6 or H5F_LIBVER_1_8. However, we need to do the work inside the HDF5 library to allow this sort of change to be enforced and we haven't had time/funding to get this done yet. It's very important to various user communities, so I'm hoping we'll get this feature finished in a reasonable time-frame.

The "least version necessary" design of the HDF5 library should make calling this routine unnecessary however. As long as you always request link and/or attribute creation order on each object in the file (including the root group, with the file creation property, as you do), you should get the 1.8 features you need without "forcing" the issue. The call is mostly a convenience routine for getting the versions of the format specified, without enabling any particular features. What happens if you comment out that call in the netCDF-4 library?

        Quincey