HDF5 documents and links Introduction to HDF5 |
HDF5 User’s Guide HDF5 Reference Manual HDF5 Application Developer's Guide |
Forward compatibility relates to the ability of an older HDF5 Library to read files created by a newer HDF5 Library. An older library should be able to read objects that are known to that library in a file created by Release 1.8.0. This document includes a list of features that are designed to create no forward compatibility problems; a forward compatibility failure with one of these features is a bug.
Backward compatibility relates to the ability of a newer HDF5 Library to read files created by an older HDF5 Library. E.g., if HDF5 Release 1.8.0 is unable to read files created by Release 1.6.5, that is a backward compatibility failure. An HDF5 design criterion is that the HDF5 Library is always backwardly compatible. A backward compatibilty failure is a bug.
The table below lists features introduced in HDF5 Release 1.8.0 and the objects they may act on, then indicates combinations in which compatibility conflicts might arise. Some features will always create objects or write data that will be incompatible with older versions of the library; others will do so only under certain circumstances.
Related document
API Compatibility Macros in HDF5 discusses configurable function macros that were introduced in HDF5 Release 1.8.0 to facilitate the adaptation of applications to that and future releases, criteria for selecting specific configurations, and steps required to set them up.
Whereas New Features in HDF5 Release 1.8.0 and Format Compatibility Considerations discusses format compatibility issues to consider when applications using HDF5 Release 1.8.0 (or a later release) will create files that might have to be read using older versions of the HDF5 Library, API Compatibility Macros in HDF5 discusses an approach to resolving API compatibility issues when moving an application to that release (or a later release).
Reading the table
New features in HDF5 Release 1.8.0 are listed across the top of the table.
Objects in an HDF5 file that features might affect format compatibility are listed on the left-hand side. If the object is printed in bold, the symbols across the row indicate the effect that the feature has when it acts directly on that object. Associated with several objects are one or more objects indented to the right and printed in normal typeface; ripple effects of a feature may affect these objects when the feature acts on the related bold-faced object.
Consider the intersection of the Attribute lines and Attribute and object headers features. The symbols on the Attribute line indicate the effect of the feature when it acts on an attribute; the symbols on the Object line, immediately below, indicate the effect of the feature on an HDF5 object when the feature acts on an attribute attached to that object. For example, the table indicates that attribute creation order can be tracked and indexed with the HDF5 Release 1.8.0 Library only with new-format attributes, and those attr ibutes will not be readable by older libraries. The table further indicates that an object to which such attributes are attached (a dataset, for example) will therefore be unreadable by an older HDF5 library.
See section 3, “Features that may create (or are known to create) compatibility concerns,” for further explanation of these functions and their format compatiblity implications.
Table footnotes:
An expanded table [PDF, large format (11x17 inches)] is available, listing all new features in Release 1.8.0, including features that create no format compatibility issues. These additional features are described more fully in section 4, “Features that are designed to create no compatibility concerns.”
H5Pset_libver_bounds
function.
H5Pset_libver_bounds
is called with the
low
argument equal to HDF_LIBVER_LATEST
,
new objects are created using the latest available format versions.
This is a file access property, so this object creation behavior can be set for any existing file, and can vary according to application needs each time a file is opened.
Functions:
H5Pset_libver_bounds( hid_t fapl_id, H5F_libver_t low, H5F_libver_t high )
H5Pget_libver_bounds( hid_t fapl_id, H5F_libver_t* low, H5F_libver_t* high )
Default behavior: If H5Pset_libver_bounds
is not called with low
equal to
HDF_LIBVER_LATEST
, then the HDF5 Library provides the greatest-possible format
compatibility. It does this by creating objects with the earliest possible format that
will handle the data being stored and accommodate the action being taken.
This new group implementation also enables user-defined and external links.
Note: Link indexing by name is inherent to the HDF5 implementation and requires no special setting.
(Note: Attribute indexing by name is inherent to the HDF5 implementation and requires no special setting.)
The current implementation includes the ASCII and UTF-8 standard character sets.
Note that when this property is set, any
missing intermediate groups are created
with the properties of the lowest-level,
previously existing existing group.
I.e., if the object elf is being created at
FILE:/a1/b543/cde/d12/elf
,
and only groups a1
and b543
in that hierarchy exist in FILE
,
groups cde
and d12
will be created with the properties of the
group b543
.
H5Dcreate_anon
, H5Gcreate_anon
,
or H5Tcommit_anon
.
If the object is to be preserved in the file,
it must then be linked to a location in the file with
H5Llink
before the file is closed.
The n-bit filter compresses data from the in-memory datatype to an n-bit datatype in the file. Since data is normally byte- or word-aligned in memory, this can result in substantial savings in the size of stored data.
The scale-offset filter performs a scale and/or offset operation on each data value and truncates the resulting value to a minimum number of bits before storing it.
H5Screate
) (3)
H5S_NULL
dataspace class allows an application
to use H5Screate
to define a dataset or
attribute dataspace with no elements.
This feature is implemented through the addition
of a NULL dataspace, H5S_NULL
,
to the set of valid dataspace classes.
HDF5 documents and links Introduction to HDF5 |
HDF5 User’s Guide HDF5 Reference Manual HDF5 Application Developer's Guide |
The HDF Group Help Desk:
Describes HDF5 Release 1.8.18, November 2016. | Copyright by The HDF Group |