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.

   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.

h5_rdwt.c

rwdsetexample.f90

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

Reading from and Writing to a Dataset

Contents: