summaryrefslogtreecommitdiffstats
path: root/doc/html/Tutor/reftoreg.html
diff options
context:
space:
mode:
Diffstat (limited to 'doc/html/Tutor/reftoreg.html')
-rw-r--r--doc/html/Tutor/reftoreg.html366
1 files changed, 0 insertions, 366 deletions
diff --git a/doc/html/Tutor/reftoreg.html b/doc/html/Tutor/reftoreg.html
deleted file mode 100644
index 3745d91..0000000
--- a/doc/html/Tutor/reftoreg.html
+++ /dev/null
@@ -1,366 +0,0 @@
-<HTML><HEAD>
-<TITLE>HDF5 Tutorial - References to Dataset Regions
-</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"> References to Dataset Regions</FONT>
-</BIG></BIG></BIG></H1>
-
-<hr noshade size=1>
-
-<BODY>
-<H2>Contents:</H2>
-<UL>
- <LI> <A HREF="#def">References to Dataset Regions</A>
- <LI> <A HREF="#def1">Creating and Storing References to Dataset Regions</A>
- <LI> <A HREF="#def2">Reading References to Dataset Regions</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="def">
-<H2>References to Dataset Regions</H2>
-Previously you learned about creating, reading, and writing
-dataset selections. Here you will learn how to store dataset
-selections in a file, and how to read them back using references
-to dataset regions.
-<P>
-A dataset region reference points to the dataset selection by storing the
-relative file address of the dataset header and the global heap offset of
-the referenced selection. The selection referenced is located by retrieving
-the coordinates of the areas in the selection from the global heap. This
-internal mechanism of storing and retrieving dataset selections is transparent
-to the user. A reference to a dataset selection (a region) is constant for
-the life of the dataset.
-<A NAME="def1">
-<H2>Creating and Storing References to Dataset Regions</H2>
-The following steps are involved in creating and storing references to
-dataset regions:
-<OL>
-
-<LI> Create a dataset in which to store the dataset regions (the selections).
-<P>
-<LI> Create selections in the dataset(s).
-The dataset(s) should already exist in the file.
-<P>
-<LI> Create references to the selections and store them in a buffer.
-<P>
-<LI> Write the dataset region references to the file.
-<P>
-<LI> Close all objects.
-</OL>
-
-<A NAME="def2">
-<H2>Reading References to Dataset Regions</H2>
-
-The following steps are involved in reading references to dataset
-regions and referenced dataset regions (selections).
-<OL>
-<LI> Open and read the dataset containing references to the dataset regions.
- The datatype <CODE>H5T_STD_REF_DSETREG</CODE> must be used during
-the read operation.
-<P>
-<LI>Use <CODE>H5Rdereference</CODE> / <CODE>h5rdeference_f</CODE> to
-obtain the dataset identifier from the read
- dataset region reference.
- <dir><dir><dir>
- <B><font size=-1>OR</font></B>
- </dir></dir></dir>
- Use <CODE>H5Rget_region</CODE> / <CODE>h5rget_region_f</CODE> to obtain
- the dataspace identifier for the dataset
- containing the selection from the read dataset region reference.
-<P>
-<LI> Obtain information about the selection or read selected data from
- the dataset.
-<P>
-<LI> Close all objects when they are no longer needed.
-</OL>
-
-<H2> Programming Example</H2>
-<A NAME="desc">
-<H3><U>Description</U></H3>
-The example below first creates a dataset in the file. Then it creates a
-dataset to store references to the dataset regions (selections).
-The first selection is a 6 x 6 hyperslab. The second selection is a point
-selection in the same dataset.
-References to both selections are created and stored in the buffer and then
-written to the dataset in the file.
-<P>
-After creating the dataset and references, the program reads the dataset
-containing the dataset region references.
-It reads data from the dereferenced dataset and displays the number of
-elements and raw data. Then it reads two selections, a hyperslab selection
-and a point selection. The program queries a number of points in the
-hyperslab and their coordinates and displays them. Then it queries a number of
-selected points and their coordinates and displays the information.<BR>
-<P>
-To obtain the example, download:
-<UL>
-[<A HREF="examples/h5_ref2reg.c">C example</A> ]
- - <code>h5_ref2reg.c</code><BR>
-[<A HREF="examples/refregexample.f90">FORTRAN example</A> ]
- - <code>refregexample.f90</code>
-</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.
-<P>
-
-Following is the output from the examples:
-<P>
-<I><U>Output of C Example</U></I>
-<PRE>
-Selected hyperslab:
-0 0 0 3 3 4 0 0 0
-0 0 0 3 4 4 0 0 0
-Selected points:
-1 0 0 0 0 0 0 0 6
-0 0 0 0 0 0 5 0 0
-</PRE>
-<I><U>Output of FORTRAN Example</U></I>
-<PRE>
- Hyperslab selection
-
- 3*0, 2*3, 4, 3*0
- 3*0, 3, 2*4, 3*0
-
- Point selection
-
- 1, 7*0, 6
- 6*0, 5, 2*0
-</PRE>
-
-<A NAME="rem">
-<H3><U>Remarks</U></H3>
-<UL>
-<LI> The following code creates a dataset to store references to the
- dataset(s) regions (selections). Notice that the
- <CODE>H5T_STD_REF_DSETREG</CODE> datatype is used.
-<P>
-<I><B>C:</I></B>
-<pre>
- dset1 = H5Dcreate (file_id, dsetnamer, H5T_STD_REF_DSETREG,
- spacer_id, creation_prp);
-</pre>
-<P>
-<I><B>FORTRAN:</B></I>
-<pre>
- CALL h5dcreate_f (file_id, dsetnamer, H5T_STD_REF_DSETREG, &
- spacer_id, dset1, hdferr, creation_prp)
-</pre>
-<P>
-
-<LI> This program uses hyperslab and point selections. We used the dataspace
- identifier for the calls to <CODE>H5Sselect_hyperslab</CODE> /
- <CODE>h5sselect_hyperslab_f</CODE> and
- <CODE>H5Sselect_elements</CODE> / <CODE>h5sselect_elements_f</CODE>.
- The identifier was obtained when the dataset was
- created and it describes the dataset's dataspace. We did not close it when
- the dataset was closed to decrease the number of function calls used
- in the example.
- In a real application program, one should open the dataset and determine
- its dataspace using the <CODE>H5Dget_space</CODE> /
- <CODE>h5dget_space_f</CODE> function.
-<P>
-<LI> <CODE>H5Rcreate</CODE> / <CODE>h5rcreate_f</CODE> is used to create a
-dataset region reference. The signature of the function is as follows:
-<P>
-<I><B>C</B></I>:
-<pre>
- herr_t H5Rcreate (void *ref, hid_t loc_id, const char *name,
- H5R_type_t ref_type, hid_t space_id)
-</pre>
-<P>
-<I><B>FORTRAN</B></I>: &nbsp;
-<pre>
- h5rcreate_f (loc_id, name, space_id, ref, hdferr)
-
- loc_id IN: INTEGER (HID_T)
- name IN: CHARACTER (LEN=*)
- space_id IN: INTEGER (HID_T)
- ref_type OUT: TYPE(hdset_reg_ref_t_f)
- hdferr OUT: INTEGER
-</pre>
-<P>
-<UL>
- <LI> The <em>ref</em> argument specifies the buffer in which
- to store the reference.
-<P>
- <LI> The <I>loc_id</I> and <I>name</I> arguments specify the
- referenced dataset.
-<P>
- <LI> In C, the <I>ref_type</I> argument specifies the reference type.
- Since we are creating references to the dataset regions,
- the <CODE>H5R_DATASET_REGION</CODE> datatype is used.
-<P>
- <LI> The <I>space_id</I> argument is a dataspace identifier.
- This dataspace includes a selection in the referenced dataset.
-<P>
- <LI> In C, the function <CODE>H5Rcreate</CODE> returns a non-negative
- value if successful and a negative value otherwise. In FORTRAN, the
- return code from the <CODE>h5rcreate_f</CODE> subroutine is
- returned in <I>hdferr</I>: 0 if succesful and -1 otherwise.
-</UL>
-<P>
-<LI> The dataset with the region references was read by
- <CODE>H5Dread</CODE> / <CODE>h5dread_f</CODE> with
- the <CODE>H5T_STD_REF_DSETREG</CODE> datatype specified.
-<P>
-<LI> The read reference can be used to obtain the dataset identifier, as we
- did with the following call:
-<P>
-<I><B>C:</B></I>
-<pre>
- dset2 = H5Rdereference (dset1, H5R_DATASET_REGION, &ref_out[0]);
-</pre>
-<P>
-<I><B>FORTRAN:</B></I>
-<pre>
- CALL h5rdereference_f (dset1, ref_out(1), dset2, hdferr)
-</pre>
-<P>
- or to obtain spacial information ( dataspace and selection ) with the call
- to <CODE>H5Rget_region</CODE> / <CODE>h5rget_region_f</CODE>:
-<P>
-<I><B>C:</B></I>
-<pre>
- dspace2 = H5Rget_region (dset1, H5R_DATASET_REGION, &ref_out[0]);
-</pre>
-<P>
-<I><B>FORTRAN:</B></I>
-<pre>
- CALL H5rget_region_f (dset1, ref_out(1), dspace2, hdferr)
-</pre>
-<P>
- The reference to the dataset region has information for both the dataset
- itself and its selection. In both calls,
-<UL>
- <LI> the <em>dset1</em> parameter is the identifier for the dataset
- with the region references and
-<P>
- <LI> the <em>ref_out</em> parameter specifies the type of reference
- stored. In this example a reference to the dataset region is stored.
-</UL>
-<P>
- The C function returns the dataspace identifier or a
- negative value if it is not successful.
- In FORTRAN, the dataset identifier or dataspace identifier
- is returned in <I>dset2</I> or <I>dspace2</I>
- and the return code for the call is returned in <I>hdferr</I>:
- 0 if successful and -1 otherwise.
-<P>
-</UL>
-
-
-</UL>
-<A NAME="fc">
-<H3><U>File Contents</U></H3>
-<P>
-<I><U>HDF5 File Created by C Example</U></I>
-<P>
-<B>Fig. A</B> &nbsp; <I><code>REF_REG.h5</code> in DDL</I>
-<PRE>
-
-HDF5 "REF_REG.h5" {
-GROUP "/" {
- DATASET "MATRIX" {
- DATATYPE { H5T_STD_I32BE }
- DATASPACE { SIMPLE ( 2, 9 ) / ( 2, 9 ) }
- DATA {
- 1, 1, 2, 3, 3, 4, 5, 5, 6,
- 1, 2, 2, 3, 4, 4, 5, 6, 6
- }
- }
- DATASET "REGION_REFERENCES" {
- DATATYPE { H5T_REFERENCE }
- DATASPACE { SIMPLE ( 2 ) / ( 2 ) }
- DATA {
- DATASET 0:744 {(0,3)-(1,5)}, DATASET 0:744 {(0,0), (1,6), (0,8)}
- }
- }
-}
-}
-
-</PRE>
-<I><U>HDF5 File Created by FORTRAN Example</U></I>:
-<P>
-<B>Fig. B</B> &nbsp; <I><code>FORTRAN.h5</code> in DDL</I>
-<PRE>
-
-HDF5 "FORTRAN.h5" {
-GROUP "/" {
- DATASET "MATRIX" {
- DATATYPE { H5T_STD_I32BE }
- DATASPACE { SIMPLE ( 9, 2 ) / ( 9, 2 ) }
- DATA {
- 1, 1,
- 1, 2,
- 2, 2,
- 3, 3,
- 3, 4,
- 4, 4,
- 5, 5,
- 5, 6,
- 6, 6
- }
- }
- DATASET "REGION_REFERENCES" {
- DATATYPE { H5T_REFERENCE }
- DATASPACE { SIMPLE ( 2 ) / ( 2 ) }
- DATA {
- DATASET 0:744 {(3,0)-(5,1)}, DATASET 0:744 {(0,0), (6,1), (8,0)}
- }
- }
-}
-}
-</PRE>
-
-Notice how the raw data in the dataset with the dataset regions is displayed.
-Each element of the raw data consists of a reference to the dataset
-(DATASET number1:number2) and its selected region.
-If the selection is a hyperslab, the corner coordinates of the hyperslab
-are displayed.
-For the point selection, the coordinates of each point are displayed.
-<!--
-Since only two selections were stored, the third and fourth elements of the
-dataset are set to NULL. This was done by the buffer
-inizialization in the program.
--->
-
-
-<!-- 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>
-
-
-
generated by cgit v0.12 at 2024-07-21 10:00:28 (GMT)