mirror of
https://github.com/HDFGroup/hdf5.git
synced 2024-11-27 02:10:55 +08:00
235 lines
6.1 KiB
HTML
235 lines
6.1 KiB
HTML
<HTML><HEAD>
|
|
<TITLE>HDF5 Tutorial - Compound Datatypes
|
|
</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">Compound Datatypes</FONT>
|
|
</BIG></BIG></BIG></H1>
|
|
|
|
<hr noshade size=1>
|
|
|
|
<BODY>
|
|
<H2>Contents:</H2>
|
|
<UL>
|
|
<LI><A HREF="#def">Creating Compound Datatypes</A>
|
|
<LI>Programming Example
|
|
<UL>
|
|
<LI> <A HREF="#desc">Description</A>
|
|
<LI> <A HREF="#rem">Remarks</A>
|
|
<LI> <A HREF="#fc">File Contents</A>
|
|
</UL>
|
|
</UL>
|
|
<HR>
|
|
<A NAME="def">
|
|
<H2>Creating Compound Datatypes</H2>
|
|
A compound datatype is similar to a struct in C or a common block in
|
|
FORTRAN. It is a collection of one or more atomic types or small arrays of
|
|
such types. To create and use a compound datatype you need to be familiar
|
|
with various properties of the compound datatype:
|
|
<UL>
|
|
<LI>It is of class <strong>compound</strong>.
|
|
<LI>It has a fixed total size, in bytes.
|
|
<LI>It consists of zero or more members (defined in any order) with
|
|
unique names and occupying non-overlapping regions within the datum.
|
|
<LI>Each member has its own datatype.
|
|
<LI>Each member is referenced by an index number between zero and <em>N</em>-1,
|
|
where <em>N</em> is the number of members in the compound datatype.
|
|
<LI>Each member has a name which is unique among its siblings in a
|
|
compound datatype.
|
|
<LI>Each member has a fixed byte offset, which locates the first byte
|
|
(smallest byte address) of that member in the compound datatype.
|
|
<LI>Each member can be a small array of up to four dimensions.
|
|
</UL>
|
|
Properties of members of a compound datatype are defined when the
|
|
member is added to the compound datatype and cannot be subsequently modified.
|
|
<P>
|
|
Compound datatypes must be built out of other datatypes. First, one
|
|
creates an empty compound datatype and specifies its total size. Then
|
|
members are added to the compound datatype in any order.
|
|
|
|
<H2> Programming Example</H2>
|
|
<A NAME="desc">
|
|
<H3><U>Description</U></H3>
|
|
|
|
This example shows how to create a compound datatype, write an array
|
|
to the file which uses the compound datatype, and read back subsets of
|
|
the members.
|
|
<p>
|
|
<UL>
|
|
[ <A HREF="examples/h5_compound.c">C Example</A> ] - <code>h5_compound.c</code>
|
|
<BR>
|
|
[ <A HREF="examples/compound.f90">Fortran 90 Example</A> ]
|
|
- <code>compound.f90</code>
|
|
<BR>
|
|
[ <A HREF="examples/java/Compound.java">Java Example</A> ] - <code>Compound.java</code>
|
|
</UL>
|
|
The program outputs the following:
|
|
<PRE>
|
|
|
|
Field c :
|
|
1.0000 0.5000 0.3333 0.2500 0.2000 0.1667 0.1429 0.1250 0.1111 0.1000
|
|
|
|
Field a :
|
|
0 1 2 3 4 5 6 7 8 9
|
|
|
|
Field b :
|
|
0.0000 1.0000 4.0000 9.0000 16.0000 25.0000 36.0000 49.0000 64.0000 81.0000
|
|
|
|
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
|
|
</PRE>
|
|
|
|
<A NAME="rem">
|
|
<H3><U>Remarks</U></H3>
|
|
<UL>
|
|
<LI><CODE>H5Tcreate</CODE> creates a new datatype of the specified class with
|
|
the specified number of bytes.
|
|
<PRE>
|
|
hid_t H5Tcreate ( H5T_class_t class, size_t size )
|
|
</PRE>
|
|
<UL>
|
|
<LI>The <I>class</I> parameter specifies the datatype to create.
|
|
Currently only the <CODE>H5T_COMPOUND</CODE> datatype class is supported with this
|
|
function.
|
|
<LI>The <I>size</I> parameter specifies the number of bytes in the
|
|
datatype to create.
|
|
</UL>
|
|
<P>
|
|
<LI><CODE>H5Tinsert</CODE> adds a member to the compound datatype specified by
|
|
<I>type_id</I>.
|
|
<PRE>
|
|
herr_t H5Tinsert ( hid_t type_id, const char * name, off_t offset,
|
|
hid_t field_id )
|
|
</PRE>
|
|
<UL>
|
|
<LI>The <I>type_id</I> parameter is the identifier of the compound datatype
|
|
to modify.
|
|
<LI>The <I>name</I> parameter is the name of the field to insert. The new
|
|
member name must be unique within a compound datatype.
|
|
<LI>The <I>offset</I> parameter is the offset in the memory structure of
|
|
the field to insert.
|
|
|
|
The library defines the <CODE>HOFFSET</CODE> macro to compute the offset of a member within
|
|
a struct:
|
|
<PRE>
|
|
HOFFSET ( s, m )
|
|
</PRE>
|
|
This macro computes the offset of member <I>m</I> within a struct
|
|
variable <I>s</I>.
|
|
|
|
<LI>The <I>field_id</I> parameter is the datatype identifier of the
|
|
field to insert.
|
|
</UL>
|
|
<P>
|
|
<LI><CODE>H5Tclose</CODE> releases a datatype.
|
|
<PRE>
|
|
herr_t H5Tclose ( hid_t type_id )
|
|
</PRE>
|
|
The <I>type_id</I> parameter is the identifier of the datatype to release.
|
|
</UL>
|
|
<A NAME="fc">
|
|
<H3><U>File Contents</U></H3>
|
|
|
|
<PRE>
|
|
HDF5 "SDScompound.h5" {
|
|
GROUP "/" {
|
|
DATASET "ArrayOfStructures" {
|
|
DATATYPE {
|
|
H5T_STD_I32BE "a_name";
|
|
H5T_IEEE_F32BE "b_name";
|
|
H5T_IEEE_F64BE "c_name";
|
|
}
|
|
DATASPACE { SIMPLE ( 10 ) / ( 10 ) }
|
|
DATA {
|
|
{
|
|
[ 0 ],
|
|
[ 0 ],
|
|
[ 1 ]
|
|
},
|
|
{
|
|
[ 1 ],
|
|
[ 1 ],
|
|
[ 0.5 ]
|
|
},
|
|
{
|
|
[ 2 ],
|
|
[ 4 ],
|
|
[ 0.333333 ]
|
|
},
|
|
{
|
|
[ 3 ],
|
|
[ 9 ],
|
|
[ 0.25 ]
|
|
},
|
|
{
|
|
[ 4 ],
|
|
[ 16 ],
|
|
[ 0.2 ]
|
|
},
|
|
{
|
|
[ 5 ],
|
|
[ 25 ],
|
|
[ 0.166667 ]
|
|
},
|
|
{
|
|
[ 6 ],
|
|
[ 36 ],
|
|
[ 0.142857 ]
|
|
},
|
|
{
|
|
[ 7 ],
|
|
[ 49 ],
|
|
[ 0.125 ]
|
|
},
|
|
{
|
|
[ 8 ],
|
|
[ 64 ],
|
|
[ 0.111111 ]
|
|
},
|
|
{
|
|
[ 9 ],
|
|
[ 81 ],
|
|
[ 0.1 ]
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
</PRE>
|
|
|
|
|
|
|
|
<!-- 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>
|
|
|
|
|
|
|