diff options
| author | Elena Pourmal <epourmal@hdfgroup.org> | 1998-07-08 22:28:21 (GMT) |
|---|---|---|
| committer | Elena Pourmal <epourmal@hdfgroup.org> | 1998-07-08 22:28:21 (GMT) |
| commit | 49f626b81f028a09d5c287156120a5d405008335 (patch) | |
| tree | ee0178875371da97373cb5c08a2fa7a276f94ccd /doc/src/RM_H5G.html | |
| parent | 2f1f2ac4e44efef28ac7b7edaf4f9470b866c9fc (diff) | |
| download | hdf5-49f626b81f028a09d5c287156120a5d405008335.zip hdf5-49f626b81f028a09d5c287156120a5d405008335.tar.gz hdf5-49f626b81f028a09d5c287156120a5d405008335.tar.bz2 | |
[svn-r475] HDF5 Reference Manual files.
Main file is RM_H5Front.html. Created from the Alpha1 Ref. Manual, Alpha1
User's Guide Documents and the Alpha2 Source Code.
Diffstat (limited to 'doc/src/RM_H5G.html')
| -rw-r--r-- | doc/src/RM_H5G.html | 882 |
1 files changed, 882 insertions, 0 deletions
diff --git a/doc/src/RM_H5G.html b/doc/src/RM_H5G.html new file mode 100644 index 0000000..b4baa99 --- /dev/null +++ b/doc/src/RM_H5G.html @@ -0,0 +1,882 @@ +<html> +<head><title> +HDF5/H5G Draft API Specification +</title></head> + +<body> + +<center> +<h1>H5G: Group Interface</h1> +</center> + +<h2>Group Object API Functions</h2> + +The Group interface functions create and manipulate physical groups +of objects on disk. + +<table border=0> +<tr><td valign=top> +<ul> + <li><a href="#Group-Create">H5Gcreate</a> + <li><a href="#Group-Open">H5Gopen</a> + <li><a href="#Group-Set">H5Gset</a> + <li><a href="#Group-Close">H5Gclose</a> +</ul> +</td><td> </td><td valign=top> +<ul> + <li><a href="#Group-Push">H5Gpush</a> + <li><a href="#Group-Pop">H5Gpop</a> + <li><a href="#Group-Link">H5Glink</a> + <li><a href="#Group-Unlink">H5Gunlink</a> (NYI) +</ul> +</td><td> </td><td valign=top> +<ul> + <li><a href="#Group-Iterate">H5Giterate</a> + <li><a href="#Group-Move">H5Gmove</a> (NYI) + <li><a href="#Group-Stat">H5Gstat</a> + <li><a href="#Group-GetLinkval">H5Gget_linkval</a> +</ul> +</td></tr><tr><td colspan=5 align=right> +<font size=-2>(NYI = Not yet implemented)</font> +</td></tr> +</table> + +<p> +A group associates names with objects and provides a mechanism +for mapping a name to an object. Since all objects appear in at +least one group (with the possible exception of the root object) +and since objects can have names in more than one group, the set +of all objects in an HDF5 file is a directed graph. The internal +nodes (nodes with out-degree greater than zero) must be groups +while the leaf nodes (nodes with out-degree zero) are either empty +groups or objects of some other type. Exactly one object in every +non-empty file is the root object. The root object always has a +positive in-degree because it is pointed to by the file boot block. + +<p> +Every file identifier returned by <code>H5Fcreate</code> or +<code>H5Fopen</code> maintains an independent current working group +stack, the top item of which is the current working group. The +stack can be manipulated with <code>H5Gset</code>, <code>H5Gpush</code>, +and <code>H5Gpop</code>. The root object is the current working group +if the stack is empty. + +<p> +An object name consists of one or more components separated from +one another by slashes. An absolute name begins with a slash and the +object is located by looking for the first component in the root +object, then looking for the second component in the first object, etc., +until the entire name is traversed. A relative name does not begin +with a slash and the traversal begins with the current working group. + +<p> +The library does not maintain the full absolute name of its current +working group because (1) cycles in the graph can make the name length +unbounded and (2) a group does not necessarily have a unique name. A +more Unix-like hierarchical naming scheme can be implemented on top of +the directed graph scheme by creating a ".." entry in each group that +points to its single predecessor; a <code>getcwd</code> function would +then be trivial. + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Group-Create">H5Gcreate</a> + <dt><strong>Signature:</strong> + <dd><em>hid_t </em><code>H5Gcreate</code>(<em>hid_t</em> <code>loc_id</code>, + <em>const char *</em><code>name</code>, + <em>size_t</em> <code>size_hint</code> + ) + <dt><strong>Purpose:</strong> + <dd>Creates a new empty group and gives it a name. + <dt><strong>Description:</strong> + <dd><code>H5Gcreate</code> creates a new group with the specified + name at the specified location, <code>loc_id</code>. + The location is identified by a file or group identifier. + The name, <code>name</code>, must not already be taken by some + other object and all parent groups must already exist. + <p> + <code>size_hint</code> is a hint for the number of bytes to + reserve to store the names which will be eventually added to + the new group. Passing a value of zero for <code>size_hint</code> + is usually adequate since the library is able to dynamically + resize the name heap, but a correct hint may result in better + performance. + If a non-positive value is supplied for size_hint, + then a default size is chosen. + <p> + The return value is a group identifier for the open group. + This group identifier should be closed by calling + <code>H5Gclose()</code> when it is no longer needed. + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>loc_id</code> + <dd>The file or group identifier. + <dt><em>const char *</em><code>name</code> + <dd>The absolute or relative name of the new group. + <dt><em>size_t</em> <code>size_hint</code> + <dd>An optional parameter indicating the number of bytes + to reserve for the names that will appear in the group. + A conservative estimate could result in multiple + system-level I/O requests to read the group name heap; + a liberal estimate could result in a single large + I/O request even when the group has just a few names. + HDF5 stores each name with a null terminator. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns a valid group identifier for the open group if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Group-Open">H5Gopen</a> + <dt><strong>Signature:</strong> + <dd><em>hid_t </em><code>H5Gopen</code>(<em>hid_t</em> <code>loc_id</code>, + <em>const char *</em><code>name</code> + ) + <dt><strong>Purpose:</strong> + <dd>Opens an existing group for modification and returns a group + identifier for that group. + <dt><strong>Description:</strong> + <dd><code>H5Gopen</code> opens an existing group with the specified name at + the specified location, <code>loc_id</code>. + The location is identified by a file or + group identifier, and returns a group identifier for the group. + The obtained group identifier should be released by calling + <code>H5Gclose()</code> when it is no longer needed. + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>loc_id</code> + <dd>File or group identifier within which group is to be open. + <dt><em>const char *</em> <code>name</code> + <dd>Name of group to open. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns a valid group identifier if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Group-Set">H5Gset</a> + <dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Gset</code> (<em>hid_t</em> <code>loc_id</code>, + <em>const char *</em><code>name</code> + ) + <dt><strong>Purpose:</strong> + <dd>Sets the current working group within a file. + <dt><strong>Description:</strong> + <dd><code>H5Gset</code> sets the group with the specified name + to be the current working group for the file which contains it. + This function sets the current working group by modifying the + top element of the current working group stack or, if the + stack is empty, by pushing a new element onto the stack. + The initial current working group is the root group. + <p> + <code>loc_id</code> can be a file identifier or a group identifier. + <p> + <code>name</code> is an absolute or relative name and is resolved as follows. Each file identifier + has a current working group, initially the root group of the + file. Relative names do not begin with a slash and are relative + to the specified group or to the current working group. + Absolute names begin with a slash and are relative to the file's + root group. For instance, the name <code>/Foo/Bar/Baz</code> is + resolved by first looking up <code>Foo</code> in the root group; + the name <code>Foo/Bar/Baz</code> is resolved by first looking + up the name <code>Foo</code> in the current working group. + <p> + Each file identifier maintains its own notion of the current + working group. If <code>loc_id</code> is a group identifier, the + file identifier is derived from the group identifier. + <p> + If a single file is opened with multiple calls to <code>H5Fopen()</code>, + which would return multiple file identifiers, then each + identifier's current working group can be set independently + of the other file identifiers for that file. + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>loc_id</code> + <dd>The file or group identifier. + <dt><em>const char *</em><code>name</code> + <dd>The name of the new current working group. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Group-Push">H5Gpush</a> + <dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Gpush</code> (<em>hid_t</em> <code>loc_id</code>, + <em>const char *</em><code>name</code> + ) + <dt><strong>Purpose:</strong> + <dd>Sets the current working group by pushing a + new element onto the current working group stack. + <dt><strong>Description:</strong> + <dd>Each file identifier maintains a stack of groups, the top group + of which is the current working group. The stack initially + contains only the root group. <code>H5Gpush</code> pushes a new group + onto the stack, thus setting a new current working group. + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>loc_id</code> + <dd>File or group identifier. + <dt><em>const char *</em><code>name</code> + <dd>The name of the new current working group. The name may be + an absolute or relative name. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Group-Pop">H5Gpop</a> + <dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Gpop</code> (<em>hid_t</em> <code>loc_id</code>) + <dt><strong>Purpose:</strong> + <dd>Removes the top, or latest, entry from the working group stack, + setting the current working group to the previous value. + <dt><strong>Description:</strong> + <dd><code>H5Gpop</code> restores the previous current working group by + popping an element from the current working group stack. + An empty stack implies that the current working group is the root + object. Attempting to pop an empty stack results in failure. + <p> + Each file identfier maintains its own notion of the current + working group. That is, if a single file is opened with + multiple calls to <code>H5Fopen()</code>, which returns multiple file + handles, then each identfier's current working group can be + set independently of the other file identfiers for that file. + <p> + If <code>loc_id</code> is a group identifier, it is used only to determine the + file identifier for the stack from which to pop the top entry. + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>loc_id</code> + <dd>The file or group identifier. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Group-Close">H5Gclose</a> + <dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Gclose</code>(<em>hid_t </em><code>group_id</code>) + <dt><strong>Purpose:</strong> + <dd>Closes the specified group. + <dt><strong>Description:</strong> + <dd><code>H5Gclose</code> releases resources used by a group which was + opened by <code>H5Gcreate()</code> or <code>H5Gopen()</code>. + After closing a group, the <code>group_id</code> cannot be used again. + <p> + Failure to release a group with this call will result in resource leaks. + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>group_id</code> + <dd>Group identifier to release. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Group-Link">H5Glink</a> + <dt><strong>Signature:</strong> + <dd><em>herr_t</em> <code>H5Glink</code>(<em>hid_t</em> <code>loc_id</code>, + <em>H5G_link_t</em> <code>link_type</code>, + <em>const char *</em><code>current_name</code>, + <em>const char *</em><code>new_name</code> + ) + <dt><strong>Purpose:</strong> + <dd>Creates a link of the specified type from <code>new_name</code> + to <code>current_name</code>. + <dt><strong>Description:</strong> + <dd><code>H5Glink</code> creates a new name for an object that has some current + name, possibly one of many names it currently has. + <p> + If <code>link_type</code> is <code>H5G_LINK_HARD</code>, then + <code>current_name</code> must name an existing object and both + names are interpreted relative to <code>loc_id</code>, which is + either a file identifier or a group identifier. + <p> + If <code>link_type</code> is <code>H5G_LINK_SOFT</code>, then + <code>current_name</code> can be anything and is interpreted at + lookup time relative to the group which contains the final + component of <code>new_name</code>. For instance, if + <code>current_name</code> is <code>./foo</code>, + <code>new_name</code> is <code>./x/y/bar</code>, and a request + is made for <code>./x/y/bar</code>, then the actual object looked + up is <code>./x/y/./foo</code>. + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>loc_id</code> + <dd>File or group identifier. + <dt><em>H5G_link_t</em> <code>link_type</code> + <dd>Link type. + Possible values are <code>H5G_LINK_HARD</code> and <code>H5G_LINK_SOFT</code>. + <dt><em>const char *</em> <code>current_name</code> + <dd>Name of the existing object if link is a hard link. + Can be anything for the soft link. + <dt><em>const char *</em> <code>new_name</code> + <dd>New name for the object. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Group-Unlink">H5Gunlink</a> + + <strong>(Not implemented in this release.)</strong> + <dt><strong>Signature:</strong> + <dd><em>herr_t </em><code>H5Gunlink</code>(<em>hid_t</em> <code>loc_id</code>, + <em>const char *</em><code>name</code> + ) + <dt><strong>Purpose:</strong> + <dd>Removes the specified <code>name</code> from the group graph and + decrements the link count for the object to which <code>name</code> points + <dt><strong>Description:</strong> + <dd><code>H5Gunlink</code> removes an association between a name and an object. + Object headers keep track of how many hard links refer to the object; + when the hard link count reaches zero, the object can be removed + from the file. Objects which are open are not removed until all + identifiers to the object are closed. + <p> + If the link count reaches zero, all file-space associated with + the object will be reclaimed. If the object is open, the + reclamation of the file space is delayed until all handles to the + object are closed. + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>loc_id</code> + <dd>Identifier of the file containing the object. + <dt><em>const char *</em> <code>name</code> + <dd>Name of the object to unlink. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Group-Iterate">H5Giterate</a> + <dt><strong>Signature:</strong> + <dd><em>int</em> <code>H5Giterate</code>(<em>hid_t</em> <code>loc_id</code>, + <em>const char</em> <code>*name</code>, + <em>int</em> <code>*idx</code>, + <em>H5G_operator_t</em> <code>operator</code>, + <em>void</em> <code>*operator_data</code> + ) + <dt><strong>Purpose:</strong> + <dd>Iterates an operation over the entries of a group. + <dt><strong>Description:</strong> + <dd><code>H5Giterate</code> iterates over the members of + <code>name</code> in the file or group specified with + <code>loc_id</code>. + For each object in the group, the <code>operator_data</code> + and some additional information, specified below, are + passed to the <code>operator</code> function. + The iteration begins with the <code>idx</code> object in the + group and the next element to be processed by the operator is + returned in <code>idx</code>. If <code>idx</code> + is NULL, then the iterator starts at the first group member; + since no stopping point is returned in this case, the iterator + cannot be restarted if one of the calls to its operator returns + non-zero. + <p> + The prototype for <code>H5G_operator_t</code> is: + <ul><dl> + <dd><code>typedef</code> <em>herr_t *</em>(<code>H5G_operator_t</code>)(<em>hid_t</em> <code>group_id</code>, + <em>const char *</em><code>member_name</code>, <em>void *</em><code>operator_data/*in,out*/</code>); + </dl></ul> + <dd>The operation receives the group identifier for the group being + iterated over, <code>group_id</code>, the name of the current + object within the group, <code>member_name</code>, and the + pointer to the operator data passed in to <code>H5Giterate</code>, + <code>operator_data</code>. + <p> + The return values from an operator are: + <ul> + <li>Zero causes the iterator to continue, returning + zero when all group members 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 group member. + <li>Negative causes the iterator to immediately return that value, + indicating failure. The iterator can be restarted at the next + group member. + </ul> + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>loc_id</code> + <dd>IN: File or group identifier. + <dt><em>const char</em> <code>*name</code> + <dd>IN: Group over which the iteration is performed. + <dt><em>int</em> <code>*idx</code> + <dd>IN/OUT: Location at which to begin the iteration. + <dt><em>H5G_iterate_t</em> <code>operator</code> + <dd>IN: Operation to be performed on an object at each step of + the iteration. + <dt><em>void</em> <code>*operator_data</code> + <dd>IN/OUT: Data associated with the operation. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns the return value of the last operator if it was non-zero, + or zero if all group members were processed. + Otherwise, returns FAIL (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Group-Move">H5Gmove</a> + + <strong>(Not implemented in this release.)</strong> + <dt><strong>Signature:</strong> + <dd><em>herr_t</em> <code>H5Gmove</code>(<em>hid_t</em> <code>loc_id</code>, + <em>const char</em> <code>*src</code>, + <em>const char</em> <code>*dst</code> + ) + <dt><strong>Purpose:</strong> + <dd>Renames an object within an HDF5 file. + <dt><strong>Description:</strong> + <dd><code>H5Gmove</code> renames an object within an HDF5 file. + The original name, <code>src</code>, is unlinked from the + group graph and the new name, <code>dst</code>, is inserted + as an atomic operation. Both names are interpreted relative + to <code>loc_id</code>, which is either a file or a group + identifier. + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>loc_id</code> + <dd>File or group identifier. + <dt><em>const char</em> <code>*src</code> + <dd>Object's original name. + <dt><em>const char</em> <code>*dst</code> + <dd>Object's new name. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0) if successful; + otherwise FAIL (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Group-Stat">H5Gstat</a> + <dt><strong>Signature:</strong> + <dd><em>herr_t</em> <code>H5Gstat</code>(<em>hid_t</em> <code>loc_id</code>, + <em>const char *</em><code>name</code>, + <em>hbool_t</em> <code>follow_link</code>, + <em>H5G_stat_t *</em><code>statbuf</code> + ) + <dt><strong>Purpose:</strong> + <dd>Returns information about an object. + <dt><strong>Description:</strong> + <dd><code>H5Gstat</code> returns information about the + specified object through the <code>statbuf</code> argument. + <code>loc_id</code> (a file, group, or dataset identifier) and + <code>name</code> together determine the object. + If the object is a symbolic link and <code>follow_link</code> is + zero (<code>0</code>), then the information returned is that for the link itself; + otherwise the link is followed and information is returned about + the object to which the link points. + If <code>follow_link</code> is non-zero but the final symbolic link + is dangling (does not point to anything), then an error is returned. + The <code>statbuf</code> fields are undefined for an error. + The existence of an object can be tested by calling this function + with a null <code>statbuf</code>. + <p> + <code>H5Gstat()</code> fills in the following data structure: + <pre> + typedef struct H5G_stat_t { + unsigned long fileno[2]; + unsigned long objno[2]; + unsigned nlink; + H5G_type_t type; + size_t linklen; + } H5G_stat_t + </pre> + The <code>fileno</code> and <code>objno</code> fields contain + four values which uniquely itentify an object among those + HDF5 files which are open: if all four values are the same + between two objects, then the two objects are the same + (provided both files are still open). + The <code>nlink</code> field is the number of hard links to + the object or zero when information is being returned about a + symbolic link (symbolic links do not have hard links but + all other objects always have at least one). + The <code>type</code> field contains the type of the object, + one of <code>H5G_GROUP</code>, <code>H5G_DATASET</code>, + or <code>H5G_LINK</code>. + If information is being returned about a symbolic link then + <code>linklen</code> will be the length of the link value + (the name of the pointed-to object with the null terminator); + otherwise <code>linklen</code> will be zero. + Other fields may be added to this structure in the future. + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>loc_id</code> + <dd>IN: File, group, or dataset identifier. + <dt><em>const char</em> <code>*name</code> + <dd>IN: Name of the object for which status is being sought. + <dt><em>hbool_t</em> <code>follow_link</code> + <dd>IN: Link flag. + <dt><em>H5G_stat_t</em> <code>*statbuf</code> + <dd>OUT: Buffer in which to return information about the object. + </dl> + <dt><strong>Returns:</strong> + <dd> Returns SUCCEED (0) with the fields of STATBUF (if non-null) initialized. + Otherwise returns FAIL (-1). +</dl> + + +<hr> +<dl> + <dt><strong>Name:</strong> <a name="Group-GetLinkval">H5Gget_linkval</a> + <dt><strong>Signature:</strong> + <dd><em>herr_t</em> <code>H5Gget_linkval</code>(<em>hid_t</em> <code>loc_id</code>, + <em>const char *</em><code>name</code>, + <em>size_t</em> <code>size</code>, + <em>char *</em><code>value</code> + ) + <dt><strong>Purpose:</strong> + <dd>Returns link value. + <dt><strong>Description:</strong> + <dd><code>H5Gget_linkval</code> returns <code>size</code> + characters of the link value through the <code>value</code> + argument if <code>loc_id</code> (a file or group identifier) + and <code>name</code> specify a symbolic link. + If <code>size</code> is smaller than the link value, then + <code>value</code> will not be null terminated. + <p> + This function fails if the specified object is not a symbolic link. + The presence of a symbolic link can be tested by passing zero for + <code>size</code> and NULL for <code>value</code>. + <p> + Use <code>H5Gstat()</code> to get the size of a link value. + <dt><strong>Parameters:</strong> + <dl> + <dt><em>hid_t</em> <code>loc_id</code> + <dd>IN: Identifier of the file or group . + <dt><em>const char *</em><code>name</code> + <dd>IN: Name of the object whose link value is to be checked. + <dt><em>size_t</em> <code>size</code> + <dd>IN: Maximum number of characters of <code>value</code> + to be returned. + <dt><em>char *</em><code>value</code> + <dd>OUT: Link value. + </dl> + <dt><strong>Returns:</strong> + <dd>Returns SUCCEED (0), with the link value in <code>value</code>, + if successful. + Otherwise returns FAIL (-1). +</dl> + + +<hr> +<hr> +</b>UNUSED PORTIONS OF EMAIL NOTES.</b> +<br> +<code>....</code> in left margin indicates where material was pulled out for use. +<HR> +<HR> +<pre> + +Hi Elena, here's a hodgepodge of stuff from html documents and +previous e-mails to answer your questions. Let me know if you need +further clarification. + +.... +.... [H5Gmove and H5Gunlink "NYI" comments were here] +.... + +Elena> We need little bit more user-friendly description of the H5Gstat and +Elena> H5Giterate functions. + +>From a Mar 31 e-mail... + +Robb> +.... +.... [H5Giterate was here] +.... +Robb> +Robb> +Robb> Group Information Functions: +.... +.... [H5Gstat was here] +.... +Robb> +Robb> herr_t H5Gname(hid_t group_id, char *name, size_t max_name_len); +Robb> +Robb> This function retrieves the name of the group for a group ID. The +Robb> name is returned in 'name' up to the length specified in 'max_name_len'. +Robb> +.... +.... [H5Gget_linkval was here] +.... +Robb> +Robb> H5Giterate example #1: The operator just looks at the member name and if it has an +Robb> `X' in it then it returns 1, otherwise return zero. Returning 1 (or any +Robb> positive value) causes the iterator to immediately return that value. If +Robb> none of the operators return 1 then the iterator eventually returns zero. +Robb> +Robb> 1 herr_t +Robb> 2 any_X (hid_t group_id/*unused*/, +Robb> 4 const char *member_name, +Robb> 5 void *op_data/*unused*/) +Robb> 6 { +Robb> 7 return strchr(member_name,'X') ? 1 : 0; +Robb> 8 } +Robb> +Robb> The iterator is invoked as: +Robb> +Robb> 9 int elmt=0; +Robb> 10 herr_t found = H5Giterate(file_id, "/foo", &elmt, any_X, NULL); +Robb> 11 +Robb> 12 if (found<0) { +Robb> 13 printf ("Error iterating through group, at member %d\n", elmt); +Robb> 14 } else if (found) { +Robb> 15 printf ("Yes, member %d has an `X' in the name\n", elmt); +Robb> 16 } else { +Robb> 17 printf ("No member name contains an `X'\n"); +Robb> 18 } +Robb> +Robb> H5Giterate example #2: An iterator to find an object whose name contains an `X' +Robb> This is the same as Example 1 except the operator also returns the name +Robb> that contains the `X'. We do this by passing a pointer to a `char*' as the +Robb> operator data and the operator will initialize that `char*' by strdup'ing +Robb> the object name. +Robb> +Robb> 1 herr_t +Robb> 2 find_X (hid_t group_id/*unused*/, +Robb> 4 const char *member_name, +Robb> 5 void *op_data/*out*/) +Robb> 6 { +Robb> 7 if (strchr(member_name,'X')) { +Robb> 8 *((char**)op_data) = strdup(member_name); +Robb> 9 return 1; +Robb> 10 } +Robb> 11 return 0; +Robb> 12 } +Robb> +Robb> To print all the names with an `X' the iterator is invoked +Robb> repeatedly until it returns zero. +Robb> +Robb> 13 int elmt = 0; +Robb> 14 char *name; +Robb> 15 while (H5Giterate(file_id, "/foo", &elmt, find_X, &name)) { +Robb> 16 puts (name); +Robb> 17 free (name); +Robb> 18 } +Robb> +Robb> H5Giterate example #3: Print all names that contain the specified character. +Robb> This is the same as Example 2 except we have to pass data into the operator +Robb> as well as get data out. We create a struct that contains the input data +Robb> (character to look for) and a slot for the output data (the name) and pass +Robb> that as the operator data. +Robb> +Robb> 1 typedef struct { +Robb> 2 char look_for; +Robb> 3 char *name; +Robb> 4 } find_char_t; +Robb> 5 +Robb> 6 herr_t +Robb> 7 find_char (hid_t group_id/*unused*/, +Robb> 9 const char *member_name, +Robb> 10 find_char_t *op_data/*in,out*/) +Robb> 11 { +Robb> 13 if (strchr(member_name, op_data->look_for)) { +Robb> 14 op_data->name = strdup (member_name); +Robb> 15 return 1; +Robb> 16 } +Robb> 17 return 0; +Robb> 18 } +Robb> +Robb> To print all names that have a `Y' one would say +Robb> +Robb> 19 find_char_t op_data; +Robb> 20 int elmt = 0; +Robb> 21 op_data->look_for = 'Y'; +Robb> 22 while (H5Giterate(file_id, "/foo", &elmt, find_X, &op_data)) { +Robb> 23 puts (op_data->name); +Robb> 24 free (op_data->name); +Robb> 25 } +Robb> +Robb> H5Giterate example #4: Efficient version of Example 3. +Robb> Examples 2 and 3 weren't too efficient because we kept interrupting the +Robb> iterator and it had to start over, albeit from the middle of the search. If +Robb> we could allow the iterator to go further then we wouldn't end up scanning +Robb> through the leaf nodes of the symbol table so often (searching for a +Robb> particular index, n, in a B-tree is an O(n) operation). +Robb> The H5Glist() function defined earlier returns the names of all the group +Robb> members which belong to a certain class, H5G_ALL, H5G_DATASET, or H5G_GROUP. +Robb> This example shows how to implement that functionality. +Robb> First we need a struct to describe the operator data and it's return +Robb> value(s). These correspond to the arguments presented for H5Glist, whose +Robb> definition is at the end of this example. (Since most of the work is done by +Robb> the operator we have to pass all this stuff back and forth through the +Robb> iterator). +Robb> +Robb> 1 typedef struct { +Robb> 2 size_t name_heap_size; +Robb> 3 char *name_heap; +Robb> 4 unsigned max_entries; +Robb> 5 char *names[]; +Robb> 6 int type; +Robb> 7 unsigned cur_entries; /* How many names read so far */ +Robb> 8 size_t cur_heap_size; /* How large is the heap */ +Robb> 9 } H5G_list_t; +Robb> +Robb> The operator checks if an object is the right type, and if so adds it to +Robb> the return value arrays in the op_data struct. If the arrays become full +Robb> then the operator returns 1 to stop the iterator. The H5*isa() functions +Robb> return true iff the named object is of the * type (sans error handling). +Robb> +Robb> 10 herr_t +Robb> 11 H5G_list_op (hid_t grp_id, const char *memb_name, +Robb> 12 H5G_list_t *op_data) +Robb> 13 { +Robb> 14 char *out_name; +Robb> 15 +Robb> 16 if (H5G_ALL==op_data->type || +Robb> 17 (H5G_DATASET==op_data->type && H5Disa(grp_id,memb_name)) || +Robb> 18 (H5G_GROUP==op_data->type && H5Gisa(grp_id, memb_name))) { +Robb> 19 +Robb> 20 /* Is there enough room for the name in the heap? */ +Robb> 21 if (op_data->cur_heap_size + strlen(memb_name) + 1 > +Robb> 22 op_data->name_heap_size) { +Robb> 23 return 2; /*try again later, see lines 59-62*/ +Robb> 24 } +Robb> 25 +Robb> 26 /* Add name to op_data return value arrays */ +Robb> 27 out_name = op_data->name_heap + op_data->cur_heap_size; +Robb> 28 strcpy (out_name, memb_name); +Robb> 29 op_data->names[op_data->cur_entries] = out_name; +Robb> 30 op_data->cur_heap_size += strlen(memb_name) + 1; +Robb> 31 +Robb> 32 /* Is the output full? */ +Robb> 33 if (op_data->cur_entries >= op_data->max_entries) { +Robb> 34 return 1; +Robb> 35 } +Robb> 36 } +Robb> 37 return 0; +Robb> 38 } +Robb> +Robb> And finally, the definition of H5Glist(): +Robb> +Robb> 39 int +Robb> 40 H5Glist (hid_t group_id, size_t name_heap_size, char *name_heap, +Robb> 41 int *start_idx, unsigned max_entries, char *names[], +Robb> 42 int type) +Robb> 43 { +Robb> 44 H5G_list_t op_data; +Robb> 45 herr_t status; +Robb> 46 +Robb> 47 op_data->name_heap_size = name_heap_size; +Robb> 48 op_data->name_heap = name_heap; +Robb> 49 op_data->max_entries = max_entries; +Robb> 50 op_data->names = names; +Robb> 51 op_data->type = type; +Robb> 52 op_data->cur_entries = 0; +Robb> 53 op_data->cur_heap_size = 0; +Robb> 54 +Robb> 55 if (0==cur_entries) return 0; +Robb> 56 status = H5Giterate (group_id, ".", start_idx, H5G_list_op, +Robb> 57 &op_data); +Robb> 58 +Robb> 59 if (2==status && 0==op_data->cur_entries) { +Robb> 60 return -1; /*heap not large enough for even one name*/ +Robb> 61 } else if (2==status) { +Robb> 62 --*start_idx; /*heap overflow, try again later*/ +Robb> 63 } else if (status<0) { +Robb> 64 return status; /*iterator or operator error*/ +Robb> 65 } +Robb> 66 return op_data->cur_entries; +Robb> 67 } +Robb> +Robb> The only other really interesting thing in this example are lines 23, 61, +Robb> and 62. We don't know if the name heap will overflow until we find a name to +Robb> put there. And then if it does, we need to be able to restart the iterator at +Robb> the entry that failed instead of the following entry. +Robb> +Robb> H5Giterate example #5: Print all the names of objects in a group, without any +Robb> buffers. +Robb> --------------------- +Robb> +Robb> herr_t print_names (hid_t grp_id, const char *name, void *opdata) +Robb> { +Robb> puts (name); +Robb> return 0; +Robb> } +Robb> +Robb> { +Robb> H5Giterate (file_id, "/foo/bar", NULL, print_names, NULL); +Robb> } + +Elena> I believe there is a typo in the H5Pget_layout function in the source +Elena> code. Second argument ( H5D_layout_t *layout is missing....) + +It's returned by value, not reference. It returns only the class of +layout and then, based on the class, you must call some other H5Pget +function like H5Pget_chunk() like this: + + hid_t dcpl; /*dataset creation property list*/ + hsize_t dims[32]; /*chunk dimensions*/ + ... + switch (H5Pget_layout(dcpl)) { + case H5D_CHUNKED: + H5Pget_chunk(dcpl, NELMTS(dims), dims); + break; + ... + case H5D_LAYOUT_ERROR: + ... + ... + } + + +Quincy and html> +Quincy and html> +.... +.... [Datatype material move to H5T.html] +.... +Quincy and html> +Quincy and html> + + +</pre> +<hr> +<hr> + +<hr> +<address> +<a href="mailto:fbaker@ncsa.uiuc.edu">Frank Baker</a> +<br> +<a href="mailto:h5docs@ncsa.uiuc.edu">HDF5 Documentation</a> + +<br> +Last modified: 8 July 1998 + +</body> +</html> |