[svn-r7937] Purpose:

    Add RM docs for new H5I routines.

Description:
    Add new H5I routines to the reference manual.

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>