diff options
Diffstat (limited to 'doc/html/Tutor/crtatt.html')
| -rw-r--r-- | doc/html/Tutor/crtatt.html | 343 |
1 files changed, 0 insertions, 343 deletions
diff --git a/doc/html/Tutor/crtatt.html b/doc/html/Tutor/crtatt.html deleted file mode 100644 index 3a4d374..0000000 --- a/doc/html/Tutor/crtatt.html +++ /dev/null @@ -1,343 +0,0 @@ -<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> - - - |