268 lines
7.5 KiB
HTML
268 lines
7.5 KiB
HTML
<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 <hdf5.h>
|
|
#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> <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> <I>HDF5 Attribute Definition</I>
|
|
<PRE>
|
|
|
|
<attribute> ::= ATTRIBUTE "<attr_name>" { <datatype>
|
|
<dataspace>
|
|
<data> }
|
|
|
|
</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>
|
|
|
|
|
|
|