From bdce101e9f8470b2dc63a47dcba794435089e01c Mon Sep 17 00:00:00 2001
From: Frank Baker <fbaker@hdfgroup.org>
Date: Thu, 2 Aug 2001 10:59:10 -0500
Subject: [svn-r4300] Purpose:     Bringing 'last minute' release branch edits
 into development branch. Description:     Updated H5check_version per recent
 expansion of the source comments. Platforms tested:     IE 5

---
 doc/html/RM_H5.html | 73 +++++++++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 62 insertions(+), 11 deletions(-)

diff --git a/doc/html/RM_H5.html b/doc/html/RM_H5.html
index f651183..03b75c2 100644
--- a/doc/html/RM_H5.html
+++ b/doc/html/RM_H5.html
@@ -290,21 +290,72 @@ facilitate moving easily between them.</i>
             <em>unsigned</em> <code>relnum</code>
         )
 <dt><strong>Purpose:</strong>
-    <dd>
+    <dd>Verifies that library versions are consistent.
 <dt><strong>Description:</strong>
-    <dd><code>H5check_version</code> verifies that the arguments match the 
-        version numbers compiled into the library.  This function is intended 
-        to be called by the user to verify that the version of the header files 
-        compiled into the application matches the version of the HDF5 library 
-        being used.
+    <dd><code>H5check_version</code> verifies that the arguments provided 
+        with the function call match the version numbers compiled into 
+        the library.  
+        <p>
+        <code>H5check_version</code> serves two slightly differing purposes.
+        <p>
+        First, the function is intended to be called by the user to verify 
+        that the version of the header files compiled into an application 
+        matches the version of the HDF5 library being used.  
+        One may look at the <code>H5check</code> definition in the file 
+        <code>H5public.h</code> as an example.
         <p>
         Due to the risks of data corruption or segmentation faults, 
         <code>H5check_version</code> causes the application to abort if the
         version numbers do not match.
-        <p>
-        If the version numbers of the library do not match 
-	the version numbers in the header files being checked, the library calls the
+	The abort is achieved by means of a call to the
         standard C function <code>abort()</code>.
+        <p>
+        Note that <code>H5check_version</code> verifies only the 
+        major and minor version numbers and the release number; 
+        it does not verify the sub-release value as that should be 
+        an empty string for any official release.
+	This means that any two incompatible library versions must
+	have different {major,minor,release} numbers. (Notice the
+	reverse is not necessarily true.)
+        <p>
+        Secondarily, <code>H5check_version</code> verifies that the 
+        library version identifiers <code>H5_VERS_MAJOR</code>, 
+        <code>H5_VERS_MINOR</code>, <code>H5_VERS_RELEASE</code>, 
+        <code>H5_VERS_SUBRELEASE</code>, and <code>H5_VERS_INFO</code> 
+        are consistent.
+        This is designed to catch source code inconsistencies, 
+        but does not generate the fatal error as in the first stage
+	because this inconsistency does not cause errors in the data files.
+        If this check reveals inconsistencies, the library issues a warning
+        but the function does not fail.
+<!--
+        <p>
+<strong><em>Alternate to preceding paragraph / More to the point?</em></strong>
+<br>
+        If the function passes the above test and does not generate 
+        an <code>abort()</code> call, the function's second purpose 
+        comes into play. 
+        <code>H5check_version</code> then procedes to verify
+        that the additional library version identifiers 
+        <code>H5_VERS_SUBRELEASE</code>, and <code>H5_VERS_INFO</code> 
+        are consistent.
+        This is designed to catch source code inconsistencies, 
+        but does not generate the fatal error 
+        that is generated under the first function.
+        <p>
+        The version and release numbers passed as 
+        <code>H5check_version</code> parameters have the 
+        following relationsips to each other:  
+        <dir>
+            An official HDF5 release is labelled as 
+            <br>
+            HDF5 Release &lt;<code>majnum</code>&gt;<strong>.</strong>&lt;<code>minnum</code>&gt;<strong>.</strong>&lt;<code>relnum</code>&gt;
+        </dir>  
+        For example, in the version of the library known as HDF5 Release 1.4.2,
+        the 1 is the major version number, <code>majnum</code>;
+        the 1 is the minor version number, <code>minnum</code>; and
+        the 1 is the release number, <code>relnum</code>.
+-->
 <dt><strong>Parameters:</strong>
     <dl>
         <dt><em>unsigned </em><code>majnum</code>
@@ -369,10 +420,10 @@ H5&nbsp;&nbsp;
 <a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a> 
 
 <br>
-Last modified:  20 March 2001
+Last modified:  2 August 2001
 
 <br>
-Describes HDF5 Release 1.5, Unreleased Development Branch 
+Describes HDF5 Release 1.5, Unreleased Development Branch
 
 
 </body>
-- 
cgit v0.12