diff options
| author | Frank Baker <fbaker@hdfgroup.org> | 2000-12-22 20:47:59 (GMT) |
|---|---|---|
| committer | Frank Baker <fbaker@hdfgroup.org> | 2000-12-22 20:47:59 (GMT) |
| commit | c1d537db2b803d6908fe3f21f62c592c9cd2bf70 (patch) | |
| tree | 56a6cb7f00a6fbec3b071722df9705e744368073 /doc/html/Tutor/crtatt.html | |
| parent | d4c3773742b8dee426e7325fee4e8fc4015f2802 (diff) | |
| download | hdf5-c1d537db2b803d6908fe3f21f62c592c9cd2bf70.zip hdf5-c1d537db2b803d6908fe3f21f62c592c9cd2bf70.tar.gz hdf5-c1d537db2b803d6908fe3f21f62c592c9cd2bf70.tar.bz2 | |
[svn-r3196]
Purpose:
Adding Tutorial to development branch (R 1.4)
Platforms tested:
IE 5
Diffstat (limited to 'doc/html/Tutor/crtatt.html')
| -rw-r--r-- | doc/html/Tutor/crtatt.html | 267 |
1 files changed, 267 insertions, 0 deletions
diff --git a/doc/html/Tutor/crtatt.html b/doc/html/Tutor/crtatt.html new file mode 100644 index 0000000..82de873 --- /dev/null +++ b/doc/html/Tutor/crtatt.html @@ -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 <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> + + + |