mirror of
https://github.com/HDFGroup/hdf5.git
synced 2025-02-11 16:01:00 +08:00
345e07fc11
Purpose:
[is this a bug fix? feature? ...]
Description:
[describe the bug, or describe the new feature, etc]
Solution:
[details about the changes, algorithm, etc...]
[Please as detail as you can since your own explanation is
better than others guessing it from the code.]
Platforms tested:
[machines you have tested the changed version. This is absolute
important. Test it out on at least two or three different platforms
such as Big-endian-32bit (SUN/IRIX), little-endian-32(LINUX) and
64-bit (IRIX64/UNICOS/DEC-ALPHA) would be good.]
170 lines
5.2 KiB
HTML
170 lines
5.2 KiB
HTML
<HTML><HEAD>
|
|
<TITLE>HDF5 Tutorial - Property Lists
|
|
</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">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="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: February 12, 2001</H6><BR>
|
|
<!-- modified by Barbara Jones - bljones@ncsa.uiuc.edu -->
|
|
</FONT>
|
|
<BR>
|
|
<!-- <A HREF="mailto:hdfhelp@ncsa.uiuc.edu"> -->
|
|
|
|
</BODY>
|
|
</HTML>
|
|
|
|
|
|
|