260 lines
7.7 KiB
HTML
260 lines
7.7 KiB
HTML
<HTML><HEAD>
|
|
<TITLE>HDF5 Tutorial - Reading to/Writing from a Dataset
|
|
</TITLE>
|
|
</HEAD>
|
|
|
|
<body bgcolor="#ffffff">
|
|
|
|
<!-- BEGIN MAIN BODY -->
|
|
|
|
<A HREF="http://www.ncsa.uiuc.edu/"><img border=0
|
|
src="http://www.ncsa.uiuc.edu/Images/NCSAhome/footerlogo.gif"
|
|
width=78 height=27 alt="NCSA"><P></A>
|
|
|
|
[ <A HREF="title.html"><I>HDF5 Tutorial Top</I></A> ]
|
|
<H1>
|
|
<BIG><BIG><BIG><FONT COLOR="#c101cd">Reading to/Writing from a Dataset</FONT>
|
|
</BIG></BIG></BIG></H1>
|
|
|
|
<hr noshade size=1>
|
|
|
|
<BODY>
|
|
<H2>Contents:</H2>
|
|
<UL>
|
|
<LI><A HREF="#rdwr">Reading to/Writing from a Dataset</A>
|
|
<LI> Programming Example
|
|
<UL>
|
|
<LI> <A HREF="#desc">Description </A>
|
|
<LI> <A HREF="#rem">Remarks</A>
|
|
<LI> <A HREF="#fc">File Contents</A>
|
|
</UL>
|
|
</UL>
|
|
<HR>
|
|
<A NAME="rdwr">
|
|
<H2>Reading to/Writing from a Dataset</h2>
|
|
<P>
|
|
During a dataset I/O operation, the library transfers raw data between memory
|
|
and the file. The memory can have a data type different than the file data type
|
|
and can also be a different size (memory is a subset of the dataset elements,
|
|
or vice versa). Therefore, to perform read or write operations, the application
|
|
program must specify:
|
|
<UL>
|
|
<LI> The dataset
|
|
|
|
<LI> The dataset's data type in memory
|
|
|
|
<LI> The dataset's dataspace in memory
|
|
|
|
<LI> The dataset's dataspace in the file
|
|
|
|
<LI> The transfer properties (The data transfer properties control various
|
|
aspects of the I/O operations like 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 transfer properties.)
|
|
|
|
<LI> The data buffer
|
|
</UL>
|
|
|
|
|
|
<P>
|
|
The steps to read to/write from a dataset are
|
|
as follows:
|
|
<OL>
|
|
<LI> Obtain the dataset identifier.
|
|
<LI> Specify the memory data type.
|
|
<LI> Specify the memory dataspace.
|
|
<LI> Specify the file dataspace.
|
|
<LI> Specify the transfer properties.
|
|
<LI> Perform the desired operation on the dataset.
|
|
<LI> Close the dataset.
|
|
<LI> Close the dataspace/data type, and property list if necessary.
|
|
</OL>
|
|
|
|
To read to/write from a dataset, the calling program must contain the following call:
|
|
<PRE>
|
|
H5Dread(dataset_id, mem_type_id, mem_space_id, file_space_id,
|
|
xfer_plist_id, buf );
|
|
</PRE>
|
|
or
|
|
<PRE>
|
|
H5Dwrite(dataset_id, mem_type_id, mem_space_id, file_space_id,
|
|
xfer_plist_id, buf);
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
<H2> Programming Example</H2>
|
|
<A NAME="desc">
|
|
<H3><U>Description</U></H3>
|
|
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,
|
|
<I>/dset</I>, writes the dataset to the file, then reads the dataset back from
|
|
memory. It then closes the dataset and file. <BR>
|
|
[ <A HREF="examples/h5_rdwt.c">Download h5_rdwt.c</A> ]
|
|
|
|
<PRE>
|
|
|
|
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
|
|
|
|
#include <hdf5.h>
|
|
#define FILE "dset.h5"
|
|
|
|
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 = H5Dopen(file_id, "/dset");
|
|
|
|
/* 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);
|
|
}
|
|
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
|
|
</PRE>
|
|
<A NAME="rem">
|
|
<H3><U>Remarks</U></H3>
|
|
<UL>
|
|
<LI> H5Fopen opens an existing file and returns a file identifier.
|
|
<PRE>
|
|
hid_t H5Fopen (const char *name, unsigned flags, hid_t access_id)
|
|
</PRE>
|
|
<UL>
|
|
<LI> The first argument is the file name.
|
|
|
|
<LI> The second argument is the file access mode. H5F_ACC_RDWR allows a file
|
|
to be read from and written to.
|
|
|
|
<LI> The third parameter is the identifier for the file access property list.
|
|
H5P_DEFAULT specifies the default file access property list.
|
|
</UL>
|
|
<P>
|
|
<LI> H5Dopen opens an existing dataset with the name specified by the second
|
|
argument at the location specified by the first parameter, and returns an
|
|
identifier.
|
|
<PRE>
|
|
hid_t H5Dopen (hid_t loc_id, const char *name)
|
|
</PRE>
|
|
<P>
|
|
<LI> H5Dwrite writes raw data from an application buffer to the specified
|
|
dataset, converting from the data type and data space of the dataset in
|
|
memory to the data type and data space of the dataset in the file.
|
|
<PRE>
|
|
herr_t H5Dwrite (hid_t dataset_id, hid_t mem_type_id, hid_t mem_space_id,
|
|
hid_t file_space_id, hid_t xfer_plist_id, const void * buf)
|
|
</PRE>
|
|
<UL>
|
|
<LI> The first parameter is the identifier of the dataset.
|
|
|
|
<LI> The second parameter is the identifier of the dataset's datatype in
|
|
memory. H5T_NATIVE_INT is an integer data type for the machine on which
|
|
the library was compiled.
|
|
|
|
<LI> The third parameter is the identifier of the dataset's dataspace in
|
|
memory. H5S_ALL indicates that the dataset's dataspace in memory is the
|
|
same as that in the file.
|
|
|
|
<LI> The fourth parameter is the identifier of the dataset's dataspace in the
|
|
file. H5S_ALL indicates that the entire dataspace of the dataset in the
|
|
file is referenced.
|
|
|
|
<LI> The fifth parameter is the identifier of the data transfer propery list.
|
|
H5P_DEFAULT indicates that the default data transfer property list is used.
|
|
|
|
<LI> The last parameter is the data buffer.
|
|
</UL>
|
|
<P>
|
|
<LI> H5Dread reads raw data from the specified dataset to an application buffer,
|
|
converting from the file datatype and dataspace to the memory datatype and
|
|
dataspace.
|
|
<PRE>
|
|
herr_t H5Dread (hid_t dataset_id, hid_t mem_type_id, hid_t mem_space_id,
|
|
hid_t file_space_id, hid_t xfer_plist_id, void * buf)
|
|
</PRE>
|
|
<UL>
|
|
<LI> The first parameter is the identifier of the dataset read from.
|
|
|
|
<LI> The second parameter is the identifier of the dataset's memory datatype.
|
|
|
|
<LI> The third parameter is the identifier of the dataset's memory dataspace.
|
|
|
|
<LI> The fourth parameter is the identifier of the dataset's file dataspace.
|
|
|
|
<LI> The fifth parameter is the identifier of the data transfer propery list.
|
|
|
|
<LI> The last parameter is the data buffer.
|
|
</UL>
|
|
</OL>
|
|
|
|
<A NAME="fc">
|
|
<H3><U>File Contents</U></H3>
|
|
Figure 6.1 shows the contents of 'dset.h5'.
|
|
<P>
|
|
<B>Fig. 6.1</B> <I>'dset.h5' in DDL</I>
|
|
<PRE>
|
|
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
|
|
}
|
|
}
|
|
}
|
|
}
|
|
</PRE>
|
|
|
|
|
|
|
|
|
|
<!-- BEGIN FOOTER INFO -->
|
|
|
|
<P><hr noshade size=1>
|
|
<font face="arial,helvetica" size="-1">
|
|
<a href="http://www.ncsa.uiuc.edu/"><img border=0
|
|
src="http://www.ncsa.uiuc.edu/Images/NCSAhome/footerlogo.gif"
|
|
width=78 height=27 alt="NCSA"><br>
|
|
The National Center for Supercomputing Applications</A><br>
|
|
<a href="http://www.uiuc.edu/">University of Illinois
|
|
at Urbana-Champaign</a><br>
|
|
<br>
|
|
<!-- <A HREF="helpdesk.mail.html"> -->
|
|
<A HREF="mailto:hdfhelp@ncsa.uiuc.edu">
|
|
hdfhelp@ncsa.uiuc.edu</A>
|
|
<BR> <H6>Last Modified: August 27, 1999</H6><BR>
|
|
<!-- modified by Barbara Jones - bljones@ncsa.uiuc.edu -->
|
|
</FONT>
|
|
<BR>
|
|
<!-- <A HREF="mailto:hdfhelp@ncsa.uiuc.edu"> -->
|
|
|
|
</BODY>
|
|
</HTML>
|
|
|
|
|
|
|