Page tree

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 H5D_READ and H5D_WRITE 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

/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
 * Copyright by The HDF Group.                                               *
 * Copyright by the Board of Trustees of the University of Illinois.         *
 * All rights reserved.                                                      *
 *                                                                           *
 * This file is part of HDF5.  The full HDF5 copyright notice, including     *
 * terms governing use, modification, and redistribution, is contained in    *
 * the files COPYING and Copyright.html.  COPYING can be found at the root   *
 * of the source code distribution tree; Copyright.html can be found at the  *
 * root level of an installed copy of the electronic HDF5 document set and   *
 * is linked from the top-level documents page.  It can also be found at     *
 * http://hdfgroup.org/HDF5/doc/Copyright.html.  If you do not have          *
 * access to either file, you may request a copy from help@hdfgroup.org.     *
 * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */

/* 
 *  This example illustrates how to write and read data in an existing
 *  dataset.  It is used in the HDF5 Tutorial.
 */

#include "hdf5.h"
#define FILE "dset.h5"

int main() {

   hid_t       file_id, dataset_id;  /* identifiers */
   herr_t      status;
   int         i, j, dset_data[4][6];

   /* Initialize the dataset. */
   for (i = 0; i < 4; i++)
      for (j = 0; j < 6; j++)
         dset_data[i][j] = i * 6 + j + 1;

   /* Open an existing file. */
   file_id = H5Fopen(FILE, H5F_ACC_RDWR, H5P_DEFAULT);

   /* Open an existing dataset. */
   dataset_id = H5Dopen2(file_id, "/dset", H5P_DEFAULT);

   /* Write the dataset. */
   status = H5Dwrite(dataset_id, H5T_NATIVE_INT, H5S_ALL, H5S_ALL, H5P_DEFAULT, 
                     dset_data);

   status = H5Dread(dataset_id, H5T_NATIVE_INT, H5S_ALL, H5S_ALL, H5P_DEFAULT, 
                    dset_data);

   /* Close the dataset. */
   status = H5Dclose(dataset_id);

   /* Close the file. */
   status = H5Fclose(file_id);
}

 Fortran

! * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
!   Copyright by The HDF Group.                                               *
!   Copyright by the Board of Trustees of the University of Illinois.         *
!   All rights reserved.                                                      *
!                                                                             *
!   This file is part of HDF5.  The full HDF5 copyright notice, including     *
!   terms governing use, modification, and redistribution, is contained in    *
!   the files COPYING and Copyright.html.  COPYING can be found at the root   *
!   of the source code distribution tree; Copyright.html can be found at the  *
!   root level of an installed copy of the electronic HDF5 document set and   *
!   is linked from the top-level documents page.  It can also be found at     *
!   http://hdfgroup.org/HDF5/doc/Copyright.html.  If you do not have          *
!   access to either file, you may request a copy from help@hdfgroup.org.     *
! * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
!
!
! The following example shows how to write and read to/from an existing dataset.
! It opens the file created in the previous example, obtains the dataset
! identifier, writes the data to the dataset in the file,
! then reads the dataset  to memory.
!
! This example is used in the HDF5 Tutorial.

PROGRAM H5_RDWT

  USE HDF5 ! This module contains all necessary modules

  IMPLICIT NONE

  CHARACTER(LEN=8), PARAMETER :: filename = "dsetf.h5" ! File name
  CHARACTER(LEN=4), PARAMETER :: dsetname = "dset"     ! Dataset name

  INTEGER(HID_T) :: file_id       ! File identifier
  INTEGER(HID_T) :: dset_id       ! Dataset identifier

  INTEGER     ::   error ! Error flag
  INTEGER     ::  i, j

  INTEGER, DIMENSION(4,6) :: dset_data, data_out ! Data buffers
  INTEGER(HSIZE_T), DIMENSION(2) :: data_dims

  !
  ! Initialize the dset_data array.
  !
  DO i = 1, 4
     DO j = 1, 6
        dset_data(i,j) = (i-1)*6 + j
     END DO
  END DO

  !
  ! Initialize FORTRAN interface.
  !
  CALL h5open_f(error)

  !
  ! Open an existing file.
  !
  CALL h5fopen_f (filename, H5F_ACC_RDWR_F, file_id, error)

  !
  ! Open an existing dataset.
  !
  CALL h5dopen_f(file_id, dsetname, dset_id, error)

  !
  ! Write the dataset.
  !
  data_dims(1) = 4
  data_dims(2) = 6
  CALL h5dwrite_f(dset_id, H5T_NATIVE_INTEGER, dset_data, data_dims, error)

  !
  ! Read the dataset.
  !
  CALL h5dread_f(dset_id, H5T_NATIVE_INTEGER, data_out, data_dims, error)

  !
  ! Close the dataset.
  !
  CALL h5dclose_f(dset_id, error)

  !
  ! Close the file.
  !
  CALL h5fclose_f(file_id, error)

  !
  ! Close FORTRAN interface.
  !
  CALL h5close_f(error)

END PROGRAM H5_RDWT



 C++

/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
 * Copyright by The HDF Group.						     *
 * Copyright by the Board of Trustees of the University of Illinois.	     *
 * All rights reserved.							     *
 *	                                                                     *
 * This file is part of HDF5.  The full HDF5 copyright notice, including     *
 * terms governing use, modification, and redistribution, is contained in    *
 * the files COPYING and Copyright.html.  COPYING can be found at the root   *
 * of the source code distribution tree; Copyright.html can be found at the  *
 * root level of an installed copy of the electronic HDF5 document set and   *
 * is linked from the top-level documents page.  It can also be found at     *
 * http://hdfgroup.org/HDF5/doc/Copyright.html.  If you do not have	     *
 * access to either file, you may request a copy from help@hdfgroup.org.     *
 * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */

/*
 *  This example illustrates how to write to and read from an existing
 *  dataset. It is used in the HDF5 Tutorial.
 */

#include <iostream>
#include <string>

#include "H5Cpp.h"

#ifndef H5_NO_NAMESPACE
    using namespace H5;
#endif

const H5std_string	FILE_NAME("h5tutr_dset.h5");
const H5std_string	DATASET_NAME("dset");
const int 	DIM0 = 4;	               // dataset dimensions
const int 	DIM1 = 6;

int main (void)
{
    
    // Data initialization.
     
    int i, j;
    int data[DIM0][DIM1];	    // buffer for data to write

    for (j = 0; j < DIM0; j++)
	for (i = 0; i < DIM1; i++)
	 data[j][i] = i * 6 + j + 1;

    // Try block to detect exceptions raised by any of the calls inside it
    try
    {
	// Turn off the auto-printing when failure occurs so that we can
	// handle the errors appropriately
	Exception::dontPrint();

	// Open an existing file and dataset.
	H5File file(FILE_NAME, H5F_ACC_RDWR);
	DataSet dataset = file.openDataSet(DATASET_NAME);

	// Write the data to the dataset using default memory space, file
	// space, and transfer properties.
	dataset.write(data, PredType::NATIVE_INT);

    }  // end of try block

    // catch failure caused by the H5File operations
    catch(FileIException error)
    {
	error.printError();
	return -1;
    }

    // catch failure caused by the DataSet operations
    catch(DataSetIException error)
    {
	error.printError();
	return -1;
    }

    return 0;  // successfully terminated
}

Python

Note that H5S_ALL is passed in for both the memory and file dataspace parameters in the read and write calls. This indicates that the entire dataspace of the dataset will be read or written to. H5S_ALL by itself does not necessarily have this meaning. See the Reference Manual entry for H5Dread or H5Dwrite for more information on using H5S_ALL.

See HDF5 Introductory Examples for the examples used in the Learning the Basics tutorial. There are examples for several other languages, including Java.

For details on compiling an HDF5 application: [ Compiling HDF5 Applications ]

Remarks

H5F_OPEN opens an existing file and returns a file identifier.

H5D_OPEN opens an existing dataset with the specified name and location.

H5D_WRITE 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. Specifying H5S_ALL for both the memory and file dataspaces indicates that the entire dataspace of the dataset is to be written to. H5S_ALL by itself does not necessarily have this meaning. See the Reference Manual entry for H5Dwrite for more information on using H5S_ALL.

H5D_READ reads raw data from the specified dataset to an application buffer, converting from the file datatype and dataspace to the memory datatype and dataspace. Specifying H5S_ALL for both the memory and file dataspaces indicates that the entire dataspace of the dataset is to be read. H5S_ALL by itself does not necessarily have this meaning. See the Reference Manual entry for H5Dread for more information on using H5S_ALL.

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: December 18, 2017 | 01:58 PM