1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
|
<HTML><HEAD>
<TITLE>HDF5 Tutorial - References to Objects
</TITLE>
</HEAD>
<body bgcolor="#ffffff">
<!-- BEGIN MAIN BODY -->
<A HREF="http://www.ncsa.uiuc.edu/"><img border=0
src="http://www.ncsa.uiuc.edu/Images/NCSAhome/footerlogo.gif"
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"> 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="http://www.ncsa.uiuc.edu/Images/NCSAhome/footerlogo.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: March 16, 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>
|
