mirror of
https://github.com/HDFGroup/hdf5.git
synced 2024-11-27 02:10:55 +08:00
410 lines
13 KiB
HTML
410 lines
13 KiB
HTML
<HTML><HEAD>
|
|
<TITLE>HDF5 Tutorial - Reading from and Writing to a Dataset
|
|
</TITLE>
|
|
</HEAD>
|
|
|
|
<body bgcolor="#ffffff">
|
|
|
|
<!-- BEGIN MAIN BODY -->
|
|
|
|
|
|
[ <A HREF="title.html"><I>HDF5 Tutorial Top</I></A> ]
|
|
<H1>
|
|
<BIG><BIG><BIG><FONT COLOR="#c101cd">Reading from and Writing to a Dataset</FONT>
|
|
</BIG></BIG></BIG></H1>
|
|
|
|
<hr noshade size=1>
|
|
|
|
<BODY>
|
|
<H2>Contents:</H2>
|
|
<UL>
|
|
<LI><A HREF="#rdwr">Reading from and Writing to 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 from and Writing to a Dataset</h2>
|
|
<P>
|
|
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:
|
|
<UL>
|
|
<LI> The dataset
|
|
|
|
<LI> The dataset's datatype in memory
|
|
|
|
<LI> The dataset's dataspace in memory
|
|
|
|
<LI> The dataset's dataspace in the file
|
|
|
|
<LI>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.)
|
|
|
|
<LI> The data buffer
|
|
</UL>
|
|
|
|
|
|
<P>
|
|
The steps to read from or write to a dataset are
|
|
as follows:
|
|
<OL>
|
|
<LI> Obtain the dataset identifier.
|
|
<LI> Specify the memory datatype.
|
|
<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, datatype, and property list if necessary.
|
|
</OL>
|
|
|
|
To read from or write to a dataset,
|
|
the <code>H5Dread</code>/<code>h5dread_f</code> and
|
|
<code>H5Dwrite</code>/<code>h5dwrite_f</code>
|
|
routines are used. <P>
|
|
<I>C</I>:
|
|
<PRE>
|
|
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);
|
|
|
|
</PRE>
|
|
<I>FORTRAN</I>:
|
|
<PRE>
|
|
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)
|
|
<font face=times><i>or</i></font>
|
|
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)
|
|
<font face=times><i>or</i></font>
|
|
CALL h5dwrite_f(dset_id, mem_type_id, buf, error)
|
|
</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 for the dataset <code>/dset</code>,
|
|
writes the dataset to the file, then reads the dataset back from
|
|
memory. It then closes the dataset and file. <BR>
|
|
<UL>
|
|
[ <A HREF="examples/h5_rdwt.c">C Example</A> ] - <code>h5_rdwt.c</code> <BR>
|
|
[ <A HREF="examples/rwdsetexample.f90">FORTRAN Example</A> ] - <code>rwdsetexample.f90</code><BR>
|
|
[ <A HREF="examples/java/DatasetRdWt.java">Java Example</A> ] - <code>DatasetRdWt.java</code> <BR>
|
|
</UL>
|
|
|
|
<B>NOTE:</B> To download a tar file of the examples, including a Makefile,
|
|
please go to the <A HREF="references.html">References</A> page.
|
|
|
|
</PRE>
|
|
<A NAME="rem">
|
|
<H3><U>Remarks</U></H3>
|
|
<UL>
|
|
<LI><code>H5Fopen</code>/<code>h5fopen_f</code> opens an existing file and
|
|
returns a file identifier.
|
|
<PRE>
|
|
<I>C</I>:
|
|
hid_t H5Fopen (const char *name, unsigned access_mode, hid_t access_prp)
|
|
|
|
<I>FORTRAN</I>:
|
|
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
|
|
|
|
</PRE>
|
|
<UL>
|
|
<LI> The argument <I>name</I> is the filename.
|
|
<P>
|
|
<LI> The <I>access_mode</I> parameter is the file access mode.
|
|
<code>H5F_ACC_RDWR</code> in C
|
|
(<code>H5F_ACC_RDWR_F</code> in FORTRAN)
|
|
allows read/write access
|
|
while <code>H5F_ACC_RDONLY</code> in C
|
|
(<code>H5F_ACC_RDONLY_F</code> in FORTRAN)
|
|
allows read-only access.
|
|
|
|
<P>
|
|
<LI> The <I>access_prp</I> parameter identifies the file access property list.
|
|
<code>H5P_DEFAULT</code> in C and <code>H5P_DEFAULT_F</code> 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.
|
|
|
|
<P>
|
|
<LI>In FORTRAN, the return code is passed back in the <I>hdferr</I>
|
|
parameter: 0 if successful, -1 if not. In C, the function returns
|
|
the file identifier if successful, and a negative value otherwise.
|
|
</UL>
|
|
<P>
|
|
<LI> <code>H5Dopen</code>/<code>h5dopen_f</code> opens an existing dataset
|
|
with the name specified by <i>name</i> at the location specified by
|
|
<i>loc_id</i>.
|
|
For FORTRAN, the return value is passed in the <I>hdferr</I> parameter:
|
|
0 if successful, -1 if not. For C, the function returns the dataset
|
|
identifier if successful, and a negative value if not.
|
|
<P>
|
|
<I>C</I>:
|
|
<PRE>
|
|
hid_t H5Dopen (hid_t loc_id, const char *name)
|
|
</PRE>
|
|
<I>FORTRAN</I>:
|
|
<PRE>
|
|
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)
|
|
</PRE>
|
|
|
|
<P>
|
|
<LI><code>H5Dwrite</code>/<code>h5dwrite_f</code> 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.
|
|
<P>
|
|
<I>C</I>:
|
|
<PRE>
|
|
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)
|
|
</PRE>
|
|
<I>FORTRAN</I>:
|
|
<PRE>
|
|
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)
|
|
</PRE>
|
|
<UL>
|
|
<LI> The <I>dset_id</I> is the dataset identifier.
|
|
<P>
|
|
|
|
<LI> The <I>mem_type_id</I> parameter is the identifier of the dataset's
|
|
memory datatype. <code>H5T_NATIVE_INT</code> in C
|
|
(<code>H5T_NATIVE_INTEGER</code> in FORTRAN) is an integer datatype
|
|
for the machine on which the library was compiled.
|
|
<P>
|
|
|
|
<LI> The <I>mem_space_id</I> parameter is the identifier of the dataset's
|
|
memory dataspace. <code>H5S_ALL</code> in C (<code>H5S_ALL_F</code>
|
|
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.
|
|
<P>
|
|
|
|
<LI> The <I>file_space_id</I> parameter is the identifier of the
|
|
dataset's file dataspace.
|
|
<code>H5S_ALL</code> in C (<code>H5S_ALL_F</code> 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.
|
|
<P>
|
|
|
|
<LI> The <I>xfer_prp</I> parameter is the data transfer propery list
|
|
identifier.
|
|
<code>H5P_DEFAULT</code> in C
|
|
(<code>H5P_DEFAULT_F</code> 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.
|
|
<P>
|
|
|
|
<LI> The <I>buf</I> parameter is the data buffer to write.
|
|
<P>
|
|
|
|
<LI> In FORTRAN, the <I>hdferr</I> 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.
|
|
</UL>
|
|
<P>
|
|
<LI><code>H5Dread</code>/<code>h5dread_f</code> reads raw data from the
|
|
specified dataset to an application buffer,
|
|
converting from the file datatype and dataspace to the memory datatype and
|
|
dataspace.
|
|
<P>
|
|
<I>C</I>:
|
|
<PRE>
|
|
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)
|
|
</PRE>
|
|
<I>FORTRAN</I>:
|
|
<PRE>
|
|
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)
|
|
|
|
</PRE>
|
|
|
|
<p>
|
|
<UL>
|
|
<LI>The <I>dset_id</I> parameter is the dataset identifier.
|
|
<P>
|
|
|
|
<LI>The <I>mem_type_id</I> parameter is the identifier of the dataset's
|
|
memory datatype. <code>H5T_NATIVE_INT</code> in C
|
|
(<code>H5T_NATIVE_INTEGER</code> in FORTRAN) is an integer datatype
|
|
for the machine on which the library was compiled.
|
|
<P>
|
|
|
|
<LI>The <I>mem_space_id</I> parameter is the identifier of the dataset's
|
|
memory dataspace. <code>H5S_ALL</code> in C (<code>H5S_ALL_F</code>
|
|
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.
|
|
<P>
|
|
|
|
<LI>The <I>file_space_id</I> parameter is the identifier of the
|
|
dataset's file dataspace.
|
|
<code>H5S_ALL</code> in C (<code>H5S_ALL_F</code> 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.
|
|
|
|
<P>
|
|
<LI>The <I>xfer_prp</I> parameter is the data transfer propery list
|
|
identifier.
|
|
<code>H5P_DEFAULT</code> in C
|
|
(<code>H5P_DEFAULT_F</code> 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.
|
|
<P>
|
|
|
|
<LI> The <I>buf</I> parameter is the data buffer to read into.
|
|
<P>
|
|
|
|
<LI> In FORTRAN, the <I>hdferr</I> 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.
|
|
</UL>
|
|
</UL>
|
|
<A NAME="fc">
|
|
<H3><U>File Contents</U></H3>
|
|
Figure 6.1a shows the contents of <code>dset.h5</code> (created by the C program).
|
|
<BR>
|
|
Figure 6.1b shows the contents of <code>dsetf.h5</code> (created by the FORTRAN
|
|
program).
|
|
<P>
|
|
<B>Fig. 6.1a</B> <I><code>dset.h5</code> 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>
|
|
<P>
|
|
<B>Fig. 6.1b</B> <I><code>dsetf.h5</code> in DDL</I>
|
|
<PRE>
|
|
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
|
|
}
|
|
}
|
|
}
|
|
}
|
|
</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="footer-ncsalogo.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>
|
|
<BR> <H6>Last Modified: June 22, 2001</H6><BR>
|
|
<!-- modified by Barbara Jones - bljones@ncsa.uiuc.edu -->
|
|
<!-- modified by Frank Baker - fbaker@ncsa.uiuc.edu -->
|
|
</FONT>
|
|
<BR>
|
|
<!-- <A HREF="mailto:hdfhelp@ncsa.uiuc.edu"> -->
|
|
|
|
</BODY>
|
|
</HTML>
|
|
|
|
|
|
|