From 180a47a037320fc8fcf48cf3114e1f548d019659 Mon Sep 17 00:00:00 2001
From: Frank Baker <fbaker@hdfgroup.org>
Date: Wed, 1 Nov 2000 14:01:55 -0500
Subject: [svn-r2789] Purpose:     To warn users that RM_H5G.html and
 Groups.html can render groups and     datasets inaccessible in a file.
 Solution:     Modified RM_H5G.html and Groups.html as follows:       -- Added
 warning (new section) to Groups.html that H5Gunlink and          H5Gmove can
 result in inaccessible groups and datasets.       -- Added links to that new
 section from H5Gunlink and H5Gmove          in RM_H5G.html. Platforms tested:
     IE5

---
 doc/html/Groups.html | 29 ++++++++++++++++++++++++++++-
 doc/html/RM_H5G.html | 12 +++++++++++-
 2 files changed, 39 insertions(+), 2 deletions(-)

diff --git a/doc/html/Groups.html b/doc/html/Groups.html
index 44ca0fb..be5844f 100644
--- a/doc/html/Groups.html
+++ b/doc/html/Groups.html
@@ -307,6 +307,33 @@
 	string is returned.
     </dl>
 
+    <a name="H5GUnlinkToCorrupt">
+    <h2>6. Unlinking Datasets with H5Gmove and H5Gunlink</h2>
+    </a>
+
+    <p>Exercise caution in the use of <code>H5Gmove</code> and 
+       <code>H5Gunlink</code>.
+
+    <p>Note that <code>H5Gmove</code> and <code>H5Gunlink</code>
+       each include a step that unlinks pointers to a set or group.
+       If the link that is removed is on the only path leading 
+       to a dataset or group, that dataset or group will become 
+       inaccessible in the file.
+
+    <p>Consider the following example.  Assume that the group
+       <code>group2</code> can only be accessed via the following path,
+       where <code>top_group</code> is a member of the file's root group:
+       <pre>
+              <code>/top_group/group1/group2/</code> </pre>
+       Using <code>H5Gmove</code>, <code>top_group</code> is renamed
+       to be a member of <code>group2</code>.  At this point, since 
+       <code>top_group</code> was the only route from the root group 
+       to <code>group1</code>, there is no longer a path by which 
+       one can access <code>group1</code>, <code>group2</code>, or 
+       any member datasets.
+       <code>top_group</code> and any member datasets have also 
+       become inaccessible.
+
 
 <hr>
 <center>
@@ -359,7 +386,7 @@
 
 <!-- Created: Tue Jan 27 09:11:27 EST 1998 -->
 <!-- hhmts start -->
-Last modified:  14 October 1999
+Last modified:  1 November 2000
 <!-- hhmts end -->
 
   </body>
diff --git a/doc/html/RM_H5G.html b/doc/html/RM_H5G.html
index 9d3de2d..8729f27 100644
--- a/doc/html/RM_H5G.html
+++ b/doc/html/RM_H5G.html
@@ -360,6 +360,11 @@ create or access function.
         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>Warning:</strong>
+    <dd>Exercise care in unlinking groups as it is possible to render data in 
+        a file inaccessible with <code>H5Gunlink</code>.  
+        See <a href="Groups.html#H5GUnlinkToCorrupt">The Group Interface</a> 
+        in the <cite>HDF5 User's Guide</cite>.
   <dt><strong>Parameters:</strong>
     <dl>
       <dt><em>hid_t</em> <code>loc_id</code>
@@ -502,6 +507,11 @@ create or access function.
         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>Warning:</strong>
+    <dd>Exercise care in moving groups as it is possible to render data in 
+        a file inaccessible with <code>H5Gmove</code>.  
+        See <a href="Groups.html#H5GUnlinkToCorrupt">The Group Interface</a> 
+        in the <cite>HDF5 User's Guide</cite>.
   <dt><strong>Parameters:</strong>
     <dl>
       <dt><em>hid_t</em> <code>loc_id</code>
@@ -805,7 +815,7 @@ H5G&nbsp;&nbsp;
 <a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a> 
 
 <br>
-Last modified:  7 March 2000
+Last modified:  1 November 2000
 <br>
 Describes HDF5 Version 1.3 (Unrelased development version. Dynamic.)
 
-- 
cgit v0.12