next up previous index
Next: HDF5 Groups Up: Creating and Structuring HDF5 Previous: Exercise

HDF5 Attributes

In this section we are going to annotate the dataset with an attribute. Attributes, as remarked earlier, are really small datasets. But they have their own functions for attribute creation, writing, reading and closing. Here is the example program, which illustrates how to use these functions.

/*
 *   Creating a dataset attribute.
 */

#include "hdf5.h"
#define FILE "dset.h5"

main() {

   hid_t       file_id, dataset_id, attribute_id, dataspace_id;  /* identifiers */
   hsize_t     dims;
   int         attr_data[2];
   herr_t      status;

   /* Initialize the attribute data. */
   attr_data[0] = 100;
   attr_data[1] = 200;

   /* Open an existing file. */
   file_id = H5Fopen(FILE, H5F_ACC_RDWR, H5P_DEFAULT);

   /* Open an existing dataset. */
   dataset_id = H5Dopen(file_id, "/dset");

   /* Create the data space for the attribute. */
   dims = 2;
   dataspace_id = H5Screate_simple(1, &dims, NULL);

   /* Create a dataset attribute. */
   attribute_id = H5Acreate(dataset_id, "Units", H5T_STD_I32BE, dataspace_id, H5P_DEFAULT);

   /* Write the attribute data. */
   status = H5Awrite(attribute_id, H5T_NATIVE_INT, attr_data);

   /* Close the attribute. */
   status = H5Aclose(attribute_id);

   /* Close the dataspace. */
   status = H5Sclose(dataspace_id);

   /* Close to the dataset. */
   status = H5Dclose(dataset_id);

   /* Close the file. */
   status = H5Fclose(file_id);
}
The program is compiled with h5cc:
gustav@bh1 $ h5cc -o h5_crtatt h5_crtatt.c
gustav@bh1 $
And now let me show you that it indeed adds an attribute to the dataset:
gustav@bh1 $ h5dump dset.h5
HDF5 "dset.h5" {
GROUP "/" {
   DATASET "dset" {
      DATATYPE  H5T_STD_I32BE
      DATASPACE  SIMPLE { ( 4, 6 ) / ( 4, 6 ) }
      DATA {
         1, 2, 3, 4, 5, 6,
         7, 8, 9, 10, 11, 12,
         13, 14, 15, 16, 17, 18,
         19, 20, 21, 22, 23, 24
      }
   }
}
}
gustav@bh1 $ ./h5_crtatt
gustav@bh1 $ h5dump dset.h5
HDF5 "dset.h5" {
GROUP "/" {
   DATASET "dset" {
      DATATYPE  H5T_STD_I32BE
      DATASPACE  SIMPLE { ( 4, 6 ) / ( 4, 6 ) }
      DATA {
         1, 2, 3, 4, 5, 6,
         7, 8, 9, 10, 11, 12,
         13, 14, 15, 16, 17, 18,
         19, 20, 21, 22, 23, 24
      }
      ATTRIBUTE "Units" {
         DATATYPE  H5T_STD_I32BE
         DATASPACE  SIMPLE { ( 2 ) / ( 2 ) }
         DATA {
            100, 200
         }
      }
   }
}
}
gustav@bh1 $

So, it works then.

The program begins with the initialization of the attribute data array:

   attr_data[0] = 100;
   attr_data[1] = 200;
Then we open the file and the dataset as before. Next we create the dataspace for the attribute, and this works exactly the same way as for the datasets:
   dims = 2;
   dataspace_id = H5Screate_simple(1, &dims, NULL);
and finally we create the attribute itself:
   attribute_id = H5Acreate(dataset_id, "Units", H5T_STD_I32BE, dataspace_id, H5P_DEFAULT);
Function  H5Acreate belongs to the family of functions for manipulations of attributes. Their names begin with H5A, where A stands for attribute. The function takes the following arguments: Observe that these parameters are exactly the same as the parameters used by H5Dcreate, but you must not use the latter function here. Attributes are attributes and datasets are datasets. HDF5 is fussy about this.

Once we have created the attribute we are going to fill it with data. This we do by calling function  H5Awrite, which is markedly simpler than H5Dwrite, this is where the difference between datasets and attributes becomes more apparent:

   status = H5Awrite(attribute_id, H5T_NATIVE_INT, attr_data);
This function takes just three arguments: the attribute identifier, the memory data type and the data buffer itself. The memory data type is, of course, native, and so HDF5 functions will have to perform the translation to the 32-bit big-endian requested when the attribute was created.

Now we have to close the attribute by calling  H5Aclose - it takes just one argument, namely the attribute identifier, and the we close all other things we've opened before, i.e., the dataspace, the dataset and the datafile itself:

   /* Close the attribute. */
   status = H5Aclose(attribute_id);

   /* Close the dataspace. */
   status = H5Sclose(dataspace_id);

   /* Close to the dataset. */
   status = H5Dclose(dataset_id);

   /* Close the file. */
   status = H5Fclose(file_id);


next up previous index
Next: HDF5 Groups Up: Creating and Structuring HDF5 Previous: Exercise
Zdzislaw Meglicki
2004-04-29