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

HDF5 File Creation

The first program we are going to look at does just this: it creates an HDF5 file, then closes it and goes away. The file is largely empty, meaning that there is going to be the top level group in it, but nothing else. We are going to add more structure to it later.

Here is the program:

/*
 *    Creating and closing a file.
 */

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

main() {

   hid_t       file_id;   /* file identifier */
   herr_t      status;

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

   /* Terminate access to the file. */
   status = H5Fclose(file_id); 
}
Now I am going to compile and run this program:
gustav@bh1 $ pwd
/N/B/gustav/src/I590/HDF5
gustav@bh1 $ which h5cc
/N/B/gustav/bin/h5cc
gustav@bh1 $ h5cc -o h5_crtfile h5_crtfile.c
gustav@bh1 $ ./h5_crtfile
gustav@bh1 $
The program executes quietly and creates file file.h5 in the working directory. Let us have a look at it with h5dump:
gustav@bh1 $ h5dump file.h5
HDF5 "file.h5" {
GROUP "/" {
}
}
gustav@bh1 $
Well, there is the top level group in it and nothing more.

Function  H5Fcreate creates an HDF5 file. It belongs to the class of File API Functions. All functions in this class have names that begin with H5F. You will learn about other classes soon enough. The third letter in an HDF5 function name always indicates the class the function belongs to.

Function H5Fcreate takes four arguments. The first one is the string that corresponds to the file's name. The second argument is a flag that specifies how the file should be created. There are two flags you can use in this place:

H5F_ACC_TRUNC
which  specifies that if you are trying to create a file that exists already, the existing file will be truncated, i.e., all data stored on the original file will be erased;
H5F_ACC_EXCL
which  specifies that if you are trying to create a file that exists already, the function should return error. The error is returned as a negative integer, otherwise the function returns a file identifier, which, technically, is a positive integer.
The third argument is the file creation property list   and the fourth argument is   the file access property list. We'll talk about the property lists later and in the meantime we are going to use the default  indicator H5P_DEFAULT.

The file identifier is an opaque variable  of type hid_t, which is defined on H5Ipublic.h to be a signed integer, so this is why you can use it at the same time for an error indicator. If H5Fcreate fails for whatever reason, the value of the identifier returned is going to be negative.

The file creation operation opens the newly created file at the same time. The file is now available for further operations on it.

Having created the file we close it with the call to  H5Fclose. This call just takes the file identifier, previously returned by the call to H5Fcreate, as its sole argument and returns the status of the operation on status, which is a variable of type  herr_t, defined on H5public.h as a signed integer. It is negative in case an error has been detected and positive otherwise.


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