diff options
Diffstat (limited to 'doc/html/Tutor/rdwt.html')
| -rw-r--r-- | doc/html/Tutor/rdwt.html | 409 |
1 files changed, 0 insertions, 409 deletions
diff --git a/doc/html/Tutor/rdwt.html b/doc/html/Tutor/rdwt.html deleted file mode 100644 index 391a0bc..0000000 --- a/doc/html/Tutor/rdwt.html +++ /dev/null @@ -1,409 +0,0 @@ -<HTML><HEAD> -<TITLE>HDF5 Tutorial - Reading from and Writing to a Dataset -</TITLE> -</HEAD> - -<body bgcolor="#ffffff"> - -<!-- BEGIN MAIN BODY --> - - - [ <A HREF="title.html"><I>HDF5 Tutorial Top</I></A> ] -<H1> -<BIG><BIG><BIG><FONT COLOR="#c101cd">Reading from and Writing to a Dataset</FONT> -</BIG></BIG></BIG></H1> - -<hr noshade size=1> - -<BODY> -<H2>Contents:</H2> -<UL> - <LI><A HREF="#rdwr">Reading from and Writing to 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 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 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 datatype in memory - - <LI> The dataset's dataspace in memory - - <LI> The dataset's dataspace in the file - - <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 from or write to a dataset are -as follows: -<OL> - <LI> Obtain the dataset identifier. - <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, datatype, and property list if necessary. -</OL> - -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> - 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> - 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> - - -<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 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> -<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> - -<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. - -</PRE> -<A NAME="rem"> -<H3><U>Remarks</U></H3> -<UL> -<LI><code>H5Fopen</code>/<code>h5fopen_f</code> opens an existing file and - returns a file identifier. -<PRE> -<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 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> <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><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 <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><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 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 <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> -<A NAME="fc"> -<H3><U>File Contents</U></H3> -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.1a</B> <I><code>dset.h5</code> 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> -<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> - - - - -<!-- 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="footer-ncsalogo.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> -<BR> <H6>Last Modified: June 22, 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"> --> - -</BODY> -</HTML> - - - |