diff options
| author | byrnHDF <byrnHDF@users.noreply.github.com> | 2023-11-16 13:49:28 (GMT) |
|---|---|---|
| committer | byrnHDF <byrnHDF@users.noreply.github.com> | 2023-11-16 13:49:28 (GMT) |
| commit | 4f20d880c97be1249f8d89ced95f72836dbf3ee0 (patch) | |
| tree | 30d8dcb282134b7126b092796f2be00d2d97bd3c /develop/_l_b_attr_create.html | |
| parent | 4e7e457497c948b41c8b0065225875bf10cdf9d4 (diff) | |
| download | hdf5-4f20d880c97be1249f8d89ced95f72836dbf3ee0.zip hdf5-4f20d880c97be1249f8d89ced95f72836dbf3ee0.tar.gz hdf5-4f20d880c97be1249f8d89ced95f72836dbf3ee0.tar.bz2 | |
deploy: ef39882fa1e13740d2530c7a0637bd1f1a822b68
Diffstat (limited to 'develop/_l_b_attr_create.html')
| -rw-r--r-- | develop/_l_b_attr_create.html | 248 |
1 files changed, 248 insertions, 0 deletions
diff --git a/develop/_l_b_attr_create.html b/develop/_l_b_attr_create.html new file mode 100644 index 0000000..18749bf --- /dev/null +++ b/develop/_l_b_attr_create.html @@ -0,0 +1,248 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"> +<head> +<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/> +<meta http-equiv="X-UA-Compatible" content="IE=9"/> +<meta name="generator" content="Doxygen 1.9.1"/> +<meta name="viewport" content="width=device-width, initial-scale=1"/> +<title>HDF5: Creating an Attribute</title> +<link href="tabs.css" rel="stylesheet" type="text/css"/> +<script type="text/javascript" src="jquery.js"></script> +<script type="text/javascript" src="dynsections.js"></script> +<link href="navtree.css" rel="stylesheet" type="text/css"/> +<script type="text/javascript" src="resize.js"></script> +<script type="text/javascript" src="navtreedata.js"></script> +<script type="text/javascript" src="navtree.js"></script> +<link href="search/search.css" rel="stylesheet" type="text/css"/> +<script type="text/javascript" src="search/searchdata.js"></script> +<script type="text/javascript" src="search/search.js"></script> +<script type="text/javascript"> +/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */ + $(document).ready(function() { init_search(); }); +/* @license-end */ +</script> +<link href="doxygen.css" rel="stylesheet" type="text/css" /> +<link href="hdf5doxy.css" rel="stylesheet" type="text/css"> +<!-- <link href="hdf5doxy.css" rel="stylesheet" type="text/css"/> + --> +<script type="text/javascript" src="hdf5_navtree_hacks.js"></script> +</head> +<body> +<div style="background:#FFDDDD;font-size:120%;text-align:center;margin:0;padding:5px">Please, help us to better serve our user community by answering the following short survey: <a href="https://www.hdfgroup.org/website-survey/">https://www.hdfgroup.org/website-survey/</a></div> +<div id="top"><!-- do not remove this div, it is closed by doxygen! --> +<div id="titlearea"> +<table cellspacing="0" cellpadding="0"> + <tbody> + <tr style="height: 56px;"> + <td id="projectlogo"><img alt="Logo" src="HDFG-logo.png"/></td> + <td id="projectalign" style="padding-left: 0.5em;"> + <div id="projectname"><a href="https://www.hdfgroup.org">HDF5</a> +  <span id="projectnumber">1.15.0.ef39882</span> + </div> + <div id="projectbrief">API Reference</div> + </td> + <td> <div id="MSearchBox" class="MSearchBoxInactive"> + <span class="left"> + <img id="MSearchSelect" src="search/mag_sel.svg" + onmouseover="return searchBox.OnSearchSelectShow()" + onmouseout="return searchBox.OnSearchSelectHide()" + alt=""/> + <input type="text" id="MSearchField" value="Search" accesskey="S" + onfocus="searchBox.OnSearchFieldFocus(true)" + onblur="searchBox.OnSearchFieldFocus(false)" + onkeyup="searchBox.OnSearchFieldChange(event)"/> + </span><span class="right"> + <a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.svg" alt=""/></a> + </span> + </div> +</td> + </tr> + </tbody> +</table> +</div> +<!-- end header part --> +<!-- Generated by Doxygen 1.9.1 --> +<script type="text/javascript"> +/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */ +var searchBox = new SearchBox("searchBox", "search",false,'Search','.html'); +/* @license-end */ +</script> +</div><!-- top --> +<div id="side-nav" class="ui-resizable side-nav-resizable"> + <div id="nav-tree"> + <div id="nav-tree-contents"> + <div id="nav-sync" class="sync"></div> + </div> + </div> + <div id="splitbar" style="-moz-user-select:none;" + class="ui-resizable-handle"> + </div> +</div> +<script type="text/javascript"> +/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */ +$(document).ready(function(){initNavTree('_l_b_attr_create.html',''); initResizable(); }); +/* @license-end */ +</script> +<div id="doc-content"> +<!-- window showing the filter options --> +<div id="MSearchSelectWindow" + onmouseover="return searchBox.OnSearchSelectShow()" + onmouseout="return searchBox.OnSearchSelectHide()" + onkeydown="return searchBox.OnSearchSelectKey(event)"> +</div> + +<!-- iframe showing the search results (closed by default) --> +<div id="MSearchResultsWindow"> +<iframe src="javascript:void(0)" frameborder="0" + name="MSearchResults" id="MSearchResults"> +</iframe> +</div> + +<div class="PageDoc"><div class="header"> + <div class="headertitle"> +<div class="title">Creating an Attribute </div> </div> +</div><!--header--> +<div class="contents"> +<div class="textblock"><p>Navigate back: <a class="el" href="index.html">Main</a> / <a class="el" href="_getting_started.html">Getting Started with HDF5</a> / <a class="el" href="_learn_basics.html">Learning the Basics</a> </p><hr /> +<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> +<h1><a class="anchor" id="secLBAttrCreate"></a> +Creating an attribute</h1> +<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> +<p>The steps to create an attribute are as follows: </p><ol> +<li> +Obtain the object identifier that the attribute is to be attached to. </li> +<li> +Define the characteristics of the attribute and specify the attribute creation property list. <ul> +<li> +Define the datatype. </li> +<li> +Define the dataspace. </li> +<li> +Specify the attribute creation property list. </li> +</ul> +</li> +<li> +Create the attribute. </li> +<li> +Close the attribute and datatype, dataspace, and attribute creation property list, if necessary. </li> +</ol> +<p>To create and close an attribute, the calling program must use <a class="el" href="group___h5_a.html#ga4a76e4e5ab6eb0fd2aa7990d38d55f24">H5Acreate</a> and <a class="el" href="group___h5_a.html#gaef4394b661e2c930879e9868e122bdda" title="Closes the specified attribute.">H5Aclose</a>. For example:</p> +<p><em>C</em> </p><div class="fragment"><div class="line">attr_id = <a class="code" href="group___h5_a.html#ga4a76e4e5ab6eb0fd2aa7990d38d55f24">H5Acreate</a> (dataset_id, <span class="stringliteral">"Units"</span>, <a class="code" href="group___p_d_t_s_t_d.html#ga37e8a6be7ee64587c2a282b965019bb8">H5T_STD_I32BE</a>, dataspace_id, <a class="code" href="_h5_ppublic_8h.html#afa85e97bfbf9bf1c58e39263846c568f">H5P_DEFAULT</a>, <a class="code" href="_h5_ppublic_8h.html#afa85e97bfbf9bf1c58e39263846c568f">H5P_DEFAULT</a>)</div> +<div class="line">status = <a class="code" href="group___h5_a.html#gaef4394b661e2c930879e9868e122bdda">H5Aclose</a> (attr_id);</div> +<div class="ttc" id="a_h5_ppublic_8h_html_afa85e97bfbf9bf1c58e39263846c568f"><div class="ttname"><a href="_h5_ppublic_8h.html#afa85e97bfbf9bf1c58e39263846c568f">H5P_DEFAULT</a></div><div class="ttdeci">#define H5P_DEFAULT</div><div class="ttdef"><b>Definition:</b> H5Ppublic.h:102</div></div> +<div class="ttc" id="agroup___h5_a_html_ga4a76e4e5ab6eb0fd2aa7990d38d55f24"><div class="ttname"><a href="group___h5_a.html#ga4a76e4e5ab6eb0fd2aa7990d38d55f24">H5Acreate</a></div><div class="ttdeci">#define H5Acreate</div><div class="ttdef"><b>Definition:</b> H5version.h:868</div></div> +<div class="ttc" id="agroup___h5_a_html_gaef4394b661e2c930879e9868e122bdda"><div class="ttname"><a href="group___h5_a.html#gaef4394b661e2c930879e9868e122bdda">H5Aclose</a></div><div class="ttdeci">herr_t H5Aclose(hid_t attr_id)</div><div class="ttdoc">Closes the specified attribute.</div></div> +<div class="ttc" id="agroup___p_d_t_s_t_d_html_ga37e8a6be7ee64587c2a282b965019bb8"><div class="ttname"><a href="group___p_d_t_s_t_d.html#ga37e8a6be7ee64587c2a282b965019bb8">H5T_STD_I32BE</a></div><div class="ttdeci">#define H5T_STD_I32BE</div><div class="ttdef"><b>Definition:</b> H5Tpublic.h:305</div></div> +</div><!-- fragment --><p><em>Fortran</em> </p><div class="fragment"><div class="line">CALL <a class="code" href="group___f_h5_a.html#gaea165327da713ef670c14ab5b05c61dd">h5acreate_f</a> (dset_id, attr_nam, type_id, space_id, attr_id, &</div> +<div class="line"> hdferr, creation_prp=creat_plist_id)</div> +<div class="line">or</div> +<div class="line">CALL <a class="code" href="group___f_h5_a.html#gaea165327da713ef670c14ab5b05c61dd">h5acreate_f</a> (dset_id, attr_nam, type_id, space_id, attr_id, hdferr)</div> +<div class="line"> </div> +<div class="line">CALL <a class="code" href="group___f_h5_a.html#ga9bce33031ee37eaf1c6877752e80cebf">h5aclose_f</a> (attr_id, hdferr)</div> +<div class="ttc" id="agroup___f_h5_a_html_ga9bce33031ee37eaf1c6877752e80cebf"><div class="ttname"><a href="group___f_h5_a.html#ga9bce33031ee37eaf1c6877752e80cebf">h5a::h5aclose_f</a></div><div class="ttdeci">subroutine h5aclose_f(attr_id, hdferr)</div><div class="ttdoc">Closes the specified attribute.</div><div class="ttdef"><b>Definition:</b> H5Aff.F90:589</div></div> +<div class="ttc" id="agroup___f_h5_a_html_gaea165327da713ef670c14ab5b05c61dd"><div class="ttname"><a href="group___f_h5_a.html#gaea165327da713ef670c14ab5b05c61dd">h5a::h5acreate_f</a></div><div class="ttdeci">subroutine h5acreate_f(loc_id, name, type_id, space_id, attr_id, hdferr, acpl_id, aapl_id)</div><div class="ttdoc">Creates a dataset as an attribute of a group, dataset, or named datatype.</div><div class="ttdef"><b>Definition:</b> H5Aff.F90:155</div></div> +</div><!-- fragment --><h1><a class="anchor" id="secLBAttrCreateRW"></a> +Reading/Writing an attribute</h1> +<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> +<p>The steps to read or write an attribute are as follows. </p><ol> +<li> +Obtain the attribute identifier. </li> +<li> +Specify the attribute's memory datatype. </li> +<li> +Perform the desired operation. </li> +<li> +Close the memory datatype if necessary. </li> +</ol> +<p>To read and/or write an attribute, the calling program must contain the <a class="el" href="group___h5_a.html#gaacb27a997f7c98e8a833d0fd63b58f1c" title="Reads the value of an attribute.">H5Aread</a> and/or <a class="el" href="group___h5_a.html#gab70871e205d57450c83efd9912be2b5c" title="Writes data to an attribute.">H5Awrite</a> routines. For example:</p> +<p><em>C</em> </p><div class="fragment"><div class="line">status = <a class="code" href="group___h5_a.html#gaacb27a997f7c98e8a833d0fd63b58f1c">H5Aread</a> (attr_id, mem_type_id, buf);</div> +<div class="line">status = <a class="code" href="group___h5_a.html#gab70871e205d57450c83efd9912be2b5c">H5Awrite</a> (attr_id, mem_type_id, buf);</div> +<div class="ttc" id="agroup___h5_a_html_gaacb27a997f7c98e8a833d0fd63b58f1c"><div class="ttname"><a href="group___h5_a.html#gaacb27a997f7c98e8a833d0fd63b58f1c">H5Aread</a></div><div class="ttdeci">herr_t H5Aread(hid_t attr_id, hid_t type_id, void *buf)</div><div class="ttdoc">Reads the value of an attribute.</div></div> +<div class="ttc" id="agroup___h5_a_html_gab70871e205d57450c83efd9912be2b5c"><div class="ttname"><a href="group___h5_a.html#gab70871e205d57450c83efd9912be2b5c">H5Awrite</a></div><div class="ttdeci">herr_t H5Awrite(hid_t attr_id, hid_t type_id, const void *buf)</div><div class="ttdoc">Writes data to an attribute.</div></div> +</div><!-- fragment --><p><em>Fortran</em> </p><div class="fragment"><div class="line">CALL <a class="code" href="group___f_h5_a.html#gac8973363111023ef0f385f7d0a2318e9">h5awrite_f</a> (attr_id, mem_type_id, buf, dims, hdferr) </div> +<div class="line">CALL <a class="code" href="group___f_h5_a.html#ga484f306a1d733ce1c306d405f2c1b7da">h5aread_f</a> (attr_id, mem_type_id, buf, dims, hdferr)</div> +<div class="ttc" id="agroup___f_h5_a_html_ga484f306a1d733ce1c306d405f2c1b7da"><div class="ttname"><a href="group___f_h5_a.html#ga484f306a1d733ce1c306d405f2c1b7da">h5a::h5aread_f</a></div><div class="ttdeci">subroutine h5aread_f(attr_id, memtype_id, buf, hdferr)</div><div class="ttdoc">Reads an attribute.</div><div class="ttdef"><b>Definition:</b> H5Aff.F90:2246</div></div> +<div class="ttc" id="agroup___f_h5_a_html_gac8973363111023ef0f385f7d0a2318e9"><div class="ttname"><a href="group___f_h5_a.html#gac8973363111023ef0f385f7d0a2318e9">h5a::h5awrite_f</a></div><div class="ttdeci">subroutine h5awrite_f(attr_id, memtype_id, buf, hdferr)</div><div class="ttdoc">Writes data to an attribute.</div><div class="ttdef"><b>Definition:</b> H5Aff.F90:2202</div></div> +</div><!-- fragment --><h1><a class="anchor" id="secLBAttrCreateHL"></a> +High Level APIs</h1> +<p>The High Level <a class="el" href="group___h5_l_t.html">HDF5 Lite APIs (H5LT,H5LD)</a> include functions that simplify and condense the steps for creating and reading datasets. Please be sure to review them, in addition to this tutorial.</p> +<h1><a class="anchor" id="secLBAttrCreateRWEx"></a> +Programming Example</h1> +<h2><a class="anchor" id="secLBAttrCreateRWExDesc"></a> +Description</h2> +<p>See <a class="el" href="_l_b_examples.html">Examples from Learning the Basics</a> for the examples used in the <a class="el" href="_learn_basics.html">Learning the Basics</a> tutorial.</p> +<p>The example shows how to create and write a dataset attribute. It opens an existing file <code style="background-color:whitesmoke;">dset.h5</code> in C (<code style="background-color:whitesmoke;">dsetf.h5</code> in FORTRAN), obtains the identifier of the dataset <code style="background-color:whitesmoke;">/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.</p> +<p>For details on compiling an HDF5 application: [ <a class="el" href="_l_b_compiling.html">Compiling HDF5 Applications</a> ]</p> +<h2><a class="anchor" id="secLBAttrCreateRWExRem"></a> +Remarks</h2> +<p><a class="el" href="group___h5_a.html#ga4a76e4e5ab6eb0fd2aa7990d38d55f24">H5Acreate</a> creates an attribute which is attached to the object specified by the first parameter, and returns an identifier.</p> +<p><a class="el" href="group___h5_a.html#gab70871e205d57450c83efd9912be2b5c" title="Writes data to an attribute.">H5Awrite</a> writes the entire attribute, and returns the status of the write.</p> +<p>When an attribute is no longer accessed by a program, <a class="el" href="group___h5_a.html#gaef4394b661e2c930879e9868e122bdda" title="Closes the specified attribute.">H5Aclose</a> must be called to release the attribute from use. An <a class="el" href="group___h5_a.html#gaef4394b661e2c930879e9868e122bdda" title="Closes the specified attribute.">H5Aclose</a>/h5aclose_f call is mandatory.</p> +<h2><a class="anchor" id="secLBAttrCreateRWExCont"></a> +File Contents</h2> +<p>Shown below is the contents and the attribute definition of <code style="background-color:whitesmoke;">dset.h5</code> (created by the C program).</p> +<p><em>dset.h5 in DDL</em> </p><div class="fragment"><div class="line">HDF5 <span class="stringliteral">"dset.h5"</span> {</div> +<div class="line">GROUP <span class="stringliteral">"/"</span> {</div> +<div class="line">DATASET <span class="stringliteral">"dset"</span> {</div> +<div class="line">DATATYPE { <a class="code" href="group___p_d_t_s_t_d.html#ga37e8a6be7ee64587c2a282b965019bb8">H5T_STD_I32BE</a> }</div> +<div class="line">DATASPACE { SIMPLE ( 4, 6 ) / ( 4, 6 ) }</div> +<div class="line">DATA {</div> +<div class="line"> 1, 2, 3, 4, 5, 6,</div> +<div class="line"> 7, 8, 9, 10, 11, 12,</div> +<div class="line"> 13, 14, 15, 16, 17, 18,</div> +<div class="line"> 19, 20, 21, 22, 23, 24</div> +<div class="line">}</div> +<div class="line">ATTRIBUTE <span class="stringliteral">"attr"</span> {</div> +<div class="line"> DATATYPE { <a class="code" href="group___p_d_t_s_t_d.html#ga37e8a6be7ee64587c2a282b965019bb8">H5T_STD_I32BE</a> }</div> +<div class="line"> DATASPACE { SIMPLE ( 2 ) / ( 2 ) }</div> +<div class="line"> DATA {</div> +<div class="line"> 100, 200</div> +<div class="line"> }</div> +<div class="line">}</div> +<div class="line">}</div> +<div class="line">}</div> +<div class="line">}</div> +</div><!-- fragment --><p>Shown below is the contents and the attribute definition of <code style="background-color:whitesmoke;">dsetf.h5</code> (created by the FORTRAN program).</p> +<p><em>dsetf.h5 in DDL</em> </p><div class="fragment"><div class="line">HDF5 <span class="stringliteral">"dsetf.h5"</span> {</div> +<div class="line">GROUP <span class="stringliteral">"/"</span> {</div> +<div class="line">DATASET <span class="stringliteral">"dset"</span> {</div> +<div class="line">DATATYPE { <a class="code" href="group___p_d_t_s_t_d.html#ga37e8a6be7ee64587c2a282b965019bb8">H5T_STD_I32BE</a> }</div> +<div class="line">DATASPACE { SIMPLE ( 6, 4 ) / ( 6, 4 ) }</div> +<div class="line">DATA {</div> +<div class="line"> 1, 7, 13, 19,</div> +<div class="line"> 2, 8, 14, 20,</div> +<div class="line"> 3, 9, 15, 21,</div> +<div class="line"> 4, 10, 16, 22,</div> +<div class="line"> 5, 11, 17, 23,</div> +<div class="line"> 6, 12, 18, 24</div> +<div class="line">}</div> +<div class="line">ATTRIBUTE <span class="stringliteral">"attr"</span> {</div> +<div class="line"> DATATYPE { <a class="code" href="group___p_d_t_s_t_d.html#ga37e8a6be7ee64587c2a282b965019bb8">H5T_STD_I32BE</a> }</div> +<div class="line"> DATASPACE { SIMPLE ( 2 ) / ( 2 ) }</div> +<div class="line"> DATA {</div> +<div class="line"> 100, 200</div> +<div class="line"> }</div> +<div class="line">}</div> +<div class="line">}</div> +<div class="line">}</div> +<div class="line">}</div> +</div><!-- fragment --><h2><a class="anchor" id="secLBAttrCreateRWExDDL"></a> +Attribute Definition in DDL</h2> +<p><em>HDF5 Attribute Definition</em> </p><div class="fragment"><div class="line"><attribute> ::= ATTRIBUTE <span class="stringliteral">"<attr_name>"</span> { <datatype></div> +<div class="line"> <dataspace></div> +<div class="line"> <data> }</div> +</div><!-- fragment --><hr /> +<p> Navigate back: <a class="el" href="index.html">Main</a> / <a class="el" href="_getting_started.html">Getting Started with HDF5</a> / <a class="el" href="_learn_basics.html">Learning the Basics</a> </p> +</div></div><!-- contents --> +</div><!-- PageDoc --> +</div><!-- doc-content --> +<!-- start footer part --> +<div id="nav-path" class="navpath"><!-- id is needed for treeview function! --> + <ul> + <li class="footer">Generated by + <a href="http://www.doxygen.org/index.html"> + <img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.9.1 </li> + </ul> +</div> +</body> +</html> |