diff options
Diffstat (limited to 'doc/html/Tutor/reftoobj.html')
| -rw-r--r-- | doc/html/Tutor/reftoobj.html | 318 |
1 files changed, 0 insertions, 318 deletions
diff --git a/doc/html/Tutor/reftoobj.html b/doc/html/Tutor/reftoobj.html deleted file mode 100644 index ad996d1..0000000 --- a/doc/html/Tutor/reftoobj.html +++ /dev/null @@ -1,318 +0,0 @@ -<HTML><HEAD> -<TITLE>HDF5 Tutorial - References to Objects -</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 Objects</FONT> -</BIG></BIG></BIG></H1> - -<hr noshade size=1> - -<BODY> -<H2>Contents:</H2> -<UL> - <LI><A HREF="#def">References to Objects</A> - <LI> <A HREF="#def1">Creating and Storing References to Objects</A> - <LI> <A HREF="#def2">Reading References and Accessing Objects Using - References</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 Objects</H2> -In HDF5, objects (i.e. groups, datasets, and named datatypes) are usually -accessed by name. This access method was discussed in previous sections. -There is another way to access stored objects - by reference. -<P> -An object reference is based on the relative file address of the object header -in the file and is constant for the life of the object. Once a reference to -an object is created and stored in a dataset in the file, it can be used -to dereference the object it points to. References are handy for creating -a file index or for grouping related objects by storing references to them in -one dataset. -<P> -<A NAME="def1"> -<H2>Creating and Storing References to Objects</H2> -The following steps are involved in creating and storing file references -to objects: -<OL> -<LI> Create the objects or open them if they already exist in the file. -<P> -<LI> Create a dataset to store references to the objects. -<P> -<LI> Create and store references to the objects in a buffer. -<P> -<LI> Write the buffer containing the references to the dataset. -</OL> - -<A NAME="def2"> -<H2>Reading References and Accessing Objects Using References</H2> - -The following steps are involved in reading references to objects and -accessing objects using references: -<OL> -<LI> Open the dataset with the references and read them. The -<CODE>H5T_STD_REF_OBJ</CODE> - datatype must be used to describe the memory datatype. -<P> -<LI> Use the read reference to obtain the identifier of the object the - reference points to. -<P> -<LI> Open the dereferenced object and perform the desired operations. -<P> -<LI> Close all objects when the task is complete. -</OL> - -<H2> Programming Example</H2> -<A NAME="desc"> -<H3><U>Description</U></H3> -The example below first creates a group in the file. -It then creates two datasets and a named datatype in that group. -References to these four objects are stored in a dataset in the root group. -<P> -After that, it opens and reads the reference dataset from the file created -previously, then dereferences the references. - -<UL> -[<A HREF="examples/h5_ref2obj.c">C example</A> ] - - <code>h5_ref2obj.c</code><BR> -[<A HREF="examples/refobjexample.f90">FORTRAN example</A> ] - - <code>refobjexample.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: -<PRE> - Data has been successfully written to the dataset - Stored datatype is of a FLOAT class -</PRE> - - -<A NAME="rem"> -<H3><U>Remarks</U></H3> - -<UL> -<LI> The following code creates a dataset in which to store the references. -<P> -<I><B>C:</B></I> <pre> - dset2_id = H5Dcreate (file_id, dsetname, H5T_STD_REF_OBJ, - space_id, H5P_DEFAULT); -</pre> -<P> -<I><B>FORTRAN:</B></I><pre> - CALL h5dcreate_f (file_id, dsetname, H5T_STD_REF_OBJ, & - space_id, dset2_id, hdferr) -</pre> -<P> - Notice that the <CODE>H5T_SDT_REF_OBJ</CODE> - datatype is used to specify that references to objects will be - stored. The datatype <CODE>H5T_STD_REF_DSETREG</CODE> is - used to store the dataset - region references and will be discussed later in this tutorial. -<P> -<LI>The next few calls to <CODE>H5Rcreate</CODE> / <CODE>h5rcreate_f</CODE> - create references to the objects. The signature of - <CODE>H5Rcreate</CODE> / <CODE>h5rcreate_f</CODE> 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> <pre> - h5rcreate_f (loc_id, name, ref, hdferr) - - loc_id IN: INTEGER (HID_T) - name IN: CHARACTER(LEN=*) - ref OUT: TYPE (hobj_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 name of - the referenced object. -<P> - <LI> In C, the <I>ref_type</I> argument specifies the type of the - reference. - Our example uses references to objects, <CODE>H5R_OBJECT</CODE>. - References to dataset regions, <CODE>H5R_DATASET_REGION</CODE>, - will be discussed later in this tutorial. -<P> - <LI> In C, the <I>space_id</I> argument specifies the dataspace - identifier. When references - to the objects are created, this argument should be set to -1. -<P> - <LI> In FORTRAN, the return value from the <CODE>h5rcreate_f</CODE> - call is in <I>hdferr</I>: 0 if successful, -1 otherwise. - In C, <CODE>H5Rcreate</CODE> returns a non-negative value if - successful and a negative value otherwise. -</UL> -<P> -<LI><CODE>H5Dwrite</CODE> / <CODE>h5dwrite_f</CODE> writes a - dataset containing the references. - Notice that the <CODE>H5T_SDT_REF_OBJ</CODE> datatype is used to - describe the dataset's memory datatype. -<P> -</UL> -<UL> -<LI> <CODE>H5Dread</CODE> / <CODE>h5dread_f</CODE> - reads the dataset containing the - references to the objects. The <CODE>H5T_STD_REF_OBJ</CODE> memory - datatype was - used to read references to memory. -<P> -<LI> <CODE>H5Rdereference</CODE> / <CODE>h5rdereference_f</CODE> obtains - the object's identifier. The signature is as follows: -<P> -<I><B>C</B></I>: <pre> - hid_t H5Rdereference (hid_t dset_id, H5R_type_t ref_type, - void *ref) -</pre> -<P> -<I><B>FORTRAN</B></I>: <pre> - h5rdereference_f (dset_id, ref, obj_id, hdferr) - - dset_id IN: INTEGER (HID_T) - ref IN: TYPE (hobj_ref_t_f) - obj_id OUT: INTEGER (HID_T) - hdferr OUT: INTEGER -</pre> -<P> - <UL> - <LI> The <I>dset_id</I> argument is the identifier of the dataset - containing the references. -<P> - <LI> In C, the <I>ref_type</I> argument specifies the reference type. -<P> - <LI> The <I>ref</I> argument is a buffer containing the reference - to be dereferenced. -<P> - <LI> The C function returns the identifier of the object that the - reference points to or a negative value if it is unsuccessful. - In FORTRAN, the object identifier is returned in <I>obj_id</I> - and the return code is returned in <I>hdferr</I>. -<P> - In our simplified situation, we know what type of object was - stored in the dataset. When the type of the object is unknown, - <CODE>H5Rget_object_type</CODE> should be used to identify the type - of object the reference points to. - </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> <I><code>REF_OBJ.h5</code> in DDL</I> - -<PRE> -HDF5 "REF_OBJ.h5" { -GROUP "/" { - GROUP "GROUP1" { - GROUP "GROUP2" { - } - } - DATASET "INTEGERS" { - DATATYPE { H5T_STD_I32BE } - DATASPACE { SIMPLE ( 5 ) / ( 5 ) } - DATA { - 1, 2, 3, 4, 5 - } - } - DATATYPE "MYTYPE" { - } - DATASET "OBJECT_REFERENCES" { - DATATYPE { H5T_REFERENCE } - DATASPACE { SIMPLE ( 4 ) / ( 4 ) } - DATA { - GROUP 0:1320, GROUP 0:2272, DATASET 0:2648, DATATYPE 0:3244 - } - } -} -} - - -</PRE> -<I><U>HDF5 File Created by FORTRAN Example</U></I>: -<p> -<B>Fig. B</B> <I><code>FORTRAN.h5</code> in DDL</I> - -<PRE> -HDF5 "FORTRAN.h5" { -GROUP "/" { - GROUP "GROUP1" { - GROUP "GROUP2" { - } - } - DATASET "INTEGERS" { - DATATYPE { H5T_STD_I32BE } - DATASPACE { SIMPLE ( 5 ) / ( 5 ) } - DATA { - 1, 2, 3, 4, 5 - } - } - DATATYPE "MyType" { - } - DATASET "OBJECT_REFERENCES" { - DATATYPE { H5T_REFERENCE } - DATASPACE { SIMPLE ( 4 ) / ( 4 ) } - DATA { - GROUP 0:1344, GROUP 0:2320, DATASET 0:2696, DATATYPE 0:3292 - } - } -} -} -</PRE> -<P> - -Notice how the data in the reference dataset is described. The two numbers -separated by a colon represent a unique identifier of the object. These -numbers are constant for the life of the object. - -<!-- 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> - - - |