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
|
<HTML><HEAD>
<TITLE>HDF5 Tutorial - Chunking and Extendible Datasets
</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">Chunking and Extendible Datasets</FONT>
</BIG></BIG></BIG></H1>
<hr noshade size=1>
<BODY>
<H2>Contents:</H2>
<UL>
<LI><A HREF="#def">Creating an Extendible 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>
<LI> <A HREF="#ddl">Dataset Definition in DDL</A>
-->
</UL>
</UL>
<HR>
<A NAME="def">
<H2>Creating an Extendible Dataset</H2>
An extendible dataset is one whose dimensions can grow.
HDF5 allows you to define a dataset to have certain initial dimensions,
then to later increase the size of any of the initial dimensions.
<P>
HDF5 requires you to use chunking to define extendible datasets.
This makes it possible to extend datasets efficiently without
having to excessively reorganize storage.
<P>
The following operations are required in order to write an extendible dataset:
<OL>
<LI>Declare the dataspace of the dataset to have unlimited dimensions for all dimensions that might eventually be extended.
<LI>Set dataset creation properties to enable chunking.
<LI>Create the dataset.
<LI>Extend the size of the dataset.
</OL>
<H2> Programming Example</H2>
<A NAME="desc">
<H3><U>Description</U></H3>
This example shows how to create a 3 x 3 extendible dataset, write to that
dataset, extend the dataset to 10x3, and write to the dataset again.
<UL>
[<A HREF="examples/h5_extend.c">C example</A> ]
- <code>h5_extend.c</code><BR>
[<A HREF="examples/chunk.f90">FORTRAN example</A> ]
- <code>chunk.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.
<A NAME="rem">
<H3><U>Remarks</U></H3>
<P>
<UL>
<LI>The routine <CODE>H5Pcreate</CODE> / <CODE>h5pcreate_f</CODE>
creates a new property as an instance of
a property list. The signature is as follows:
<P>
<I><B>C:</B></I>
<pre>
hid_t H5Pcreate (H5P_class_t classtype)
</pre>
<P>
<I><B>FORTRAN:</B></I>
<pre>
h5pcreate_f (classtype, prp_id, hdferr)
classtype IN: INTEGER
prp_id OUT: INTEGER(HID_T)
hdferr OUT: INTEGER
</pre>
<P>
<UL>
<LI>The parameter <I>classtype</I> is the type of property list to create.
Valid class types are as follows:
<center>
<table border=1>
<tr align=center>
<td><b>C</b></td>
<td><b>FORTRAN</b></td>
</tr><tr align=left>
<td><code> <BR>
H5P_FILE_CREATE <BR>
H5P_FILE_ACCESS <BR>
H5P_DATASET_CREATE<BR>
H5P_DATASET_XFER <BR>
H5P_MOUNT <BR><BR>
</code></td>
<td><code> <BR>
H5P_FILE_CREATE_F <BR>
H5P_FILE_ACCESS_F <BR>
H5P_DATASET_CREATE_F<BR>
H5P_DATASET_XFER_F <BR>
H5P_MOUNT_F <BR><BR>
</code></td>
</tr>
</table>
</center>
<LI>In C, the property list identifier is returned if successful;
otherwise a negative value is returned, if not.
In FORTRAN, the property list identifier is returned in <I>prp_id</I>
and the return value for the call is returned in <I>hdferr</I>.
</UL>
<P>
<LI>The routine <CODE>H5Pset_chunk</CODE> / <CODE>h5pset_chunk_f</CODE>
sets the size of the chunks used
to store a chunked layout dataset.
The signature of this routine is as follows:
<P>
<I><B>C:</B></I>
<pre>
herr_t H5Pset_chunk (hid_t prp_id, int ndims,
const hsize_t * dims)
</pre>
<P>
<I><B>FORTRAN:</B></I>
<pre>
h5pset_chunk_f (prp_id, ndims, dims, hdferr)
prp_id IN: INTEGER(HID_T)
ndims IN: INTEGER
dims IN: INTEGER(HSIZE_T), DIMENSION(ndims)
hdferr OUT: INTEGER
</pre>
<P>
<UL>
<LI>The <em>prp_id</em> parameter is the identifier for the property
list to query.
<LI>The <em>ndims</em> parameter is the number of dimensions of
each chunk.
<LI>The <em>dims</em> parameter is an array containing the size of
each chunk.
<LI>In C, a non-negative value is returned if successful; otherwise a
negative value is returned.
In FORTRAN, the return value is returned in <em>hdferr</em>: 0 if
successful and -1 otherwise.
</UL>
<P>
<LI>The <CODE>H5Dextend</CODE> / <CODE>h5dextend_f</CODE> routine
extends a dataset that has an unlimited
dimension. The signature is as follows:
<P>
<I><B>C:</B></I>
<pre>
herr_t H5Dextend (hid_t dset_id, const hsize_t * size)
</pre>
<P>
<I><B>FORTRAN:</B></I>
<pre>
h5dextend_f (dset_id, size, hdferr)
dset_id IN: INTEGER(HID_T)
size IN: INTEGER(HSIZE_T), DIMENSION(*)
hdferr OUT: INTEGER<BR>
</pre>
<P>
<UL>
<LI>The <em>dset_id</em> parameter is the dataset identifier.
<LI>The <em>size</em> parameter, is an array containing the
new magnitude of each dimension.
<LI>In C, this function returns a non-negative value if successful and
a negative value otherwise.
In FORTRAN, the return value is returned in <em>hdferr</em>:
0 if successful and -1 otherwise.
</UL>
<P>
<LI>The <CODE>H5Dget_create_plist</CODE> / <CODE>h5dget_create_plist_f</CODE>
routine returns an identifier for a
copy of the dataset creation property list for a dataset.
<P>
<LI>The C function, <CODE>H5Pget_layout</CODE>, returns the layout of the raw data for a
dataset. Valid types are <CODE>H5D_CONTIGUOUS</CODE> and
<CODE>H5D_CHUNKED</CODE>.
A FORTRAN routine for <CODE>H5Pget_layout</CODE> does not yet exist.
<P>
<LI>The <CODE>H5Pget_chunk</CODE> / <CODE>h5pget_chunk_f</CODE>
routine retrieves the size of chunks
for the raw data of a chunked layout dataset.
The signature is as follows:
<P>
<I><B>C:</B></I>
<pre>
int H5Pget_chunk (hid_t prp_id, int ndims, hsize_t * dims)
</pre>
<P>
<I><B>FORTRAN:</B></I>
<pre>
h5pget_chunk_f (prp_id, ndims, dims, hdferr)
prp_id IN: INTEGER(HID_T)
ndims IN: INTEGER
dims OUT: INTEGER(HSIZE_T), DIMENSION(ndims)
hdferr OUT: INTEGER
</pre>
<P>
<UL>
<LI>The <em>prp_id</em> parameter is the identifier of the
property list to query.
<LI>The <em>ndims</em> parameter is the size of the <em>dims</em>
array.
<LI>The <em>dims</em> parameter is the array in which to store the chunk
dimensions.
<LI>In C, this function returns the chunk dimensionality if successful
and a negative value otherwise.
In FORTRAN, the return value is returned in <em>hdferr</em>:
the chunked rank if successful and -1 otherwise.
</UL>
<P>
<LI>The <CODE>H5Pclose</CODE> / <CODE>h5pclose_f</CODE> routine
terminates access to a property list.
The signature is as follows:
<P>
<I><B>C:</B></I>
<pre>
herr_t H5Pclose (hid_t prp_id)
</pre>
<P>
<I><B>FORTRAN:</B></I>
<pre>
h5pclose_f (prp_id, hdferr)
prp_id IN: INTEGER(HID_T)
hdferr OUT: INTEGER
</pre>
<P>
<ul>
<li>The <em>prp_id</em> parameter is the identifier of the property list
to terminate access to.
</ul>
</UL>
<!--
<A NAME="fc">
<H3><U>File Contents</U></H3>
-->
<!-- 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>
|
