diff options
Diffstat (limited to 'doc/html/Attributes.html')
| -rw-r--r-- | doc/html/Attributes.html | 177 |
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> |