summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authorQuincey Koziol <koziol@hdfgroup.org>2003-12-11 18:30:27 (GMT)
committerQuincey Koziol <koziol@hdfgroup.org>2003-12-11 18:30:27 (GMT)
commit38af6a43fa7b537ed435d7aadbb110945853a554 (patch)
tree81b153105e85eb955720228931a6dff1076de2e1 /doc
parent16be9e3b5ab32e2c636cd5a0606f631be46226f1 (diff)
downloadhdf5-38af6a43fa7b537ed435d7aadbb110945853a554.zip
hdf5-38af6a43fa7b537ed435d7aadbb110945853a554.tar.gz
hdf5-38af6a43fa7b537ed435d7aadbb110945853a554.tar.bz2
[svn-r7937] Purpose:
Add RM docs for new H5I routines. Description: Add new H5I routines to the reference manual.
Diffstat (limited to 'doc')
-rw-r--r--doc/html/RM_H5I.html238
1 files changed, 235 insertions, 3 deletions
diff --git a/doc/html/RM_H5I.html b/doc/html/RM_H5I.html
index b100372..478671f 100644
--- a/doc/html/RM_H5I.html
+++ b/doc/html/RM_H5I.html
@@ -78,19 +78,52 @@ object names.
<table border=0>
<tr><td valign=top>
<ul>
+ <li><a href="#Identify-IncRef">H5Iinc_ref</a>
<li><a href="#Identify-GetName">H5Iget_name</a>
</ul>
</td><td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</td><td valign=top>
<ul>
+ <li><a href="#Identify-DecRef">H5Idec_ref</a>
<li><a href="#Identify-GetType">H5Iget_type</a>
</ul>
</td><td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</td><td valign=top>
<ul>
- &nbsp;
+ <li><a href="#Identify-GetRef">H5Iget_ref</a>
</ul>
</td></tr>
</table>
+<br>
+
+<i>Alphabetical Listing</i>
+
+<table border="0">
+ <tr>
+ <td valign="top">
+ <ul>
+ <li><a href="#Identify-DecRef">H5Idec_ref</a>
+ <li><a href="#Identify-GetName">H5Iget_name</a>
+ </ul>
+ </td>
+
+ <td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</td>
+
+ <td valign="top">
+ <ul>
+ <li><a href="#Identify-GetRef">H5Iget_ref</a>
+ <li><a href="#Identify-GetType">H5Iget_type</a>
+ </ul>
+ </td>
+
+ <td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</td>
+
+ <td valign="top">
+ <ul>
+ <li><a href="#Identify-IncRef">H5Iinc_ref</a>
+ </ul>
+ </td>
+ </tr>
+</table>
<br>
<strong>The FORTRAN90 Interfaces:</strong>
@@ -102,20 +135,96 @@ as the corresponding C function.
<table border=0>
<tr><td valign=top>
<ul>
+ <li><a href="#Identify-IncRef">h5iinc_ref_f</a>
<li><a href="#Identify-GetName">h5iget_name_f</a>
</ul>
</td><td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</td><td valign=top>
<ul>
+ <li><a href="#Identify-DecRef">h5idec_ref_f</a>
<li><a href="#Identify-GetType">h5iget_type_f</a>
</ul>
</td><td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</td><td valign=top>
<ul>
- &nbsp;
+ <li><a href="#Identify-GetRef">h5iget_ref_f</a>
</ul>
</td></tr>
</table>
<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Idec_ref" -->
+<hr>
+<dl>
+<dt><strong>Name:</strong> <a name="Identify-DecRef">H5Idec_ref</a>
+<dt><strong>Signature:</strong>
+ <dd><em>int</em> <code>H5Idec_ref</code>(<em>hid_t</em> <code>obj_id</code>)
+<dt><strong>Purpose:</strong>
+ <dd>Decrements the reference count for an object.
+<dt><strong>Description:</strong>
+ <dd><code>H5Idec_ref</code> decrements the reference count of the object
+ identified by <code>obj_id</code>.
+
+ <p>
+ The reference count for an object ID is attached to the information
+ about an object in memory and has no relation to the number of links to
+ an object on disk.
+
+ <p>
+ The reference count for a newly created object will be 1.
+ Reference counts for objects may be explicitly modified with this
+ function or with <code>H5Iinc_ref</code>.
+ When an object ID's reference count reaches zero, the object will be
+ closed.
+ Calling an object ID's 'close' function decrements the reference count
+ for the ID which normally closes the object, but
+ if the reference count for the ID has been incremented with
+ <code>H5Iinc_ref</code>, the object will only be closed when the
+ reference count
+ reaches zero with further calls to this function or the
+ object ID's 'close' function.
+
+ <p>
+ If the object ID was created by a collective parallel call (such as
+ <code>H5Dcreate</code>, <code>H5Gopen</code>, etc.), the reference
+ count should be modified by all the processes which have copies of
+ the ID. Generally this means that group, dataset, attribute, file
+ and named datatype IDs should be modified by all the processes and
+ that all other types of IDs are safe to modify by individual processes.
+
+ <p>
+ This function is of particular value when an application is maintaining
+ multiple copies of an object ID. The object ID can be incremented when
+ a copy is made. Each copy of the ID can then be safely closed or
+ decremented and the HDF5 object will be closed when the reference count
+ for that that object drops to zero.
+<dt><strong>Parameters:</strong>
+ <dl>
+ <dt><em>hid_t</em> <code>obj_id</code>
+ <dd>IN: Object identifier whose reference count will be modified.
+ </dl>
+<dt><strong>Returns:</strong>
+ <dd>Returns a non-negative reference count of the object ID after
+ decrementing it if successful; otherwise a negative value is returned.
+<dt><strong>Fortran90 Interface:</strong> h5idec_ref_f
+ <dd>
+ <pre>
+SUBROUTINE h5idec_ref_f(obj_id, ref_count, hdferr)
+ IMPLICIT NONE
+ INTEGER(HID_T), INTENT(IN) :: obj_id !Object identifier
+ INTEGER, INTENT(OUT) :: ref_count !Reference count of object ID
+ INTEGER, INTENT(OUT) :: hdferr ! Error code
+ ! 0 on success, and -1 on failure
+END SUBROUTINE h5idec_ref_f
+ </pre>
+
+ <!--<dt><strong>Non-C API(s):</strong>
+ <dd>
+
+ <img src="Graphics/Java.gif">
+ <img src="Graphics/C++.gif">
+ -->
+</dl>
+
+<!-- NEW PAGE -->
<!-- NEW PAGE -->
<!-- HEADER RIGHT "H5Iget_name" -->
<hr>
@@ -190,6 +299,56 @@ END SUBROUTINE h5iget_name_f
</dl>
<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Iget_ref" -->
+<hr>
+<dl>
+<dt><strong>Name:</strong> <a name="Identify-GetRef">H5Iget_ref</a>
+<dt><strong>Signature:</strong>
+ <dd><em>int</em> <code>H5Iget_ref</code>(<em>hid_t</em> <code>obj_id</code>)
+<dt><strong>Purpose:</strong>
+ <dd>Retrieves the reference count for an object.
+<dt><strong>Description:</strong>
+ <dd><code>H5Iget_ref</code> retrieves the reference count of the object
+ identified by <code>obj_id</code>.
+
+ <p>
+ The reference count for an object ID is attached to the information
+ about an object in memory and has no relation to the number of links to
+ an object on disk.
+
+ <p>
+ This function can also be used to check if an object ID is still valid.
+ A non-negative return value from this function indicates that the ID
+ is still valid.
+<dt><strong>Parameters:</strong>
+ <dl>
+ <dt><em>hid_t</em> <code>obj_id</code>
+ <dd>IN: Object identifier whose reference count will be retrieved.
+ </dl>
+<dt><strong>Returns:</strong>
+ <dd>Returns a non-negative current reference count of the object ID
+ if successful; otherwise a negative value is returned.
+<dt><strong>Fortran90 Interface:</strong> h5iget_ref_f
+ <dd>
+ <pre>
+SUBROUTINE h5iget_ref_f(obj_id, ref_count, hdferr)
+ IMPLICIT NONE
+ INTEGER(HID_T), INTENT(IN) :: obj_id !Object identifier
+ INTEGER, INTENT(OUT) :: ref_count !Reference count of object ID
+ INTEGER, INTENT(OUT) :: hdferr ! Error code
+ ! 0 on success, and -1 on failure
+END SUBROUTINE h5iget_ref_f
+ </pre>
+
+ <!--<dt><strong>Non-C API(s):</strong>
+ <dd>
+
+ <img src="Graphics/Java.gif">
+ <img src="Graphics/C++.gif">
+ -->
+</dl>
+
+<!-- NEW PAGE -->
<!-- HEADER RIGHT "H5Iget_type" -->
<hr>
<dl>
@@ -264,6 +423,79 @@ END SUBROUTINE h5iget_type_f
-->
</dl>
+<!-- NEW PAGE -->
+<!-- HEADER RIGHT "H5Iinc_ref" -->
+<hr>
+<dl>
+<dt><strong>Name:</strong> <a name="Identify-IncRef">H5Iinc_ref</a>
+<dt><strong>Signature:</strong>
+ <dd><em>int</em> <code>H5Iinc_ref</code>(<em>hid_t</em> <code>obj_id</code>)
+<dt><strong>Purpose:</strong>
+ <dd>Increments the reference count for an object.
+<dt><strong>Description:</strong>
+ <dd><code>H5Iinc_ref</code> increments the reference count of the object
+ identified by <code>obj_id</code>.
+
+ <p>
+ The reference count for an object ID is attached to the information
+ about an object in memory and has no relation to the number of links to
+ an object on disk.
+
+ <p>
+ The reference count for a newly created object will be 1.
+ Reference counts for objects may be explicitly modified with this
+ function or with <code>H5Idec_ref</code>.
+ When an object ID's reference count reaches zero, the object will be
+ closed.
+ Calling an object ID's 'close' function decrements the reference count
+ for the ID which normally closes the object, but
+ if the reference count for the ID has been incremented with this
+ function, the object will only be closed when the reference count
+ reaches zero with further calls to <code>H5Idec_ref</code> or the
+ object ID's 'close' function.
+
+ <p>
+ If the object ID was created by a collective parallel call (such as
+ <code>H5Dcreate</code>, <code>H5Gopen</code>, etc.), the reference
+ count should be modified by all the processes which have copies of
+ the ID. Generally this means that group, dataset, attribute, file
+ and named datatype IDs should be modified by all the processes and
+ that all other types of IDs are safe to modify by individual processes.
+
+ <p>
+ This function is of particular value when an application is maintaining
+ multiple copies of an object ID. The object ID can be incremented when
+ a copy is made. Each copy of the ID can then be safely closed or
+ decremented and the HDF5 object will be closed when the reference count
+ for that that object drops to zero.
+<dt><strong>Parameters:</strong>
+ <dl>
+ <dt><em>hid_t</em> <code>obj_id</code>
+ <dd>IN: Object identifier whose reference count will be modified.
+ </dl>
+<dt><strong>Returns:</strong>
+ <dd>Returns a non-negative reference count of the object ID after
+ incrementing it if successful; otherwise a negative value is returned.
+<dt><strong>Fortran90 Interface:</strong> h5iinc_ref_f
+ <dd>
+ <pre>
+SUBROUTINE h5iinc_ref_f(obj_id, ref_count, hdferr)
+ IMPLICIT NONE
+ INTEGER(HID_T), INTENT(IN) :: obj_id !Object identifier
+ INTEGER, INTENT(OUT) :: ref_count !Reference count of object ID
+ INTEGER, INTENT(OUT) :: hdferr ! Error code
+ ! 0 on success, and -1 on failure
+END SUBROUTINE h5iinc_ref_f
+ </pre>
+
+ <!--<dt><strong>Non-C API(s):</strong>
+ <dd>
+
+ <img src="Graphics/Java.gif">
+ <img src="Graphics/C++.gif">
+ -->
+</dl>
+
<!-- #BeginLibraryItem "/ed_libs/NavBar_RM.lbi" --><hr>
<center>
<table border=0 width=98%>
@@ -304,7 +536,7 @@ And in this document, the
Describes HDF5 Release 1.7, the unreleased development branch; working toward HDF5 Release 1.8.0
</address><!-- #EndLibraryItem --><SCRIPT LANGUAGE="JAVASCRIPT">
<!--
-document.writeln("Last modified: 21 October 2003");
+document.writeln("Last modified: 11 December 2003");
-->
</SCRIPT>