summaryrefslogtreecommitdiffstats
path: root/doc/html/Tutor/rdwt.html
diff options
context:
space:
mode:
Diffstat (limited to 'doc/html/Tutor/rdwt.html')
-rw-r--r--doc/html/Tutor/rdwt.html386
1 files changed, 270 insertions, 116 deletions
diff --git a/doc/html/Tutor/rdwt.html b/doc/html/Tutor/rdwt.html
index 1eb1a84..445bdf2 100644
--- a/doc/html/Tutor/rdwt.html
+++ b/doc/html/Tutor/rdwt.html
@@ -1,5 +1,5 @@
<HTML><HEAD>
-<TITLE>HDF5 Tutorial - Reading to/Writing from a Dataset
+<TITLE>HDF5 Tutorial - Reading from and Writing to a Dataset
</TITLE>
</HEAD>
@@ -13,7 +13,7 @@ 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><FONT COLOR="#c101cd">Reading from and Writing to a Dataset</FONT>
</BIG></BIG></BIG></H1>
<hr noshade size=1>
@@ -21,7 +21,7 @@ width=78 height=27 alt="NCSA"><P></A>
<BODY>
<H2>Contents:</H2>
<UL>
- <LI><A HREF="#rdwr">Reading to/Writing from a Dataset</A>
+ <LI><A HREF="#rdwr">Reading from and Writing to a Dataset</A>
<LI> Programming Example
<UL>
<LI> <A HREF="#desc">Description </A>
@@ -31,54 +31,74 @@ width=78 height=27 alt="NCSA"><P></A>
</UL>
<HR>
<A NAME="rdwr">
-<H2>Reading to/Writing from a Dataset</h2>
+<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 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
+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 data type in memory
+ <LI> The dataset's datatype 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 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 to/write from a dataset are
+The steps to read from or write to a dataset are
as follows:
<OL>
<LI> Obtain the dataset identifier.
- <LI> Specify the memory data type.
+ <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/data type, and property list if necessary.
+ <LI> Close the dataspace, datatype, and property list if necessary.
</OL>
-To read to/write from a dataset, the calling program must contain the following call:
+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>
- H5Dread(dataset_id, mem_type_id, mem_space_id, file_space_id,
- xfer_plist_id, buf );
-</PRE>
- or
+ 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>
- H5Dwrite(dataset_id, mem_type_id, mem_space_id, file_space_id,
- xfer_plist_id, buf);
+ 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>
@@ -88,130 +108,241 @@ To read to/write from a dataset, the calling program must contain the following
<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
+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>
-[ <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);
+<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>
- /* Close the dataset. */
- status = H5Dclose(dataset_id);
+<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.
- /* 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.
+<LI><code>H5Fopen</code>/<code>h5fopen_f</code> 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.
+<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)
- <LI> The second argument is the file access mode. H5F_ACC_RDWR allows a file
- to be read from and written to.
+ 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
- <LI> The third parameter is the identifier for the file access property list.
- H5P_DEFAULT specifies the default file access property list.
+</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> 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.
+<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> 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.
+<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>
- 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)
+ 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 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.
+ <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> H5Dread reads raw data from the specified dataset to an application buffer,
+<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 dataset_id, hid_t mem_type_id, hid_t mem_space_id,
- hid_t file_space_id, hid_t xfer_plist_id, void * buf)
+ 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>
-<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.
+<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)
- <LI> The fifth parameter is the identifier of the data transfer propery list.
+</PRE>
- <LI> The last parameter is the data buffer.
+<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>
-</OL>
-
<A NAME="fc">
<H3><U>File Contents</U></H3>
-Figure 6.1 shows the contents of 'dset.h5'.
+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.1</B> &nbsp; <I>'dset.h5' in DDL</I>
+ <B>Fig. 6.1a</B> &nbsp; <I><code>dset.h5</code> in DDL</I>
<PRE>
HDF5 "dset.h5" {
GROUP "/" {
@@ -228,6 +359,26 @@ Figure 6.1 shows the contents of 'dset.h5'.
}
}
</PRE>
+<P>
+ <B>Fig. 6.1b</B> &nbsp; <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>
@@ -246,8 +397,11 @@ Figure 6.1 shows the contents of 'dset.h5'.
<!-- <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>
+<br>
+Describes HDF5 Release 1.2.2, June 2000
+<BR> <H6>Last Modified: April 5, 2000</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"> -->