diff options
Diffstat (limited to 'doc/html/Tutor/rdwt.html')
| -rw-r--r-- | doc/html/Tutor/rdwt.html | 384 |
1 files changed, 268 insertions, 116 deletions
diff --git a/doc/html/Tutor/rdwt.html b/doc/html/Tutor/rdwt.html index 1eb1a84..74c1122 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 <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); +<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> <I>'dset.h5' in DDL</I> + <B>Fig. 6.1a</B> <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> <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,9 @@ 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> <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"> --> |