HDF5 Tutorial: Introductory Topics
Reading from and Writing to a Dataset

Reading from and Writing to a Dataset

During a dataset I/O operation, the library transfers raw data between memory and the file. The data in memory can have a datatype different from that of the file and can also be of a different size (i.e., the data in memory is a subset of the dataset elements, or vice versa). Therefore, to perform read or write operations, the application program must specify:

» The dataset
» The dataset's datatype in memory
» The dataset's dataspace in memory
» The dataset's dataspace in the file
» The dataset transfer property list

(The dataset transfer property list controls various aspects of the I/O operations, such as the number of processes participating in a collective I/O request or hints to the library to control caching of raw data. In this tutorial, we use the default dataset transfer property list.)

» The data buffer

The steps to read from or write to a dataset are as follows:

» Obtain the dataset identifier.
» Specify the memory datatype.
» Specify the memory dataspace.
» Specify the file dataspace.
» Specify the transfer properties.
» Perform the desired operation on the dataset.
» Close the dataset.
» Close the dataspace, datatype, and property list if necessary.

To read from or write to a dataset, the H5Dread /h5dread_f and H5Dwrite / h5dwrite_f routines are used.

C:
   status = H5Dread (set_id, mem_type_id, mem_space_id, file_space_id,
                     xfer_prp, buf );
   status = H5Dwrite (set_id, mem_type_id, mem_space_id, file_space_id,
                     xfer_prp, buf);

FORTRAN:
   CALL h5dread_f(dset_id, mem_type_id, buf, dims, error, &
                     mem_space_id=mspace_id, file_space_id=fspace_id, &
                     xfer_prp=xfer_plist_id)
        or
   CALL h5dread_f(dset_id, mem_type_id, buf, dims,  error)


   CALL h5dwrite_f(dset_id, mem_type_id, buf, dims, error, &
                     mem_space_id=mspace_id, file_space_id=fspace_id, &
                     xfer_prp=xfer_plist_id)
        or
   CALL h5dwrite_f(dset_id, mem_type_id, buf, dims, error)

High Level APIs

The High Level HDF5 Lite APIs include functions that simplify and condense the steps for creating and reading datasets. Please be sure to review them, in addition to this tutorial.

Programming Example

Description

The following example shows how to read and write an existing dataset. It opens the file created in the previous example, obtains the dataset identifier for the dataset /dset, writes the dataset to the file, then reads the dataset back. It then closes the dataset and file.

C Example (using HDF5 1.8)

h5_rdwt18.c

C Example (using HDF5 1.6)

h5_rdwt.c

FORTRAN Example

rwdsetexample.f90

For details on compiling an HDF5 application: [ click here ]

Remarks

H5Fopen / h5fopen_f opens an existing file and returns a file identifier.

H5Dopen / h5dopen_f opens an existing dataset with the specified name and location.

H5Dwrite / h5dwrite_f writes raw data from an application buffer to the specified dataset, converting from the datatype and dataspace of the dataset in memory to the datatype and dataspace of the dataset in the file.

H5Dread / h5dread_f reads raw data from the specified dataset to an application buffer, converting from the file datatype and dataspace to the memory datatype and dataspace.

File Contents

Figure 6.1a shows the contents of dset.h5 (created by the C program).
Figure 6.1b shows the contents of dsetf.h5 (created by the FORTRAN program).

Fig. 6.1a dset.h5 in DDL

      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
            }
         }
      }
      }

Fig. 6.1b dsetf.h5 in DDL

HDF5 "dsetf.h5" {
GROUP "/" {
   DATASET "dset" {
      DATATYPE { H5T_STD_I32BE }
      DATASPACE { SIMPLE ( 6, 4 ) / ( 6, 4 ) }
      DATA {
         1, 7, 13, 19,
         2, 8, 14, 20,
         3, 9, 15, 21,
         4, 10, 16, 22,
         5, 11, 17, 23,
         6, 12, 18, 24
      }
   }
}
}

- - Last modified:August 19th 2008

HDF5 Tutorial: Introductory TopicsReading from and Writing to a Dataset