[svn-r467] Restructuring documentation.

author: Quincey Koziol <koziol@hdfgroup.org> 1998-07-08 14:54:54 (GMT)
committer: Quincey Koziol <koziol@hdfgroup.org> 1998-07-08 14:54:54 (GMT)
commit: bd1e676c521d881b3143829f493a28b5ced1294b (patch)
tree: 69c50f9fe21ce87f293d8617a6bd51b4cc1e0244 /doc/html/Attributes.html
parent: 73345095897d9698bb1f2f7df830bf80a56dc65a (diff)
download: hdf5-bd1e676c521d881b3143829f493a28b5ced1294b.zip
hdf5-bd1e676c521d881b3143829f493a28b5ced1294b.tar.gz
hdf5-bd1e676c521d881b3143829f493a28b5ced1294b.tar.bz2
1 files changed, 177 insertions, 0 deletions
diff --git a/doc/html/Attributes.html b/doc/html/Attributes.html
new file mode 100644
index 0000000..85fe70f
--- /dev/null
+++ b/doc/html/Attributes.html
@@ -0,0 +1,177 @@
+<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
+<html>
+  <head>
+    <title>Attributes</title>
+  </head>
+
+  <body>
+    <h1>Attributes</h1>
+
+    <h2>1. Introduction</h2>
+
+    <p>The appribute API (H5A) is primarily designed to easily allow small
+        datasets to be attached to primary datasets as metadata information.
+        Additional goals for the H5A interface include keeping storage
+        requirement for each attribute to a minimum and easily sharing
+        attributes among datasets.
+    <p>Because attributes are intended to be small objects, large datasets
+        intended as additional information for a primary dataset should be
+        stored as supplemental datasets in a group with the primary dataset.
+        Attributes can then be attached to the group containing everything to
+        indicate a particular type of dataset with supplemental datasets is
+        located in the group.  How small is "small" is not defined by the
+        library and is up to the user's interpretation.
+    <p>Attributes are not seperate objects in the file, they are always
+        contained in the object header of the object they are attached to.  The
+        I/O functions defined below are required to read or write attribute
+        information, not the H5D I/O routines.
+
+    <h2>2. Creating, Opening, Closing and Deleting Attributes</h2>
+
+    <p>Attributes are created with the <code>H5Acreate()</code> function,
+      and existing attributes can be accessed with either the
+      <code>H5Aopen_name()</code> or <code>H5Aopen_idx()</code> functions. All
+      three functions return an object ID which should be eventually released
+      by calling <code>H5Aclose()</code>.
+
+    <dl>
+      <dt><code>hid_t H5Acreate (hid_t <em>loc_id</em>, const char
+	  *<em>name</em>, hid_t <em>type_id</em>, hid_t <em>space_id</em>,
+	  hid_t <em>create_plist_id</em>)</code>
+        <dd>This function creates an attribute which is attached to the object
+    specified with <em>loc_id</em>.  The name specified with <em>name</em>
+    for each attribute for an object must be unique for that object.  The <em>type_id</em>
+    and <em>space_id</em> are created with the H5T and H5S interfaces
+    respectively.  Currently only simple dataspaces are allowed for attribute
+    dataspaces.  The <em>create_plist_id</em> property list is currently
+    unused, but will be used int the future for optional properties of
+    attributes.  The attribute ID returned from this function must be released
+    with H5Aclose or resource leaks will develop.  Attempting to create an
+    attribute with the same name as an already existing attribute will fail,
+    leaving the pre-existing attribute in place.
+    This function returns a attribute ID for success or negative for failure.
+
+	<br><br>
+      <dt><code>hid_t H5Aopen_name (hid_t <em>loc_id</em>, const char
+	  *<em>name</em>)</code>
+      <dd> This function opens an attribute which is attached to the object
+    specified with <em>loc_id</em>.  The name specified with <em>name</em>
+    indicates the attribute to access.  The attribute ID returned from this
+    function must be released with H5Aclose or resource leaks will develop.
+    This function returns a attribute ID for success or negative for failure.
+
+	<br><br>
+      <dt><code>hid_t H5Aopen_idx (hid_t <em>loc_id</em>, unsigned
+	  <em>idx</em>)</code>
+      <dd>This function opens an attribute which is attached to the object
+    specified with <em>loc_id</em>.  The attribute specified with <em>idx</em>
+    indicates the <em>idx</em>th attribute to access, starting with '0'. The
+    attribute ID returned from this function must be released with H5Aclose or
+    resource leaks will develop.
+    This function returns a attribute ID for success or negative for failure.
+
+	<br><br>
+      <dt><code>herr_t H5Aclose (hid_t <em>attr_id</em>)</code>
+      <dd>This function releases an attribute from use.  Further use of the
+    attribute ID will result in undefined behavior.
+    This function returns non-negative on success, negative on failure.
+
+	<br><br>
+      <dt><code>herr_t H5Adelete (hid_t <em>loc_id</em>, 
+        const char *<em>name</em>)</code>
+      <dd>This function removes the named attribute from a dataset or group.
+    This function should not be used when attribute IDs are open on <em>loc_id</em>
+    as it may cause the internal indexes of the attributes to change and future 
+    writes to the open attributes to produce incorrect results.
+    Returns non-negative on success, negative on failure.
+    </dl>
+
+    <h2>3. Attribute I/O Functions</h2>
+
+    <p>Attributes may only be written as an entire object, no partial I/O
+        is currently supported.
+
+    <dl>
+      <dt><code>herr_t H5Awrite (hid_t <em>attr_id</em>,
+      hid_t <em>mem_type_id</em>, void *<em>buf</em>)</code>
+      <dd>This function writes an attribute, specified with <em>attr_id</em>,
+    with <em>mem_type_id</em> specifying the datatype in memory.  The entire
+    attribute is written from <em>buf</em> to the file.
+    This function returns non-negative on success, negative on failure.
+
+	<br><br>
+      <dt><code>herr_t H5Aread (hid_t <em>attr_id</em>,
+      hid_t <em>mem_type_id</em>, void *<em>buf</em>)</code>
+      <dd>This function read an attribute, specified with <em>attr_id</em>, with
+    <em>mem_type_id</em> specifying the datatype in memory.  The entire
+    attribute is read into <em>buf</em> from the file.
+    This function returns non-negative on success, negative on failure.
+
+    </dl>
+
+    <h2>4. Attribute Inquiry Functions</h2>
+
+    <dl>
+      <dt><code>int H5Aiterate (hid_t <em>loc_id</em>, 
+      unsigned *<em>attr_number</em>, 
+      H5A_operator <em>operator</em>, 
+	  void *<em>operator_data</em>)</code>
+      <dd> This function interates over the attributes of dataset or group
+    specified with <em>loc_id</em>.  For each attribute of the object, the
+    <em>operator_data</em> and some additional information (specified below)
+    are passed to the <em>operator</em> function.  The iteration begins with
+    the <em>*attr_number</em> object in the group and the next attribute to be
+    processed by the operator is returned in <em>*attr_number</em>.
+        <P>The iterator returns a negative value if something is wrong, the return
+    value of the last operator if it was non-zero, or zero if all attributes
+    were processed.
+        <P>The prototype for H5A_operator_t is: <br>
+            <code>typedef herr_t (*H5A_operator_t)(hid_t <em>loc_id</em>,
+                const char *<em>attr_name</em>, void *<em>operator_data</em>);</code>
+    <P>The operation receives the ID for the group or dataset being iterated over
+    (<em>loc_id</em>), the name of the current attribute about the object (<em>attr_name</em>)
+    and the pointer to the operator data passed in to H5Aiterate
+    (<em>operator_data</em>).  The return values from an operator are:
+        <ul>
+        <li>Zero causes the iterator to continue, returning zero when all 
+            attributes have been processed.
+        <li>Positive causes the iterator to immediately return that positive
+            value, indicating short-circuit success.  The iterator can be
+            restarted at the next attribute.
+        <li>Negative causes the iterator to immediately return that value,
+            indicating failure.  The iterator can be restarted at the next
+            attribute.
+        </ul>
+	<br><br>
+      <dt><code>hid_t H5Aget_space (hid_t <em>attr_id</em>)</code>
+      <dd>This function retrieves a copy of the dataspace for an attribute.
+    The dataspace ID returned from this function must be released with H5Sclose
+    or resource leaks will develop.
+    This function returns a dataspace ID for success or negative for failure.
+	<br><br>
+      <dt><code>hid_t H5Aget_type (hid_t <em>attr_id</em>)</code>
+      <dd>This function retrieves a copy of the datatype for an attribute.
+    The datatype ID returned from this function must be released with H5Tclose
+    or resource leaks will develop.
+    This function returns a datatype ID for success or negative for failure.
+	<br><br>
+      <dt><code>size_t H5Aget_name (hid_t <em>attr_id</em>,
+          char *<em>buf</em>, size_t <em>buf_size</em>)</code>
+      <dd>This function retrieves the name of an attribute for an attribute ID.
+    Up to <em>buf_size</em> characters are stored in <em>buf</em> followed by a
+    '\0' string terminator.  If the name of the attribute is longer than
+    <em>buf_size</em>-1, the string terminator is stored in the last position
+    of the buffer to properly terminate the string.
+    This function returns the length of the attribute's name (which may be
+    longer than <em>buf_size</em>) on success or negative for failure.
+	<br><br>
+      <dt><code>int H5Anum_attrs (hid_t <em>loc_id</em>)</code>
+      <dd>This function returns the number of attributes attached to a dataset or
+    group, <em>loc_id</em>.
+    This function returns non-negative for success or negative for failure.
+    </dl>
+
+    <hr>
+    <address><a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Support</a></address>
+  </body>
+</html>
author	Quincey Koziol <koziol@hdfgroup.org>	1998-07-08 14:54:54 (GMT)
committer	Quincey Koziol <koziol@hdfgroup.org>	1998-07-08 14:54:54 (GMT)
commit	bd1e676c521d881b3143829f493a28b5ced1294b (patch)
tree	69c50f9fe21ce87f293d8617a6bd51b4cc1e0244 /doc/html/Attributes.html
parent	73345095897d9698bb1f2f7df830bf80a56dc65a (diff)
download	hdf5-bd1e676c521d881b3143829f493a28b5ced1294b.zip hdf5-bd1e676c521d881b3143829f493a28b5ced1294b.tar.gz hdf5-bd1e676c521d881b3143829f493a28b5ced1294b.tar.bz2