mirror of
https://github.com/HDFGroup/hdf5.git
synced 2024-12-03 02:32:04 +08:00
344 lines
9.9 KiB
HTML
344 lines
9.9 KiB
HTML
<HTML><HEAD>
|
|
<TITLE>HDF5 Tutorial - Creating an Attribute
|
|
</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">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, read, and write an attribute.
|
|
<P>
|
|
<P>
|
|
<H3>Creating an attribute</H3>
|
|
<P>
|
|
Creating an attribute is similar to creating a dataset. To create an
|
|
attribute, the application must specify the object which the attribute is
|
|
attached to, the datatype and dataspace of the attribute data,
|
|
and the attribute creation property list.
|
|
<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 the
|
|
attribute creation property list.
|
|
<UL>
|
|
<LI> Define the datatype.
|
|
<LI> Define the dataspace.
|
|
<LI> Specify the attribute creation property list.
|
|
</UL>
|
|
<LI> Create the attribute.
|
|
<LI> Close the attribute and datatype, dataspace, and
|
|
attribute creation property list, if necessary.
|
|
</OL>
|
|
<P>
|
|
To create and close an attribute, the calling program must use
|
|
<code>H5Acreate</code>/<code>h5acreate_f</code> and
|
|
<code>H5Aclose</code>/<code>h5aclose_f</code>. For example:
|
|
<P>
|
|
<I>C</I>:
|
|
<PRE>
|
|
attr_id = H5Acreate (dset_id, attr_name, type_id, space_id, creation_prp);
|
|
status = H5Aclose (attr_id);
|
|
</PRE>
|
|
<I>FORTRAN</I>:
|
|
<PRE>
|
|
CALL h5acreate_f (dset_id, attr_nam, type_id, space_id, attr_id, &
|
|
hdferr, creation_prp=creat_plist_id)
|
|
<i>or</i>
|
|
CALL h5acreate_f (dset_id, attr_nam, type_id, space_id, attr_id, hdferr)
|
|
|
|
CALL h5aclose_f (attr_id, hdferr)
|
|
</PRE>
|
|
|
|
<H3>Reading/Writing an attribute</H3>
|
|
<P>
|
|
Attributes may only be read or written as an entire object; no partial I/O is
|
|
supported. Therefore, to perform I/O operations on an attribute, the
|
|
application needs only to specify the attribute and the attribute's memory
|
|
datatype.
|
|
<P>
|
|
The steps to read or write an attribute are as follows.
|
|
<OL>
|
|
<LI> Obtain the attribute identifier.
|
|
<LI> Specify the attribute's memory datatype.
|
|
<LI> Perform the desired operation.
|
|
<LI> Close the memory datatype if necessary.
|
|
</OL>
|
|
<P>
|
|
To read and/or write an attribute, the calling program must contain the
|
|
<code>H5Aread</code>/<code>h5aread_f</code> and/or
|
|
<code>H5Awrite</code>/<code>h5awrite_f</code> routines. For example:
|
|
<P>
|
|
<I>C</I>:
|
|
<PRE>
|
|
status = H5Aread (attr_id, mem_type_id, buf);
|
|
status = H5Awrite (attr_id, mem_type_id, buf);
|
|
</PRE>
|
|
<I>FORTRAN</I>:
|
|
<PRE>
|
|
CALL h5awrite_f (attr_id, mem_type_id, buf, hdferr)
|
|
CALL h5aread_f (attr_id, mem_type_id, buf, hdferr)
|
|
</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 <code>dset.h5</code> in C
|
|
(<code>dsetf.h5</code> in FORTRAN),
|
|
obtains the identifier of the dataset <code>/dset</code>,
|
|
defines the attribute's dataspace, creates the dataset attribute, writes
|
|
the attribute, and then closes the attribute's dataspace, attribute, dataset,
|
|
and file. <BR>
|
|
<UL>
|
|
[ <A HREF="examples/h5_crtatt.c">C Example </A> ] - <code>h5_crtatt.c</code><BR>
|
|
[ <A HREF="examples/attrexample.f90">FORTRAN Example</A> ] - <code>attrexample.f90</code><BR>
|
|
[ <A HREF="examples/java/CreateAttribute.java">Java Example </A> ]
|
|
- <code>CreateAttribute.java</code><BR>
|
|
</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>
|
|
<UL>
|
|
<LI><code>H5Acreate</code>/<code>h5acreate_f</code> creates an attribute
|
|
which is attached to the object specified by the first parameter,
|
|
and returns an identifier.
|
|
<P>
|
|
<I>C</I>:
|
|
<PRE>
|
|
hid_t H5Acreate (hid_t obj_id, const char *name, hid_t type_id,
|
|
hid_t space_id, hid_t creation_prp)
|
|
</PRE>
|
|
<I>FORTRAN</I>:
|
|
<PRE>
|
|
h5acreate_f (obj_id, name, type_id, space_id, attr_id, &
|
|
hdferr, creation_prp)
|
|
|
|
obj_id INTEGER(HID_T)
|
|
name CHARACTER(LEN=*)
|
|
type_id INTEGER(HID_T)
|
|
space_id INTEGER(HID_T)
|
|
attr_id INTEGER(HID_T)
|
|
hdferr INTEGER
|
|
(Possible values: 0 on success and -1 on failure)
|
|
creation_prp INTEGER(HID_T), OPTIONAL
|
|
|
|
</PRE>
|
|
<UL>
|
|
<LI> The <I>obj_id</I> parameter is the identifier of the object that
|
|
the attribute is attached to.
|
|
<P>
|
|
<LI> The <I>name</I> parameter is the name of the attribute to create.
|
|
<P>
|
|
<LI> The <I>type_id</I> parameter is the identifier of the
|
|
attribute's datatype.
|
|
<P>
|
|
<LI> The <I>space_id</I> parameter is the identifier of the attribute's
|
|
dataspace.
|
|
<P>
|
|
<LI> The <I>creation_prp</I> parameter is the creation property list
|
|
identifier.
|
|
<code>H5P_DEFAULT</code> in C (<code>H5P_DEFAULT_F</code> in FORTRAN)
|
|
specifies the default creation property list.
|
|
This parameter is optional in FORTRAN; when it is omitted,
|
|
the default creation property list is used.
|
|
<P>
|
|
<LI> In FORTRAN, the return code for this call is returned in <I>hdferr</I>:
|
|
0 if successful, -1 if not. The attribute identifier is returned
|
|
in <I>attr_id</I>. In C, the function returns the
|
|
attribute identifier if successful and a negative value if not.
|
|
|
|
|
|
</UL>
|
|
<P>
|
|
<LI><code>H5Awrite</code>/<code>h5awrite_f</code> writes the entire attribute,
|
|
and returns the status of the write.
|
|
<P>
|
|
<I>C</I>:
|
|
<PRE>
|
|
herr_t H5Awrite (hid_t attr_id, hid_t mem_type_id, void *buf)
|
|
</PRE>
|
|
<I>FORTRAN</I>:
|
|
<PRE>
|
|
h5awrite_f (attr_id, mem_type_id, buf, hdferr)
|
|
|
|
attr_id INTEGER(HID_T)
|
|
memtype_id INTEGER(HID_T)
|
|
buf TYPE(VOID)
|
|
hdferr INTEGER
|
|
(Possible values: 0 on success and -1 on failure)
|
|
|
|
</PRE>
|
|
<UL>
|
|
<LI> The <I>attr_id</I> parameter is the identifier of the attribute
|
|
to write.
|
|
<P>
|
|
<LI> The <I>mem_type_id</I> parameter is the identifier of the
|
|
attribute's memory datatype.
|
|
<P>
|
|
<LI> The <I>buf</I> parameter is the data buffer to write out.
|
|
<P>
|
|
<LI>In C, this function returns a non-negative value if successful and
|
|
a negative value, otherwise. In FORTRAN, the return value is in the
|
|
<I>hdferr</I> parameter: 0 if successful, -1 otherwise.
|
|
</UL>
|
|
<P>
|
|
<LI> When an attribute is no longer accessed by a program,
|
|
<code>H5Aclose</code>/<code>h5aclose_f</code> must be called
|
|
to release the attribute from use.
|
|
The C routine returns a non-negative value if successful;
|
|
otherwise it returns a negative value.
|
|
In FORTRAN, the return value is in the <I>hdferr</I> parameter:
|
|
0 if successful, -1 otherwise.
|
|
<P>
|
|
<I>C</I>:
|
|
<pre>
|
|
herr_t H5Aclose (hid_t attr_id)
|
|
</pre>
|
|
|
|
<I>FORTRAN</I>:
|
|
<pre>
|
|
h5aclose_f (attr_id, hdferr)
|
|
|
|
attr_id INTEGER(HID_T)
|
|
hdferr INTEGER
|
|
(Possible values: 0 on success and -1 on failure)
|
|
|
|
</pre>
|
|
<ul>
|
|
<li> An <code>H5Aclose</code>/<code>h5aclose_f</code> call is mandatory.
|
|
</ul>
|
|
</UL>
|
|
|
|
|
|
|
|
<A NAME="fc">
|
|
<H3><U>File Contents</U></H3>
|
|
<P>
|
|
The contents of <code>dset.h5</code> (<code>dsetf.h5</code> for FORTRAN) and the
|
|
attribute definition are shown below:
|
|
<P>
|
|
<B>Fig. 7.1a</B> <I><code>dset.h5</code> 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>
|
|
<B>Fig. 7.1b</B> <I><code>dsetf.h5</code> in DDL</I>
|
|
<PRE>
|
|
HDF5 "dsetf.h5" {
|
|
GROUP "/" {
|
|
DATASET "dset" {
|
|
DATATYPE { H5T_STD_I32BE }
|
|
DATASPACE { SIMPLE ( 6, 4 ) / ( 6, 4 ) }
|
|
DATA {
|
|
1, 7, 13, 19,
|
|
2, 8, 14, 20,
|
|
3, 9, 15, 21,
|
|
4, 10, 16, 22,
|
|
5, 11, 17, 23,
|
|
6, 12, 18, 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="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 -->
|
|
</FONT>
|
|
<BR>
|
|
<!-- <A HREF="mailto:hdfhelp@ncsa.uiuc.edu"> -->
|
|
|
|
</BODY>
|
|
</HTML>
|
|
|
|
|
|
|