philipp/hdf5
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

[svn-r1736] HDF5 Tutorial: First version of Tutorial to be checked in for distribution.

Browse Source
This commit is contained in:
Frank Baker
1999-10-08 18:03:05 -05:00
parent 59b430fbdd
commit 3c2fc7a967
75 changed files with 6823 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

267
doc/html/Tutor/crtatt.html Normal file
View File

@@ -0,0 +1,267 @@
<HTML><HEAD>
<TITLE>HDF5 Tutorial - Creating an Attribute
</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">Creating an Attribute</FONT>
</BIG></BIG></BIG></H1>
<hr noshade size=1>
<BODY>
<H2>Contents:</H2>
<UL>
<LI> <A HREF="#def">What is an Attribute</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">Attribute Definition in DDL</A>
</UL>
</UL>
<HR>
<A NAME="def">
<H2>What is an Attribute?</h2>
<P>
Attributes are small datasets that can be used to describe the nature and/or
the intended usage of the object they are attached to. In this section, we
show how to create and read/write an attribute.
<P>
<P>
<H3>Creating an attribute</H3>
<P>
Creating an attribute is similar to the creation of a dataset. To create an
attribute the application must specify the object which the attribute is
attached to, the data type and space of the attribute data and the creation
properties.
<P>
The steps to create an attribute are as follows:
<OL>
<LI> Obtain the object identifier that the attribute is to be attached to.
<LI> Define the characteristics of the attribute and specify creation
properties.
<UL>
<LI> Define the data type.
<LI> Define the dataspace.
<LI> Specify the creation properties.
</UL>
<LI> Create the attribute.
<LI> Close the attribute and data type, dataspace, and creation property
list if necessary.
</OL>
<P>
To create an attribute, the calling program must contain the following calls:
<PRE>
attr_id = H5Acreate(loc_id, attr_name, type_id, space_id, create_plist);
H5Aclose(attr_id);
</PRE>
<H3>Reading/Writing an attribute</H3>
<P>
Attributes may only be read/written as an entire object. No partial I/O is
currently supported. Therefore, to perform I/O operations on an attribute, the
application needs only to specify the attribute and the attribute's memory
data type.
<P>
The steps to read/write an attribute are as follows.
<OL>
<LI> Obtain the attribute identifier.
<LI> Specify the attribute's memory data type.
<LI> Perform the desired operation.
<LI> Close the memory data type if necessary.
</OL>
<P>
To read/write an attribute, the calling program must contain the following
calls:
<PRE>
status = H5Aread(attr_id, mem_type_id, buf);
</PRE>
or
<PRE>
status = H5Awrite(attr_id, mem_type_id, buf);
</PRE>
<P>
<H2> Programming Example</H2>
<A NAME="desc">
<H3><U>Description</U></H3>
This example shows how to create and write a dataset attribute.
It opens an existing file 'dset.h5', obtains the id of the dataset "/dset1",
defines the attribute's dataspace, creates the dataset attribute, writes
the attribute, and then closes the attribute's dataspace, attribute, dataset,
and file. <BR>
[ <A HREF="examples/h5_crtatt.c">Download h5_crtatt.c</A> ]
<PRE>
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
#include &lt;hdf5.h&gt;
#define FILE "dset.h5"
main() {
hid_t file_id, dataset_id, attribute_id, dataspace_id; /* identifiers
*/
hsize_t dims;
int attr_data[2];
herr_t status;
/* Initialize the attribute data. */
attr_data[0] = 100;
attr_data[1] = 200;
/* Open an existing file. */
file_id = H5Fopen(FILE, H5F_ACC_RDWR, H5P_DEFAULT);
/* Open an existing dataset. */
dataset_id = H5Dopen(file_id, "/dset");
/* Create the data space for the attribute. */
dims = 2;
dataspace_id = H5Screate_simple(1, &dims, NULL);
/* Create a dataset attribute. */
attribute_id = H5Acreate(dataset_id, "attr", H5T_STD_I32BE, dataspace_id, H5P_DEFAULT);
/* Write the attribute data. */
status = H5Awrite(attribute_id, H5T_NATIVE_INT, attr_data);
/* Close the attribute. */
status = H5Aclose(attribute_id);
/* Close the dataspace. */
status = H5Sclose(dataspace_id);
/* Close to the dataset. */
status = H5Dclose(dataset_id);
/* Close the file. */
status = H5Fclose(file_id);
}
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
</PRE>
<A NAME="rem">
<H3><U>Remarks</U></H3>
<UL>
<LI> H5Acreate creates an attribute which is attached to the object specified by
the first parameter, and returns an identifier.
<PRE>
hid_t H5Acreate (hid_t loc_id, const char *name, hid_t type_id,
hid_t space_id, hid_t create_plist)
</PRE>
<UL>
<LI> The first parameter is the identifier of the object which the attribute is
attached to.
<LI> The second parameter is the name of the attribute to create.
<LI> The third parameter is the identifier of the attribute's datatype.
<LI> The fourth parameter is the identifier of the attribute's dataspace.
<LI> The last parameter is the identifier of the creation property list.
H5P_DEFAULT specifies the default creation property list.
</UL>
<P>
<LI> H5Awrite writes the entire attribute, and returns the status of the write.
<PRE>
herr_t H5Awrite (hid_t attr_id, hid_t mem_type_id, void *buf)
</PRE>
<UL>
<LI> The first parameter is the identifier of the attribute to write.
<LI> The second parameter is the identifier of the attribute's memory datatype.
<LI> The last parameter is the data buffer.
</UL>
<P>
<LI> When an attribute is no longer accessed by a program, H5Aclose must be called
to release the attribute from use. This call is mandatory.
<PRE>
herr_t H5Aclose (hid_t attr_id)
</PRE>
</UL>
<A NAME="fc">
<H3><U>File Contents</U></H3>
<P>
The contents of 'dset.h5' and the attribute definition are given in the
following:
<P>
<B>Fig. 7.1</B> &nbsp; <I>'dset.h5' in DDL</I>
<PRE>
HDF5 "dset.h5" {
GROUP "/" {
DATASET "dset" {
DATATYPE { H5T_STD_I32BE }
DATASPACE { SIMPLE ( 4, 6 ) / ( 4, 6 ) }
DATA {
1, 2, 3, 4, 5, 6,
7, 8, 9, 10, 11, 12,
13, 14, 15, 16, 17, 18,
19, 20, 21, 22, 23, 24
}
ATTRIBUTE "attr" {
DATATYPE { H5T_STD_I32BE }
DATASPACE { SIMPLE ( 2 ) / ( 2 ) }
DATA {
100, 200
}
}
}
}
}
</PRE>
<A NAME="ddl">
<h3><U>Attribute Definition in DDL</U></H3>
<B>Fig. 7.2</B> &nbsp; <I>HDF5 Attribute Definition</I>
<PRE>
&lt;attribute&gt ::= ATTRIBUTE "&lt;attr_name&gt;" { &lt;datatype&gt
&lt;dataspace&gt
&lt;data&gt }
</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="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> <H6>Last Modified: August 27, 1999</H6><BR>
<!-- modified by Barbara Jones - bljones@ncsa.uiuc.edu -->
</FONT>
<BR>
<!-- <A HREF="mailto:hdfhelp@ncsa.uiuc.edu"> -->
</BODY>
</HTML>