319 lines
9.4 KiB
HTML
319 lines
9.4 KiB
HTML
<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>
|
|
|
|
|
|
|