[ HDF5 Tutorial Top ]

# Reading from and Writing to a Dataset

## Contents:

- Reading from and Writing to a Dataset
- Programming Example
  - Description
  - Remarks
  - File Contents

## 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:

1. Obtain the dataset identifier.
2. Specify the memory datatype.
3. Specify the memory dataspace.
4. Specify the file dataspace.
5. Specify the transfer properties.
6. Perform the desired operation on the dataset.
7. Close the dataset.
8. 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, 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, error)

       CALL h5dwrite_f(dset_id, mem_type_id, buf, 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, error)

## 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 from memory. It then closes the dataset and file.

[ C Example ] - `h5_rdwt.c`
[ FORTRAN Example ] - `rwdsetexample.f90`
[ Java Example ] - `DatasetRdWt.java`

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

### Remarks

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

      C:
        hid_t H5Fopen (const char *name, unsigned access_mode, hid_t access_prp)

      FORTRAN:
        h5fopen_f (name, access_mode, file_id, hdferr, access_prp)

              name         CHARACTER(LEN=*)
              access_mode  INTEGER
                           (Possible values: H5F_ACC_RDWR_F, H5F_ACC_RDONLY_F)
              file_id      INTEGER(HID_T)
              hdferr       INTEGER
                           (Possible values: 0 on success and -1 on failure)
              access_prp   INTEGER(HID_T), OPTIONAL

  - The argument name is the filename.

  - The access_mode parameter is the file access mode. `H5F_ACC_RDWR` in C (`H5F_ACC_RDWR_F` in FORTRAN) allows read/write access while `H5F_ACC_RDONLY` in C (`H5F_ACC_RDONLY_F` in FORTRAN) allows read-only access.

  - The access_prp parameter identifies the file access property list. `H5P_DEFAULT` in C and `H5P_DEFAULT_F` in FORTRAN specify the default file access property list. This parameter is optional in FORTRAN; if it is omitted, the default file access property list is used.

  - In FORTRAN, the return code is passed back in the hdferr parameter: 0 if successful, -1 if not. In C, the function returns the file identifier if successful, and a negative value otherwise.

- `H5Dopen`/`h5dopen_f` opens an existing dataset with the name specified by name at the location specified by loc_id. For FORTRAN, the return value is passed in the hdferr parameter: 0 if successful, -1 if not. For C, the function returns the dataset identifier if successful, and a negative value if not.

  C:

        hid_t H5Dopen (hid_t loc_id, const char *name)

  FORTRAN:

        h5dopen_f(loc_id, name, hdferr)

              loc_id   INTEGER(HID_T)
              name     CHARACTER(LEN=*)
              hdferr   INTEGER
                       (Possible values: 0 on success and -1 on failure)

- `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.

  C:

        herr_t H5Dwrite (hid_t dset_id, hid_t mem_type_id, hid_t mem_space_id,
                         hid_t file_space_id, hid_t xfer_prp, const void * buf)

  FORTRAN:

        h5dwrite_f (dset_id, mem_type_id, buf, hdferr, mem_space_id, &
                                             file_space_id, xfer_prp)

              dset_id        INTEGER(HID_T)
              mem_type_id    INTEGER(HID_T)
              buf(*,...*)    TYPE
              hdferr         INTEGER
                             (Possible values: 0 on success and -1 on failure)
              mem_space_id   INTEGER(HID_T), OPTIONAL
                             (Default value: H5S_ALL_F)
              file_space_id  INTEGER(HID_T), OPTIONAL
                             (Default value: H5S_ALL_F)
              xfer_prp       INTEGER(HID_T), OPTIONAL
                             (Default value: H5P_DEFAULT_F)

  - The dset_id is the dataset identifier.

  - The mem_type_id parameter is the identifier of the dataset's memory datatype. `H5T_NATIVE_INT` in C (`H5T_NATIVE_INTEGER` in FORTRAN) is an integer datatype for the machine on which the library was compiled.

  - The mem_space_id parameter is the identifier of the dataset's memory dataspace. `H5S_ALL` in C (`H5S_ALL_F` in FORTRAN) is the default value and indicates that the whole dataspace in memory is selected for the I/O operation. This parameter is optional in FORTRAN; if it is omitted, the default will be used.

  - The file_space_id parameter is the identifier of the dataset's file dataspace. `H5S_ALL` in C (`H5S_ALL_F` in FORTRAN) is the default value and indicates that the entire dataspace of the dataset in the file is selected for the I/O operation. This parameter is optional in FORTRAN; if it is omitted, the default will be used.

  - The xfer_prp parameter is the data transfer propery list identifier. `H5P_DEFAULT` in C (`H5P_DEFAULT_F` in FORTRAN) is the default value and indicates that the default data transfer property list is used. This parameter is optional in FORTRAN; if it is omitted, the default will be used.

  - The buf parameter is the data buffer to write.

  - In FORTRAN, the hdferr parameter is for the error code passed back: 0 if successful, -1 if not. In C, this function returns a non-negative value if successful; otherwise it returns a negative value.

- `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.

  C:

        herr_t H5Dread (hid_t dset_id, hid_t mem_type_id, hid_t mem_space_id,
                        hid_t file_space_id, hid_t xfer_prp, void * buf)

  FORTRAN:

        h5dread_f (dset_id, mem_type_id, buf, hdferr, mem_space_id, &
                        file_space_id, xfer_prp)

              dset_id        INTEGER(HID_T)
              mem_type_id    INTEGER(HID_T)
              buf(*,...*)    TYPE
              hdferr         INTEGER
                             (Possible values: 0 on success and -1 on failure)
              mem_space_id   INTEGER(HID_T), OPTIONAL
                             (Default value: H5S_ALL_F)
              file_space_id  INTEGER(HID_T), OPTIONAL
                             (Default value: H5S_ALL_F)
              xfer_prp       INTEGER(HID_T), OPTIONAL
                             (Default value: H5P_DEFAULT_F)

  - The dset_id parameter is the dataset identifier.

  - The mem_type_id parameter is the identifier of the dataset's memory datatype. `H5T_NATIVE_INT` in C (`H5T_NATIVE_INTEGER` in FORTRAN) is an integer datatype for the machine on which the library was compiled.

  - The mem_space_id parameter is the identifier of the dataset's memory dataspace. `H5S_ALL` in C (`H5S_ALL_F` in FORTRAN) is the default value and indicates that the whole dataspace in memory is selected for the I/O operation. This parameter is optional in FORTRAN; if it is omitted, the default will be used.

  - The file_space_id parameter is the identifier of the dataset's file dataspace. `H5S_ALL` in C (`H5S_ALL_F` in FORTRAN) is the default value and indicates that the entire dataspace of the dataset in the file is selected for the I/O operation. This parameter is optional in FORTRAN; if it is omitted, the default will be used.

  - The xfer_prp parameter is the data transfer propery list identifier. `H5P_DEFAULT` in C (`H5P_DEFAULT_F` in FORTRAN) is the default value and indicates that the default data transfer property list is used. This parameter is optional in FORTRAN; if it is omitted, the default will be used.

  - The buf parameter is the data buffer to read into.

  - In FORTRAN, the hdferr parameter is for the error code passed back: 0 if successful, -1 if not. In C, this function returns a non-negative value if successful; otherwise it returns a negative value.

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

The National Center for Supercomputing Applications
University of Illinois at Urbana-Champaign
hdfhelp@ncsa.uiuc.edu

###### Last Modified: June 22, 2001