[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
This commit is contained in:
Frank Baker 2001-08-02 10:59:10 -05:00
parent a2788dafc7
commit bdce101e9f

View File

@ -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>