diff options
| author | Frank Baker <fbaker@hdfgroup.org> | 2000-12-22 20:47:59 (GMT) |
|---|---|---|
| committer | Frank Baker <fbaker@hdfgroup.org> | 2000-12-22 20:47:59 (GMT) |
| commit | c1d537db2b803d6908fe3f21f62c592c9cd2bf70 (patch) | |
| tree | 56a6cb7f00a6fbec3b071722df9705e744368073 /doc/html/Tutor/rdwt.html | |
| parent | d4c3773742b8dee426e7325fee4e8fc4015f2802 (diff) | |
| download | hdf5-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.html | 259 |
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 <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> + + + |