next up previous index
Next: Writing On and Reading Up: Creating and Structuring HDF5 Previous: HDF5 File Creation

HDF5 Datasets

In this example we are going to do more than just create an empty HDF5 file. We are going to create a file and then we are going to create a dataset within its top level group. But we are still going to postpone filling the dataset with any data. The file system equivalent of this operation is to create an empty file in, say, a top level directory of some file system, and then fill the file with nulls, just so as to reserve sufficient space for the file itself.

Here is the program:

/*
 *   Creating and closing a dataset.
 */

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

main() {

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

   /* Create a new file using default properties. */
   file_id = H5Fcreate(FILE, H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT);

   /* Create the data space for the dataset. */
   dims[0] = 4; 
   dims[1] = 6; 
   dataspace_id = H5Screate_simple(2, dims, NULL);

   /* Create the dataset. */
   dataset_id = H5Dcreate(file_id, "/dset", H5T_STD_I32BE, dataspace_id, H5P_DEFAULT);

   /* End access to the dataset and release resources used by it. */
   status = H5Dclose(dataset_id);

   /* Terminate access to the data space. */ 
   status = H5Sclose(dataspace_id);

   /* Close the file. */
   status = H5Fclose(file_id);
}
And here is how the program is compiled, linked, and run:
gustav@bh1 $ h5cc -o h5_crtdat h5_crtdat.c          
gustav@bh1 $ ./h5_crtdat
gustav@bh1 $ ls
dset.h5  h5_crtdat    h5_crtdat.o  h5_crtfile.c
file.h5  h5_crtdat.c  h5_crtfile   h5_crtfile.o
gustav@bh1 $
The program executes silently, but here you can again see that a new HDF5 file has been created, dset.h5. To see what's inside it use h5dump:
gustav@bh1 $ h5dump dset.h5
HDF5 "dset.h5" {
GROUP "/" {
   DATASET "dset" {
      DATATYPE  H5T_STD_I32BE
      DATASPACE  SIMPLE { ( 4, 6 ) / ( 4, 6 ) }
      DATA {
         0, 0, 0, 0, 0, 0,
         0, 0, 0, 0, 0, 0,
         0, 0, 0, 0, 0, 0,
         0, 0, 0, 0, 0, 0
      }
   }
}
}
gustav@bh1 $
So this program indeed created a file and then it created an empty fileset within it.

Let us have a look at the program.

After we have created the file itself with the call to H5Fcreate:

   file_id = H5Fcreate(FILE, H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT);
we are going to create first the space for the dataset. Functions that manipulate space that is then going to be allocated to datasets or attributes, all have their names beginning with H5S. The third letter, S, stands for space. The specific function we are going to call here is  H5Screate_simple
   dims[0] = 4; 
   dims[1] = 6; 
   dataspace_id = H5Screate_simple(2, dims, NULL);
It creates the so called simple space. When is the data space simple? If the data corresponds to a regular N-dimensional array of data points, e.g., data on a regular rectangular grid, then the corresponding data space is simple, otherwise it is called complex. So data on irregular grids, resulting from dynamic refinement of meshes, must be written on complex data spaces.

Function H5Screate_simple takes three arguments. The first argument is the rank of the array. In our case we are going to create space for an array of rank 2, i.e., a 2-dimensional matrix. The second argument is an array of length given by the first argument, whose entries specify the length of the matrix in each dimension. In our case we are going to have a $4\times6$ matrix filled with integers, so the second argument is [4,6].

Now the third argument would be used if we wanted to create a data space that could be stretched if, e.g., we wanted to fill the dataset with more data than originally intended. We can specify here up to how much the space can be stretched, e.g., up to the size of [400,600], or we could place no limits at all on its stretchability, in which case the third argument  would be [H5S_UNLIMITED,H5S_UNLIMITED]. If the third array is NULL, as is the case in this example, the generated data space is not-stretchable.

Arrays used in place of the second and third argument of H5Screate_simple are of type  hsize_t *, where hsize_t is defined on H5public.h to be size_t, which on the AVIDD system defaults to a 32-bit integer.

Function H5Screate_simple returns a dataset identifier, which is of the same type as a file identifier and other identifiers returned by other HDF5 function, i.e., hid_t.

Having created the space for the dataset, we are now ready to create the dataset itself. The dataset is created within the pre-allocated space by calling function  H5Dcreate:

   dataset_id = H5Dcreate(file_id, "/dset", H5T_STD_I32BE, dataspace_id, H5P_DEFAULT);
All functions that operate on datasets have their names beginning with H5D, where D stands for dataset. Function H5Dcreate takes five arguments:

Having created the dataset, we are now going to close it. This is like closing a file in a directory tree:

   status = H5Dclose(dataset_id);
Function  H5Dclose takes just one argument, the dataset identifier. Then we have to close the data space:
   status = H5Sclose(dataspace_id);
Here the function  H5Sclose also takes just one argument, namely the data space identifier. And finally we close the file itself:
   status = H5Fclose(file_id);

So this is how it all works. But$\ldots$ we still haven't filled the data set with any data. It's been merely created and sized, but it's filled with zeros. We are going to write real data on it in the next section.


next up previous index
Next: Writing On and Reading Up: Creating and Structuring HDF5 Previous: HDF5 File Creation
Zdzislaw Meglicki
2004-04-29