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
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
|
<html>
<head><title>
HDF5/H5RA Draft API Specification
</title></head>
<body>
<hr>
<center>
<a href="RM_H5Front.html">HDF5 Reference Manual</a>
<a href="RM_H5.html">H5</a>
<a href="RM_H5A.html">H5A</a>
<a href="RM_H5D.html">H5D</a>
<a href="RM_H5E.html">H5E</a>
<a href="RM_H5F.html">H5F</a>
<a href="RM_H5G.html">H5G</a>
<a href="RM_H5I.html">H5I</a>
<a href="RM_H5P.html">H5P</a>
<a href="RM_H5R.html">H5R</a>
H5RA
<a href="RM_H5S.html">H5S</a>
<a href="RM_H5T.html">H5T</a>
<a href="RM_H5Z.html">H5Z</a>
<a href="Tools.html">Tools</a>
<!--
<a href="Glossary.html">Glossary</a>
-->
</center>
<hr>
<center>
<h1>H5RA: Ragged Array Interface</h1>
</center>
<h2>Ragged Array API Functions</h2>
<table border=1>
<tr><th align=left>
<font color=red>
The H5RA Interface is strictly experimental at this time;
the interface may change dramatically or support for ragged arrays
may be unavailable in future in releases. As a result, future releases
may be unable to retrieve data stored with this interface.
<p><center>Use these functions at your own risk!<br>
Do not create any archives using this interface!</center>
</font>
</th></tr>
</table>
<p>
These functions enable the user to store and retrieve data in ragged arrays.
<table border=0>
<tr><td valign=top>
<ul>
<li><a href="#Ragged-Create">H5RAcreate</a>
</ul>
</td><td> </td><td valign=top>
<ul>
<li><a href="#Ragged-Open">H5RAopen</a>
<li><a href="#Ragged-Close">H5RAclose</a>
</ul>
</td><td> </td><td valign=top>
<ul>
<li><a href="#Ragged-Write">H5RAwrite</a>
<li><a href="#Ragged-Read">H5RAread</a>
</ul>
</td></tr>
</table>
<p>
This version of the Ragged Array interface implements a
two-dimensional array where each row of the array is a different length.
It is intended for applications where the distribution of row lengths
is such that most rows are near an average length with only a few rows
that are significantly shorter or longer. The raw data is split among
two datasets, <code>raw</code> and <code>over</code>: the <code>raw</code>
dataset is a two-dimensional chunked dataset whose width is large enough
to hold most of the rows while the <code>over</code> dataset is a heap
that stores the ends of rows that overflow the first dataset.
A third dataset, called <code>meta</code>, contains one record for each
row and describes what elements, if any, overflow the <code>raw</code>
dataset and where they are stored in the <code>over</code> dataset.
All three datasets are contained in a single group whose name is the
name of the ragged array.
<p>
<hr>
<dl>
<dt><strong>Name:</strong> <a name="Ragged-Create">H5RAcreate</a>
<dt><strong>Signature:</strong>
<dd><em>hid_t</em> <code>H5RAcreate</code>(<em>hid_t</em> <code>loc_id</code>,
<em>const char *</em><code>name</code>,
<em>hid_t</em> <code>type_id</code>,
<em>hid_t</em> <code>plist_id</code>
)
<dt><strong>Purpose:</strong>
<dd>Creates a ragged array.
<dt><strong>Description:</strong>
<dd><code>H5RAcreate</code> creates a new ragged array with the
name specified in <code>name</code>. A ragged array is
implemented as a group containing three datasets.
The dataset <code>raw</code> is a fixed width dataset
which will hold the majority of the data.
The dataset <code>over</code> is a one dimensional heap
which will hold the end of rows which are too long to fit
in <code>raw</code>
Finally, the <code>meta</code> dataset contains information
about the <code>over</code> array. All elements of the
ragged array are stored with the same data type.
<p>
The property list <code>plist_id</code> should contain
information about chunking. The chunk width will determine
the width of the <code>raw</code> dataset while the chunk
length should be such that the total chunk size is
reasonably large since I/O will be performed in units
of chunks). If the <code>plist_id</code> does not have
a chunk size defined (e.g., <code>H5P_DEFAULT</code>)
then this function will fail.
<dt><strong>Parameters:</strong>
<dl>
<dt><em>hid_t</em> <code>loc_id</code>
<dd>Location identifier of the dataset.
<dt><em>const char *</em><code>name</code>
<dd>The assigned name of the data set to be stored in the
ragged array.
<dt><em>hid_t</em> <code>type_id</code>
<dd>Data type identifier for the ragged array data.
<dt><em>hid_t</em> <code>plist_id</code>
<dd>Property list of the dataset.
</dl>
<dt><strong>Returns:</strong>
<dd>Returns a ragged array identifier if successful;
otherwise returns a negative value.
</dl>
<hr>
<dl>
<dt><strong>Name:</strong> <a name="Ragged-Open">H5RAopen</a>
<dt><strong>Signature:</strong>
<dd><em>hid_t</em> <code>H5RAopen</code>(<em>hid_t</em> <code>loc_id</code>,
<em>const char *</em><code>name</code>
)
<dt><strong>Purpose:</strong>
<dd>Opens a ragged array.
<dt><strong>Description:</strong>
<dd><code>H5RAopen</code> opens an existing ragged array.
<p>
The name of the array, <code>name</code>, should be the same
that was used when the array was created, i.e., the name of
the group which implements the array.
<dt><strong>Parameters:</strong>
<dl>
<dt><em>hid_t</em> <code>loc_id</code>
<dd>The location identifier of the dataset.
<dt><em>const char *</em><code>name</code>
<dd>The name of the ragged array.
</dl>
<dt><strong>Returns:</strong>
<dd>Returns a ragged array identifier if successful;
otherwise returns a negative value.
</dl>
<hr>
<dl>
<dt><strong>Name:</strong> <a name="Ragged-Close">H5RAclose</a>
<dt><strong>Signature:</strong>
<dd><em>herr_t</em> <code>H5RAclose</code>(<em>hid_t</em> <code>array_id</code>)
<dt><strong>Purpose:</strong>
<dd>Closes a ragged array.
<dt><strong>Description:</strong>
<dd><code>H5RAclose</code> closes the ragged array specified
with the array identifier <code>array_id</code>.
<dt><strong>Parameters:</strong>
<dl>
<dt><em>hid_t</em> <code>array_id</code>
<dd>The array identifier for the ragged array to be closed.
</dl>
<dt><strong>Returns:</strong>
<dd>Returns a non-negative value if successful;
otherwise returns a negative value.
</dl>
<hr>
<dl>
<dt><strong>Name:</strong> <a name="Ragged-Write">H5RAwrite</a>
<dt><strong>Signature:</strong>
<dd><em>herr_t</em> <code>H5RAwrite</code>(<em>hid_t</em> <code>array_id</code>,
<em>hssize_t</em> <code>start_row</code>,
<em>hsize_t</em> <code>nrows</code>,
<em>hid_t</em> <code>type_id</code>,
<em>hsize_t</em> <code>size[/*nrows*/]</code>,
<em>void *</em><code>buf[/*nrows*/]</code>
)
<dt><strong>Purpose:</strong>
<dd>Writes to a ragged array.
<dt><strong>Description:</strong>
<dd><code>H5RAwrite</code> writes a contiguous set of rows to a
ragged array beginning at row number <code>start_row</code>
and continuing for <code>nrows</code> rows.
<p>
Each row of the ragged array contains <code>size[]</code>
elements of type <code>type_id</code> and each row is stored
in a buffer pointed to by <code>buf[]</code>.
<p>
Datatype conversion takes place at the time of a read or write
and is automatic. See the
<a href="Datatypes.html#Datatypes-DataConversion">Data Conversion</a>
section of <cite>The Data Type Interface (H5T)</cite> in the
<cite>HDF5 User's Guide</cite> for a discussion of
data conversion, including the range of conversions currently
supported by the HDF5 libraries.
<dt><strong>Parameters:</strong>
<dl>
<dt><em>hid_t</em> <code>array_id</code>
<dd>Array identifier for the ragged array to be written to.
<dt><em>hssize_t</em> <code>start_row</code>
<dd>Row at which the write will start.
<dt><em>hsize_t</em> <code>nrows</code>
<dd>Number of rows to be written
<dt><em>hid_t</em> <code>type_id</code>
<dd>Data type identifier for the data to be written.
<dt><em>hsize_t</em> <code>size[/*nrows*/]</code>
<dd>Lengths of the rows to be written.
<dt><em>void *</em><code>buf[/*nrows*/]</code>
<dd>Pointers to buffers containing the data to be written.
</dl>
<dt><strong>Returns:</strong>
<dd>Returns a non-negative value if successful;
otherwise returns a negative value.
</dl>
<hr>
<dl>
<dt><strong>Name:</strong> <a name="Ragged-Read">H5RAread</a>
<dt><strong>Signature:</strong>
<dd><em>herr_t</em> <code>H5RAread</code>(<em>hid_t</em> <code>array_id</code>,
<em>hssize_t</em> <code>start_row</code>,
<em>hsize_t</em> <code>nrows</code>,
<em>hid_t</em> <code>type_id</code>,
<em>hsize_t</em> <code>size[/*nrows*/]</code>,
<em>void *</em><code>buf[/*nrows*/]</code>
)
<dt><strong>Purpose:</strong>
<dd>
<dt><strong>Description:</strong>
<dd><code>H5RAread</code> reads the contents of one or more rows
of the ragged array pointed to by <code>array_id</code>.
<p>
The rows to be read begin at row <code>start_row</code> and
continue for <code>nrows</code> rows.
<p>
All raw data is converted to type <code>type_id</code>.
<p>
The caller must allocate the <code>size[]</code> and
<code>buf[]</code> arrays.
<p>
Memory for the data can be allocated by either the caller or
the library. In the former case, the caller should initialize
the <code>buf[]</code> array with pointers to valid memory and
the <code>size[]</code> array with the lengths of the buffers.
In the latter case, the caller should initialize
<code>buf[]</code> with null pointers (the input value of
<code>size[]</code> is irrelevant in this case) and the
library will allocate memory for each row by calling
<code>malloc()</code>.
<p>
Datatype conversion takes place at the time of a read or write
and is automatic. See the
<a href="Datatypes.html#Datatypes-DataConversion">Data Conversion</a>
section of <cite>The Data Type Interface (H5T)</cite> in the
<cite>HDF5 User's Guide</cite> for a discussion of
data conversion, including the range of conversions currently
supported by the HDF5 libraries.
<dt><strong>Parameters:</strong>
<dl>
<dt><em>hid_t</em> <code>array_id</code>
<dd>Array identifier for the ragged array to be read from.
<dt><em>hssize_t</em> <code>start_row</code>
<dd>Row at which the read will start.
<dt><em>hsize_t</em> <code>nrows</code>
<dd>Number of rows to be read
<dt><em>hid_t</em> <code>type_id</code>
<dd>Data type identifier for the data to be read.
<dt><em>hsize_t</em> <code>size[/*nrows*/]</code>
<dd>Lengths of the rows to be read.
<dt><em>void *</em><code>buf[/*nrows*/]</code>
<dd>Pointers to buffers into which the data is to be read.
</dl>
<dt><strong>Returns:</strong>
<dd>Returns a non-negative value if successful.
The values of the <code>size[]</code> array will be the
true length of each row. If a row is longer than the
caller-allocated length, then <code>size[]</code> will
contain the true length of the row although not all elements
of that row will be stored in the buffer.
<p>
Returns a negative value on failure. The <code>buf[]</code>
array will contain it's original pointers (null or otherwise),
although the caller-supplied buffers may have been modified.
The <code>size[]</code> array may also have been modified.
</dl>
<hr>
<center>
<a href="RM_H5Front.html">HDF5 Reference Manual</a>
<a href="RM_H5.html">H5</a>
<a href="RM_H5A.html">H5A</a>
<a href="RM_H5D.html">H5D</a>
<a href="RM_H5E.html">H5E</a>
<a href="RM_H5F.html">H5F</a>
<a href="RM_H5G.html">H5G</a>
<a href="RM_H5I.html">H5I</a>
<a href="RM_H5P.html">H5P</a>
<a href="RM_H5R.html">H5R</a>
H5RA
<a href="RM_H5S.html">H5S</a>
<a href="RM_H5T.html">H5T</a>
<a href="RM_H5Z.html">H5Z</a>
<a href="Tools.html">Tools</a>
<!--
<a href="Glossary.html">Glossary</a>
-->
</center>
<hr>
<address>
<a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a>
<br>
Last modified: 27 October 1998
</body>
</html>
|
