Creating an HDF5 File

What is an HDF5 file?

An HDF5 file is a binary file containing scientific data and supporting metadata. The primary types of objects stored in an HDF5 file, groups and datasets, will be discussed in other sections of this tutorial.

To create a file, an application must specify a filename, file access mode, file creation property list, and file access property list.

File access mode:
When creating a file, the file access mode specifies the action to take if the file already exists:
- H5F_ACC_TRUNC specifies that if the file already exists, the current contents will be deleted so that the application can rewrite the file with new data.
- H5F_ACC_EXCL specifies that the open is to fail if the file already exists.
- If the file does not already exist, the file access parameter is ignored.
- In all cases, the application has both read and write access to a successfully created file.
Note that there are two different access modes for opening exisitng files:
- H5F_ACC_RDONLY specifies that the application has read access but will not be allowed to write any data.
- H5F_ACC_RDWR specifies that the application has read and write access.
For further information, see The File Interface (H5F) section of the HDF5 User's Guide and the H5F: File Interface section of the HDF5 Reference Manual.
File creation property list:
The file creation property list is used to control the file metadata. File metadata contains information about the size of the user-block, the size of various file data structures used by the HDF5 library, etc. In this tutorial, the default file creation property list, H5P_DEFAULT, is used.
The user-block is a fixed-length block of data located at the beginning of the file which is ignored by the HDF5 library. The user-block may be used to store any data or information found to be useful to applications.
For further information, see The File Interface (H5F) section of the HDF5 User's Guide.
File access property list:
The file access property list is used to control different methods of performing I/O on files. The default file access property list, H5P_DEFAULT, is used in this tutorial.
For further information, see The File Interface (H5F) section of the HDF5 User's Guide.

The steps to create and close an HDF5 file are as follows:

Specify the file creation and access property lists, if necessary.
Create the file.
Close the file and close the property lists, if necessary.

To create an HDF5 file, the calling program must contain calls to create and close the file. For example:

   file_id = H5Fcreate (filename, access_mode, create_id, access_id);
   status = H5Fclose (file_id);

FORTRAN:

   CALL h5fcreate_f (filename, access_mode, file_id, hdferr, &
            creation_prp=create_id, access_prp=access_id)
        or
   CALL h5fcreate_f (filename, access_mode, file_id, hdferr)

   CALL h5fclose_f (file_id, hdferr)

In FORTRAN, the file creation property list, creation_prp, and file access property list, access_prp, are optional parameters; they can be omitted if the default values are to be used.

Programming Example

Description

The following example demonstrates how to create and close an HDF5 file. It creates a file called file.h5 in the C version, filef.h5 in FORTRAN, and then closes the file.

h5_crtfile.c

fileexample.f90

CreateFile.java

NOTE: To download a tar file of all of the examples, including a Makefile, please go to the References page.

Remarks

In C: The include file hdf5.h contains definitions and declarations and must be included in any program that uses the HDF5 library.
In FORTRAN: The module HDF5 contains definitions and declarations and must be used in any program that uses the HDF5 library.
H5Fcreate/h5fcreate_f creates an HDF5 file and returns the file identifier.
```
C:       
  hid_t H5Fcreate (const char *name, unsigned access_mode, hid_t creation_prp, 
                   hid_t access_prp) 
FORTRAN: 
  h5fcreate_f (name, access_mode, file_id, hdferr, creation_prp, access_prp)

           name          CHARACTER(LEN=*)
           access_flag   INTEGER 
                         (Valid values: H5F_ACC_RDWR_F, H5F_ACC_RDONLY_F, 
                         H5F_ACC_TRUNC_F, H5F_ACC_EXCL_F, H5F_ACC_DEBUG_F)
           file_id       INTEGER(HID_T)
           hdferr        INTEGER 
                         (Valid values: 0 on success and -1 on failure)
           creation_prp  INTEGER(HID_T), OPTIONAL
                         (Default value: H5P_DEFAULT_F)
           access_prp    INTEGER(HID_T), OPTIONAL
                         (Default value: H5P_DEFAULT_F) 
         
```
- The name parameter specifies the name of the file to be created.
- The access_mode parameter specifies the file access mode. H5F_ACC_TRUNC (H5F_ACC_TRUNC_F in FORTRAN) will truncate a file if it already exists.
- The creation_prp parameter specifies the file creation property list. For C, using H5P_DEFAULT indicates that the default file creation property list is to be used. This option is optional in FORTRAN; if it is omitted, the default file creation property list, H5P_DEFAULT_F, is used.
- The access_prp parameter specifies the file access property list. For C, using H5P_DEFAULT indicates that the default file creation property list is to be used. This option is optional in FORTRAN; if it is omitted, the default file creation property list, H5P_DEFAULT_F, is used.
- In C, this function returns the file identifier if successful and a negative value otherwise. In FORTRAN, the file identifier is returned in the file_id parameter. If the call is successful, 0 (zero) is passed back in the hdferr parameter. Otherwise, hdferr will have a value of -1.
When a file is no longer accessed by a program, H5Fclose/h5fclose_f must be called to release the resources used by the file. This call is mandatory.
```
C:
    herr_t H5Fclose (hid_t file_id) 

FORTRAN:
    h5fclose_f(file_id, hdferr)
```
The root group is automatically created when a file is created. Every file has a root group and the path name of the root group is always /.

File Contents

The HDF team has developed tools for examining the contents of HDF5 files. The tool used in this tutorial is the HDF5 dumper, h5dump, which displays the file contents in human-readable form. The output of h5dump is an ASCII display formatted according to the HDF5 DDL grammar. This grammar is defined, using Backus-Naur Form, in the DDL in BNF for HDF5.

To view the file contents, type:

   h5dump <filename>

Figure 4.1 describes the file contents of file.h5 (filef.h5) using a directed graph. The directed graphs in this tutorial use an oval to represent an HDF5 group and a rectangle to represent an HDF5 dataset (none in this example). Arrows indicate the inclusion direction of the contents (none in this example).

Fig. 4.1 Contents of file.h5 (filef.h5)

Figure 4.2 is the text description of file.h5, as generated by h5dump. The HDF5 file called file.h5 contains a group called /, or the root group. (The file called filef.h5, created by the FORTRAN version of the example, has the same output except that the filename shown is filef.h5.)

Fig. 4.2 file.h5 in DDL


         HDF5 "file.h5" {
         GROUP "/" {
         }
         }

File Definition in DDL

Figure 4.3 is the simplified DDL file definition for creating an HDF5 file. For simplicity, a simplified DDL is used in this tutorial. A complete and more rigorous DDL can be found in the DDL in BNF for HDF5, a section of the HDF5 User's Guide.

Fig. 4.3 HDF5 File Definition

The following symbol definitions are used in the DDL:


        ::=               defined as
        <tname>           a token with the name tname
        <a> | <b>         one of <a> or <b>
        <a>*              zero or more occurrences of <a>

The simplified DDL for file definition is as follows:

        <file> ::= HDF5 "<file_name>" { <root_group> }

        <root_group> ::= GROUP "/" { <group_attribute>* <group_member>* }

        <group_attribute> ::= <attribute>

        <group_member> ::= <group> | <dataset>

The National Center for Supercomputing Applications
University of Illinois at Urbana-Champaign

hdfhelp@ncsa.uiuc.edu
Describes HDF5 Release 1.2.2, June 2000