[ HDF5 Tutorial Top ] [ Introductory Topics Top ] [ Next ] [ Prev ]

Creating an HDF5 File


Contents:


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.

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

  1. Specify the file creation and access property lists, if necessary.
  2. Create the file.
  3. 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:

C:

   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.

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

Remarks

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>


NCSA
The National Center for Supercomputing Applications

University of Illinois at Urbana-Champaign

hdfhelp@ncsa.uiuc.edu

Last Modified: November 21, 2001