mirror of
https://github.com/HDFGroup/hdf5.git
synced 2024-11-27 02:10:55 +08:00
285 lines
7.9 KiB
HTML
285 lines
7.9 KiB
HTML
<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>
|
|
|
|
|
|
|