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
|
<HTML><HEAD>
<TITLE>HDF5 Tutorial - Property Lists
</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">Property Lists</FONT>
</BIG></BIG></BIG></H1>
<hr noshade size=1>
<BODY>
<!--
<H2>Contents:</H2>
<UL>
<LI> <A HREF="#def">Definition of Property Lists</A>
</UL>
<HR>
<A NAME="def">
-->
<P>
The property list interface provides a mechanism for adding functionality
to HDF5 calls, without increasing the number of arguments used
for a given call.
<P>
A property list is a collection of values which can
be passed to various HDF5 functions to control features that
are typically unimportant or whose default values are usually used
(by specifying <code>H5P_DEFAULT</code> / <CODE>H5P_DEFAULT_F</CODE>).
<P>
It supports unusual cases when:
<UL>
<LI><A HREF="#cf">Creating Files</A>
<LI><A HREF="#fa">Accessing Files</A>
<LI><A HREF="#cd">Creating Datasets</A>
<LI><A HREF="#rdwt">Reading or Writing Data</A>
</UL>
<A NAME="cf">
<H3>Creating Files</H3>
The File Creation property list, H5P_FILE_CREATE, applies to H5Fcreate()
only and is used to control the file metadata which is maintained in the
super block of the file. The parameters that can be modified are:
user-block size, offset and length sizes, symbol table parameters,
and index storage parameters.
<P>
The following example shows how to create a file with 64-bit object
offsets and lengths:
<PRE>
hid_t create_plist;
hid_t file_id;
create_plist = H5Pcreate(H5P_FILE_CREATE);
H5Pset_sizes(create_plist, 8, 8);
file_id = H5Fcreate("test.h5", H5F_ACC_TRUNC,
create_plist, H5P_DEFAULT);
.
.
.
H5Fclose(file_id);
</PRE>
<A NAME="fa">
<H3>Accessing Files</H3>
The File Access property list, H5P_FILE_ACCESS, applies to H5Fcreate() and
H5Fopen() and is used to control different methods of
performing I/O on files. The different types of I/O are: unbuffered I/O,
buffered I/O, memory I/O, parallel files using MPI I/O, and data alignment.
<P>
Following is an example of using the H5P_FILE_ACCESS property list for creating
HDF5 files with the metadata and data split into different files:
<BR>
[ <A HREF="examples/h5split.c">C program</A> ]
- <code>h5split.c</code><BR>
<P>
<A NAME="cd">
<h3>Creating Datasets</H3>
The Dataset Creation property list, H5P_DATASET_CREATE, applies to
H5Dcreate() and controls information on how raw data
is organized on disk and how the raw data is compressed. The dataset API
partitions these terms by layout, compression, and external storage:
<P>
<UL>
<LI>Layout:
<UL>
<LI>H5D_COMPACT: Data is small and can be stored in object header (<I>not
implemented yet</I>). This eliminates disk seek/read requests.
<P>
<LI>H5D_CONTIGUOUS: (default) The data is large, non-extendible,
non-compressible, non-sparse, and can be stored externally.
<P>
<LI>H5D_CHUNKED: The data is large and can be extended in any dimension.
It is partitioned into chunks so each chunk is the same logical size.
Following is an example that uses the H5P_DATASET_CREATE property list to create
a chunked and extendible dataset:
<BR>
[ <A HREF="examples/h5_extend.c">C program</A> ]
- <code>h5_extend.c</code><BR>
<P>
</UL>
<LI>Compression: (gzip compression)
<LI>External Storage Properties: The data must be contiguous to be stored
externally. It allows you to store the data in one or more non-HDF5 files.
Following is an example of using the H5P_DATASET_CREATE property list to
create a dataset in an external file:
<BR>
[ <A HREF="examples/h5_crtextd.c">C program</A> ]
- <code>h5_crtextd.c</code><BR>
<P>
</UL>
</UL>
<A NAME="rdwt">
<H3>Reading or Writing Data</H3>
The Data Transfer property list, H5P_DATASET_XFER, is used to control
various aspects of I/O, such as caching hints or collective I/O information.
<P>
The following code sets the maximum size for the type conversion buffer
and background buffer:
<PRE>
plist_xfer = H5Pcreate (H5P_DATASET_XFER);
H5Pset_buffer(plist_xfer, (hsize_t)NX*NY*NZ, NULL, NULL);
status = H5Dread (dataset, H5T_NATIVE_UCHAR, memspace, dataspace,
plist_xfer);
</PRE>
<!--
See:<BR>
[ <A HREF="examples/h5_xfer.c">C program</A> ]
- <code> h5_xfer.c</code><BR>
-->
<!-- 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 -->
</FONT>
<BR>
<!-- <A HREF="mailto:hdfhelp@ncsa.uiuc.edu"> -->
</BODY>
</HTML>
|
