philipp/hdf5
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

[svn-r3659]

Browse Source 
Added html files with references to the fortran 90 files.
(under examples/)
This commit is contained in:
Barbara Jones
2001-03-19 09:26:47 -05:00
parent 380eb42bc5
commit f11cef2c56
30 changed files with 2967 additions and 3139 deletions
Download Patch File Download Diff File Expand all files Collapse all files

365
doc/html/Tutor/rdwt.html
View File

@@ -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> ]
<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>
<PRE>
<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.
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
#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.
<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)
<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 first argument is the file name.
<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.
<LI> The second argument is the file access mode. H5F_ACC_RDWR allows a file
to be read from and written to.
<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.
<LI> The third parameter is the identifier for the file access property list.
H5P_DEFAULT specifies the default file access property list.
<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>
<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.
<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)
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 first parameter is the identifier of the dataset.
<LI> The <I>dset_id</I> is the dataset identifier.
<P>
<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 <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 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 <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 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 <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 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 <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 last parameter is the data buffer.
<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>
<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 first parameter is the identifier of the dataset read from.
<LI>The <I>dset_id</I> parameter is the dataset identifier.
<P>
<LI> The second parameter is the identifier of the dataset's memory datatype.
<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 third parameter is the identifier of the dataset's memory dataspace.
<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 fourth parameter is the identifier of the dataset's file dataspace.
<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.
<LI> The fifth parameter is the identifier of the data transfer propery list.
<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 last parameter is the data buffer.
<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,10 @@ 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>
<BR> <H6>Last Modified: March 16, 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"> -->