summaryrefslogtreecommitdiffstats
path: root/doc/html/Tutor/rdwt.html
diff options
context:
space:
mode:
authorFrank Baker <fbaker@hdfgroup.org>2000-12-22 20:47:59 (GMT)
committerFrank Baker <fbaker@hdfgroup.org>2000-12-22 20:47:59 (GMT)
commitc1d537db2b803d6908fe3f21f62c592c9cd2bf70 (patch)
tree56a6cb7f00a6fbec3b071722df9705e744368073 /doc/html/Tutor/rdwt.html
parentd4c3773742b8dee426e7325fee4e8fc4015f2802 (diff)
downloadhdf5-c1d537db2b803d6908fe3f21f62c592c9cd2bf70.zip
hdf5-c1d537db2b803d6908fe3f21f62c592c9cd2bf70.tar.gz
hdf5-c1d537db2b803d6908fe3f21f62c592c9cd2bf70.tar.bz2
[svn-r3196]
Purpose: Adding Tutorial to development branch (R 1.4) Platforms tested: IE 5
Diffstat (limited to 'doc/html/Tutor/rdwt.html')
-rw-r--r--doc/html/Tutor/rdwt.html259
1 files changed, 259 insertions, 0 deletions
diff --git a/doc/html/Tutor/rdwt.html b/doc/html/Tutor/rdwt.html
new file mode 100644
index 0000000..1eb1a84
--- /dev/null
+++ b/doc/html/Tutor/rdwt.html
@@ -0,0 +1,259 @@
+<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 &lt;hdf5.h&gt;
+#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 &lt; 4; i++)
+ for (j = 0; j &lt; 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> &nbsp; <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>
+
+
+