[svn-r4678]

Purpose:
    Expanded descriptions and minor copy edits.

Description:
    H5Fcreate, H5Fopen, H5Fclose
       Changes stemming from Albert's H5Fxxx proposal
    Added IN/OUT designations to parameters.
    Minor formatting and copy edits

    [Sorry, but "no space left on device" error prevents deletion
    of extra blank lines!]


Platforms tested:
    IE 5

1 files changed, 123 insertions, 49 deletions

diff --git a/doc/html/RM_H5F.html b/doc/html/RM_H5F.html
index fbcbcc2..e01da01 100644
--- a/doc/html/RM_H5F.html
+++ b/doc/html/RM_H5F.html
@@ -135,45 +135,72 @@ facilitate moving easily between them.</i>
             function for accessing existing HDF5 files.  
             <p>
             The parameter <code>access_id</code> is a file access property
-	      list identifier or <code>H5P_DEFAULT</code> for the default I/O access
-            parameters.  
+            list identifier or <code>H5P_DEFAULT</code> if the 
+            default I/O access parameters are to be used  
             <p>
             The <code>flags</code> argument determines whether writing 
- 		to an existing file will be allowed or not.  
+            to an existing file will be allowed.  
             The file is opened with read and write permission if 
-	      <code>flags</code> is set to <code>H5F_ACC_RDWR</code>.  
+            <code>flags</code> is set to <code>H5F_ACC_RDWR</code>.  
             All flags may be combined with the bit-wise OR operator (`|') 
- 		to change the behavior of the file open call.  
- 		The more complex behaviors of a file's access are controlled 
- 		through the file-access property list.
+            to change the behavior of the file open call.  
+            More complex behaviors of file access are controlled 
+            through the file-access property list.
             <p>
-            Files which are opened more than once return a unique identifier 
-            for each <code>H5Fopen()</code> call and can be accessed 
-            through all file identifiers.  
+            The return value is a file identifier for the open file;
+            this file identifier should be closed by calling 
+            <code>H5Fclose</code> when it is no longer needed. 
             <p>
-            The return value is a file identifier for the open file and it
-            should be closed by calling <code>H5Fclose()</code> when it is
-            no longer needed. 
+
+            <b>Special case -- Multiple opens:</b>
+            <br>
+            A file can often be opened with a new <code>H5Fopen</code> 
+            call without closing an already-open identifier established 
+            in a previous <code>H5Fopen</code> or <code>H5Fcreate</code> 
+            call.  Each such <code>H5Fopen</code> call will return a 
+            unique identifier and the file can be accessed through any 
+            of these identifiers as long as the identifier remains valid.
+            In such multiply-opened cases, all the open calls should 
+            use the same <code>flags</code> argument. 
+            <p>
+            In some cases, such as files on a local Unix file system, 
+            the HDF5 library can detect that a file is multiply opened and 
+            will maintain coherent access among the file identifiers.
+            <p>
+            But in many other cases, such as parallel file systems or
+            networked file systems, it is not always possible to detect 
+            multiple opens of the same physical file.  
+            In such cases, HDF5 will treat the file identifiers 
+            as though they are accessing different files and
+            will be unable to maintain coherent access.
+            Errors are likely to result in these cases.
+            While unlikely, the HDF5 library may not be able to detect,
+            and thus report, such errors.
+            <p>
+            It is generally recommended that applications avoid 
+            multiple opens of the same file.
+
 <dt><strong>Parameters:</strong>
     <dl>
         <dt><em>const char *</em><code>name</code>
-            <dd>Name of the file to access.
+            <dd>IN: Name of the file to access.
         <dt><em>unsigned</em> <code>flags</code>
-            <dd>File access flags.  Allowable values are:
+            <dd>IN: File access flags.  Allowable values are:
                 <ul><dl>
-                    <dt>H5F_ACC_RDWR
+                    <dt><code>H5F_ACC_RDWR</code>
                         <dd>Allow read and write access to file.
-                    <dt>H5F_ACC_RDONLY
+                    <dt><code>H5F_ACC_RDONLY</code>
                         <dd>Allow read-only access to file.
-                </dl></ul>
+                </dl>
                 <li><code>H5F_ACC_RDWR</code> and <code>H5F_ACC_RDONLY</code> 
                 are mutually exclusive; use exactly one.
                 <li>An additional flag, <code>H5F_ACC_DEBUG</code>, prints 
                 debug information.  This flag is used only by HDF5 library 
                 developers; it is neither tested nor supported
                 for use in applications.
+                </ul>
         <dt><em>hid_t</em> <code>access_id</code>
-            <dd>Identifier for the file access properties list.
+            <dd>IN: Identifier for the file access properties list.
                 If parallel file access is desired, this is a collective
                 call according to the communicator stored in the
                 <code>access_id</code>. 
@@ -218,17 +245,55 @@ facilitate moving easily between them.</i>
             property lists.  The value of <code>H5P_DEFAULT</code> for 
             a property list value indicates that the library should use
             the default values for the appropriate property list.
+            <p>
+            The return value is a file identifier for the newly-created file;
+            this file identifier should be closed by calling 
+            <code>H5Fclose</code> when it is no longer needed. 
+            <p>
+
+            <b>Special case -- File creation in the case of an 
+            already-open file:</b>
+            <br>
+            If a file being created is already opened, by either a 
+            previous <code>H5Fopen</code> or <code>H5Fcreate</code> call, 
+            the HDF5 library may or may not detect that the open file and 
+            the new file are the same physical file. 
+            (See <a href="#File-Open"><code>H5Fopen</code></a> regarding 
+            the limitations in detecting the re-opening of an already-open 
+            file.) 
+            <p>
+            If the library detects that the file is already opened, 
+            <code>H5Fcreate</code> will return a failure, regardless 
+            of the use of <code>H5F_ACC_TRUNC</code>.
+            <p>
+            If the library does not detect that the file is already opened 
+            and <code>H5F_ACC_TRUNC</code> is not used, 
+            <code>H5Fcreate</code> will return a failure because the file 
+            already exists.  Note that this is correct behavior.
+            <p>
+            But if the library does not detect that the file is already 
+            opened and <code>H5F_ACC_TRUNC</code> is used, 
+            <code>H5Fcreate</code> will truncate the existing file
+            and return a valid file identifier.
+            Such a truncation of a currently-opened file will almost 
+            certainly result in errors. 
+            While unlikely, the HDF5 library may not be able to detect,
+            and thus report, such errors.
+            <p>
+            Applications should avoid calling <code>H5Fcreate</code> 
+            with an already opened file.
+
 <dt><strong>Parameters:</strong>
     <dl>
         <dt><em>const char *</em><code>name</code>
-            <dd>Name of the file to access.
+            <dd>IN: Name of the file to access.
         <dt><em>uintn</em> <code>flags</code>
-            <dd>File access flags.  Allowable values are:
+            <dd>IN: File access flags.  Allowable values are:
                 <ul><dl>
-                    <dt>H5F_ACC_TRUNC
+                    <dt><code>H5F_ACC_TRUNC</code>
                         <dd>Truncate file, if it already exists,  
                             erasing all data previously stored in the file.
-                    <dt>H5F_ACC_EXCL
+                    <dt><code>H5F_ACC_EXCL</code>
                         <dd>Fail if file already exists.
                 </dl></ul>
                 <li><code>H5F_ACC_TRUNC</code> and <code>H5F_ACC_EXCL</code> 
@@ -238,11 +303,11 @@ facilitate moving easily between them.</i>
                 developers; <i>it is neither tested nor supported</i> 
                 for use in applications.
         <dt><em>hid_t</em> <code>create_id</code>
-            <dd>File creation property list identifier, used when modifying
+            <dd>IN: File creation property list identifier, used when modifying
                 default file meta-data.
                 Use <code>H5P_DEFAULT</code> for default file creation properties.
         <dt><em>hid_t</em> <code>access_id</code>
-            <dd>File access property list identifier.
+            <dd>IN: File access property list identifier.
                 If parallel file access is desired, this is a collective
                 call according to the communicator stored in the
                 <code>access_id</code>. 
@@ -300,9 +365,9 @@ facilitate moving easily between them.</i>
 <dt><strong>Parameters:</strong>
     <dl>
         <dt><em>hid_t </em><code>object_id</code>
-            <dd>Identifier of object used to identify the file.
+            <dd>IN: Identifier of object used to identify the file.
         <dt><em>H5F_scope_t</em> <code>scope</code>
-            <dd>Specifies the scope of the flushing action.
+            <dd>IN: Specifies the scope of the flushing action.
     </dl>
 <dt><strong>Returns:</strong>
     <dd>Returns a non-negative value if successful;
@@ -332,7 +397,7 @@ facilitate moving easily between them.</i>
 <dt><strong>Parameters:</strong>
     <dl>
         <dt><em>const char *</em><code>name</code>
-            <dd>File name to check format.
+            <dd>IN: File name to check format.
     </dl>
 <dt><strong>Returns:</strong>
     <dd>When successful, returns a positive value, for <code>TRUE</code>,
@@ -372,7 +437,7 @@ facilitate moving easily between them.</i>
 <dt><strong>Parameters:</strong>
     <dl>
         <dt><em>hid_t</em> <code>file_id</code>
-            <dd>Identifier of the file to get creation property list of
+            <dd>IN: Identifier of the file to get creation property list of
     </dl>
 <dt><strong>Returns:</strong>
     <dd>Returns a file creation property list identifier if successful;
@@ -409,7 +474,7 @@ facilitate moving easily between them.</i>
 <dt><strong>Parameters:</strong>
     <dl>
         <dt><em>hid_t</em> <code>file_id</code>
-            <dd>Identifier of file to get access property list of
+            <dd>IN: Identifier of file to get access property list of
     </dl>
 <dt><strong>Returns:</strong>
     <dd>Returns a file access property list identifier if successful;
@@ -443,15 +508,8 @@ facilitate moving easily between them.</i>
             identifier, group identifier, or shared datatype identifier),
             the file will be fully closed and access will end.
             <p>
-            If this is the last file identifier open for the file 
-            and other access identifiers are still in use, 
-            those access identifiers remain valid until separately 
-            closed and can still be used.
-            (But the file identifier is no longer valid and cannot be used.)
-            Once all of the remaining access identifiers are closed,
-            the file will be fully closed and access will end.
-            <p>
-            <strong>EXCEPTION:</strong> 
+            <strong>Delayed close:</strong> 
+            <br>
             Note the following deviation from the above-described behavior.
             If <code>H5Fclose</code> is called for a file but one or more 
             objects within the file remain open, those objects will remain 
@@ -462,10 +520,26 @@ facilitate moving easily between them.</i>
             (including writable) until it is explicitely closed.  
             The file will be automatically closed once all objects in the
             file have been closed.
+            <p>
+            Be warned, hoever, that there are circumstances where it is 
+            not possible to delay closing a file.  
+            For example, an MPI-IO file close is a collective call; all of
+            the processes that opened the file must close it collectively.
+            The file cannot be closed at some time in the future by each 
+            process in an independent fashion.
+            Another example is that an application using an AFS token-based 
+            file access privilage may destroy its AFS token after 
+            <code>H5Fclose</code> has returned successfully.  
+            This would make any future access to the file, or any object 
+            within it, illegal. 
+            <p>
+            In such situations, applications must close all open objects 
+            in a file before calling <code>H5Fclose</code>.  
+            It is generally recommended to do so in all cases.
 <dt><strong>Parameters:</strong>
     <dl>
         <dt><em>hid_t</em> <code>file_id</code>
-            <dd>Identifier of a file to terminate access to.
+            <dd>IN: Identifier of a file to terminate access to.
     </dl>
 <dt><strong>Returns:</strong>
     <dd>Returns a non-negative value if successful;
@@ -502,16 +576,16 @@ facilitate moving easily between them.</i>
 <dt><strong>Parameters:</strong>
     <dl>
         <dt><em>hid_t</em> <code>loc_id</code>
-            <dd>The identifier for of file or group in 
+            <dd>IN: Identifier for of file or group in 
                 which <code>name</code> is defined.
         <dt><em>const char *</em><code>name</code>
-            <dd>The name of the group onto which the 
+            <dd>IN: Name of the group onto which the 
                 file specified by <code>child_id</code> 
                 is to be mounted.
         <dt><em>hid_t</em> <code>child_id</code>
-            <dd>The identifier of the file to be mounted.
+            <dd>IN: Identifier of the file to be mounted.
         <dt><em>hid_t</em> <code>plist_id</code>
-            <dd>The identifier of the property list to be used.
+            <dd>IN: Identifier of the property list to be used.
     </dl>
 <dt><strong>Returns:</strong>
     <dd>Returns a non-negative value if successful;
@@ -554,10 +628,10 @@ facilitate moving easily between them.</i>
 <dt><strong>Parameters:</strong>
     <dl>
         <dt><em>hid_t</em> <code>loc_id</code>
-            <dd>The file or group identifier for the location at which
+            <dd>IN: File or group identifier for the location at which
                 the specified file is to be unmounted.
         <dt><em>const char *</em><code>name</code>
-            <dd>The name of the mount point.
+            <dd>IN: Name of the mount point.
     </dl>
 <dt><strong>Returns:</strong>
     <dd>Returns a non-negative value if successful;
@@ -597,11 +671,11 @@ facilitate moving easily between them.</i>
             <code> H5Freopen&nbsp;(file_id) </code> to reopen it.
             <p>
             The new file identifier should be closed by calling
-            <code>H5Fclose()</code> when it is no longer needed.
+            <code>H5Fclose</code> when it is no longer needed.
 <dt><strong>Parameters:</strong>
     <dl>
         <dt><em>hid_t</em> <code>file_id</code>
-            <dd>Identifier of a file for which an additional identifier 
+            <dd>IN: Identifier of a file for which an additional identifier 
                 is required.
     </dl>
 <dt><strong>Returns:</strong>
@@ -658,7 +732,7 @@ H5F&nbsp;&nbsp;
 <a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a> 
 
 <br>
-Last modified:  12 October 2000
+Last modified:  5 December 2001
 <br>
 Describes HDF5 Release 1.5, Unreleased Development Branch