API Compatibility Macros in HDF5

Audience

This document is designed for HDF5 users or developers with existing applications that they wish to modify to take advantage of the latest version of the HDF5 Library.

Compatibility issues

With a major release such HDF5 Release 1.8.0, there are often compatibility issues that must be considered when migrating an application to the new release.

This document, API Compatibility Macros in HDF5, discusses an approach to resolving API compatibility issues. New Features in HDF5 Release 1.8.0 and Format Compatibility Considerations discusses features introduced in HDF5 Release 1.8.0, corresponding APIs that may trigger these features, and the resulting potential file format compatibility issues.

Summary and motivation

Several basic HDF5 functions have changed over the years as requirements on the library and data format have evolved. To enable existing applications to run properly, all versions of these functions have been retained; for flexibility and ease-of-use, macros have been created that can be mapped either globally to broad sets of function versions or on a function-by-function basis to specific versions. For example, an overall approach can be determined by means global setting; function-level settings can then be used to override the global setting then for specific functions.

The HDF5 team generally (and strongly) encourages users to update applications to work with the latest HDF5 release, but there are common circumstances where that can take substantial resources or, for other reasons, may not a realistic or necessary. Use of the API-compatibility macros feature, as described in this document, can be particularly valuable in situations such as the following:

Only binaries are available, with no access to the original source code; updating the application is not feasible.
Source code is available, but there are no resources to update it.
Source code is available, as are resources to update it, but the old version works quite satisfactorily. On the other hand, it would be valuable to take advantage of certain efficiencies in the newer HDF5 release.
The applications are large or complex and must continue to run while the update is carried out.

Understanding and using the macros

Scope of selection:
The HDF5 Library can be globally configured in the following ways:

To present fully-compatible HDF5 Release 1.6.x interfaces. Macros will be mapped to 1.6.x function versions; 1.8.0 interfaces will be available, but must be called by their version-numbered names.
For example, the macro H5Gcreate will be mapped to the version-numbered 1.6.x version of the function, H5Gcreate1. The version-numbered 1.6.x and 1.8.x functions will be explicitly available as H5Gcreate1 and H5Gcreate2, respectively.
To present complete HDF5 Release 1.8.0 interfaces. Macros will be mapped to 1.8.0 function versions; 1.6.x interfaces will be available, but must be called by their version-numbered names.
For example, the macro H5Gcreate will be mapped to the version-numbered 1.8.0 version of the function, H5Gcreate2. The version-numbered 1.6.x and 1.8.x functions will be explicitly available as H5Gcreate1 and H5Gcreate2, respectively.
To make no compatibility allowance, presenting strictly HDF5 Release 1.8.x interfaces; macros will be mapped to 1.8.x function versions.
For example, the macro H5Gcreate will be mapped to the 1.8.x version of the function, H5Gcreate2. The 1.8.x version of the function,H5Gcreate2, will be available to be called explicitly. The version-numbered 1.6.x function, H5Gcreate1, will not be available.

Function-level settings are available for situations where it is necessary to have access to more complex combinations of newer and older function versions.

Specified macro is mapped to selected version of function.
If H5Gcreate_vers is set to 2, the macro H5Gcreate will be mapped to H5Gcreate2.

Global settings can be selected either when the HDF5 Library is built and installed or when the application is built and installed. Function-level settings can be selected only when the application is built and installed. Function-level settings override the global setting.

Global settings
Global settings are determined when either the HDF5 Library or the user application is built and installed.

**Table1:** Summary of HDF5 global compatibility settings
Configure flag (global settings)	Public symbols are mapped to...	Deprecated symbols are available
Default	1.6 Example: `H5Gcreate` is mapped to `H5Gcreate1`, the renamed version of the function `H5Gcreate` from Release 1.6.x. The Release 1.8.0 function `H5Gcreate2` is available.	Yes
`--disable-deprecated-symbols`	1.8 Example: `H5Gcreate` is mapped to `H5Gcreate2`. `H5Gcreate1` is not available.	No
`--with-default-api-version=v16`	1.6 Example: `H5Gcreate` is mapped to `H5Gcreate1`. `H5Gcreate2` is available.	Yes
`--with-default-api-version=v18`	1.8 Example: `H5Gcreate` is mapped to `H5Gcreate2`. `H5Gcreate1` is available.	Varies

When building HDF5, the following configure flags control API-compatibility mode:

     Default All current and deprecated APIs are available.
Macros are mapped to the original version of each API. For example, the macro H5Gcreate is mapped to the function H5Gcreate1.
All API versions are available by version number. For example, an application can call either H5Gcreate1 or H5Gcreate2, depending on requirements.
This is the default behavior; no compatibility flag is required. However, the flag --enable-deprecated-symbols can be used to explicitly invoke this setting.

     --disable-deprecated-symbols Only current APIs are available.
Macros are mapped to the current version of each API. For example, in Release 1.8.0, the macro H5Gcreate is mapped to the function H5Gcreate2.
Since no deprecated APIs or symbols are included in the binary, H5Gcreate1 will be unavailable.
Usage:
./configure ... --disable-deprecated-symbols ...

     --with-default-api-version=v16   Macros are mapped to the Release 1.6 version of each API. For example, the macro H5Gcreate is mapped to the function H5Gcreate1.
APIs, symbols, and functionality that were introduced in the Release 1.8.x series will be included in the binary and will be directly callable, just not via the macros. For example, the Release 1.8.0 version of H5Gcreate will be available as H5Gcreate2.
Usage:
./configure ... --with-default-api-version=v16 ...

     --with-default-api-version=v18 Only HDF5 Release 1.6 APIs are available.
Macros are mapped to the Release 1.6 version of each API. For example, the macro H5Gcreate is mapped to the function H5Gcreate1.
Only APIs, symbols, or functionality that were available in the Release 1.6 series will be included in the binary, so H5Gcreate2 will be unavailable.
Usage:
./configure ... --with-default-api-version=v18 ...

     Examples Though there is some overlap in the functionality of these flags, they enable a full range of configurations. The following examples show how these flags can be combined. Note that in some cases, the same objective can be achieved with just one of the flags.
To build an instance of the HDF5 Library with the Release 1.6.x APIs fully available as the defaults:
./configure ... -- enable-deprecated-symbols      --with-default-api-version=v16 ...
To build an instance of the HDF5 Library with the Release 1.8.x APIs fully available as the defaults and Release 1.6.x symbols and APIs available through explicit calls:
./configure ... -- enable-deprecated-symbols      --with-default-api-version=v18 ...
To build an instance of the HDF5 Library with the Release 1.8.x APIs fully available as the defaults and with none of the deprecated Release 1.6.x symbols and APIs:
./configure ... -- disable-deprecated-symbols      --with-default-api-version=v18 ...

     Illegal combination This combination will result in an error either during configuration or at compile time as the first flag would eliminate all deprecated symbols, rendering implementation of the second flag impossible:
./configure ... -- disable-deprecated-symbols      --with-default-api-version=v16 ...

When building an HDF5 application, the following h5cc options control API-compatibility mode:

     Default
(no API-compatibility flags)   All current and deprecated HDF5 APIs are available in the application, providing maximum fexibility.
Macros are mapped to the current version of each API. For example, the macro H5Gcreate is mapped to the function H5Gcreate2.
All API versions are available by version number For example, an application can call either H5Gcreate1 or H5Gcreate2, depending on requirements.
Requires:
HDF5 Library built with no compatibility flags or with --enable-deprecated-symbols.
Usage:
h5cc ... <without any API-compatibility flag> ...
gcc ... <without any API-compatibility flag> ...

     -D H5_NO_DEPRECATED_SYMBOLS    Current release only; current HDF5 APIs only are available in the application.
Macros are mapped to the current version of each API. For example, in Release 1.8.0, the macro H5Gcreate is mapped to the function H5Gcreate2.
No deprecated APIs or symbols are included. In Release 1.8.0, for example, H5Gcreate1 will be unavailable.
Requires:
No special requirement; HDF5 Library may be built with no compatibility flags or with any legal combination.
Usage:
h5cc ... -D H5_NO_DEPRECATED_SYMBOLS ...
gcc ... -D H5_NO_DEPRECATED_SYMBOLS ...

     -D H5_USE_16_API Release 1.6 emulation; only HDF5 Release 1.6.x APIs are available.
Macros are mapped to the Release 1.6.x version of each API. For example, the macro H5Gcreate is mapped to the function H5Gcreate1.
Only APIs, symbols, or functionality that were available in the Release 1.6 series will be included in the binary. H5Gcreate2, for example, will be unavailable.
Requires:
HDF5 Library built with no compatibility flags, with --enable-deprecated-symbols, or with --with-default-api-version=v16.
Usage:
h5cc ... -D H5_USE_16_API ...
gcc ... -D H5_USE_16_API ...

Function-level settings
Function-level settings are determined only when the user application is built and installed.

In the cases where there are multiple versions of a function available, a high-level function macro can be selectively defined to point to any version of the function. For example, the macro H5Gcreate can be mapped to either of the functions H5Gcreate1 or H5Gcreate2. This is accomplished through a set of compilation flags that can be used when the application is compiled. For example:

If the flag H5Gcreate_vers is set to 1, the macro H5Gcreate will be mapped to H5Gcreate1.
h5cc ... -D H5Gcreate_vers=1 ...
gcc ... -D H5Gcreate_vers=1 ...
If the flag H5Gcreate_vers is set to 2, the macro H5Gcreate will be mapped to H5Gcreate2.
h5cc ... -D H5Gcreate_vers=2 ...
gcc ... -D H5Gcreate_vers=2 ...

As of Release 1.8.0, the following function macros are defined and can be mapped to the corresponding function versions by defining the version flags as indicated:

Macro	Underlying functions	Version flags
`H5Acreate`	`H5Acreate1` `H5Acreate2`	`H5Acreate_vers=1` `H5Acreate_vers=2`
`H5Adelete`	`H5Adelete1` `H5Adelete2`	`H5Adelete_vers=1` `H5Adelete_vers=2`
`H5Aiterate`	`H5Aiterate1` `H5Aiterate2`	`H5Aiterate_vers=1` `H5Aiterate_vers=2`
`H5Arename`	`H5Arename1` `H5Arename2`	`H5Arename_vers=1` `H5Arename_vers=2`
`H5Dcreate`	`H5Dcreate1` `H5Dcreate2`	`H5Dcreate_vers=1` `H5Dcreate_vers=2`
`H5Dopen`	`H5Dopen1` `H5Dopen2`	`H5Dopen_vers=1` `H5Dopen_vers=2`
`H5Eclear`	`H5Eclear1` `H5Eclear2`	`H5Eclear_vers=1` `H5Eclear_vers=2`
`H5Eprint`	`H5Eprint1` `H5Eprint2`	`H5Eprint_vers=1` `H5Eprint_vers=2`
`H5Epush`	`H5Epush1` `H5Epush2`	`H5Epush_vers=1` `H5Epush_vers=2`
`H5Eset_auto`	`H5Eset_auto1` `H5Eset_auto2`	`H5Eset_auto_vers=1` `H5Eset_auto_vers=2`
`H5Eget_auto`	`H5Eget_auto1` `H5Eget_auto2`	`H5Eget_auto_vers=1` `H5Eget_auto_vers=2`
`H5Ewalk`	`H5Ewalk1` `H5Ewalk2`	`H5Ewalk_vers=1` `H5Ewalk_vers=2`
`H5Gcreate`	`H5Gcreate1` `H5Gcreate2`	`H5Gcreate_vers=1` `H5Gcreate_vers=2`
`H5Gopen`	`H5Gopen1` `H5Gopen2`	`H5Gopen_vers=1` `H5Gopen_vers=2`
`H5Pget_filter`	`H5Pget_filter1` `H5Pget_filter2`	`H5Pget_filter_vers=1` `H5Pget_filter_vers=2`
`H5Pget_filter_by_id`	`H5Pget_filter_by_id1` `H5Pget_filter_by_id2`	`H5Pget_filter_by_id_vers=1` `H5Pget_filter_by_id_vers=2`
`H5Pinsert`	`H5Pinsert1` `H5Pinsert2`	`H5Pinsert_vers=1` `H5Pinsert_vers=2`
`H5Pregister`	`H5Pregister1` `H5Pregister2`	`H5Pregister_vers=1` `H5Pregister_vers=2`
`H5Rget_obj_type`	`H5Rget_obj_type1` `H5Rget_obj_type2`	`H5Rget_obj_type_vers=1` `H5Rget_obj_type_vers=2`
`H5Tarray_create`	`H5Tarray_create1` `H5Tarray_create2`	`H5Tarray_create_vers=1` `H5Tarray_create_vers=2`
`H5Tcommit`	`H5Tcommit1` `H5Tcommit2`	`H5Tcommit_vers=1` `H5Tcommit_vers=2`
`H5Tget_array_dims`	`H5Tget_array_dims1` `H5Tget_array_dims2`	`H5Tget_array_dims_vers=1` `H5Tget_array_dims_vers=2`
`H5Topen`	`H5Topen1` `H5Topen2`	`H5Topen_vers=1` `H5Topen_vers=2`

When building an HDF5 application, the following h5cc options control function-level API-compatibility:

-D H5Gcreate_vers=2 The macro H5Gcreate will be mapped to the function H5Gcreate2.

Note that the function-level settings require that HDF5 Library was built with an appropriate API-compatibility flag.

Note that the function-level settings do not negate any available functions; if H5Gcreate1 is available in the installed version of the HDF5 Library, it will remain available to the application as H5Gcreate1. Similarly, H5Gcreate2will remain available to the application as H5Gcreate2.

Common use case

Migrating an application to 1.8: [an outline; needs full text and context]

Start with global setting for 1.6 (-D H5_USE_16_API).
Move one function at a time (or sets of functions) to 1.8, setting function-level flags to 1.8 as you go (...-vers=[1,2]).
Then drop H5_USE_16_API; default h5cc app build will provide current APIs.
The set -D H5_NO_DEPRECATED_SYMBOLS and cleanup any failures to catch remaining update issues (e.g., H5Dextend versus H5Dset_extent).

HDF5 documents and links
Introduction to HDF5
HDF5 User Guide

THG Help Desk:

Describes HDF5 Release 1.8.0, January 2008.

	Default	All current and deprecated APIs are available. Macros are mapped to the original version of each API. For example, the macro `H5Gcreate` is mapped to the function `H5Gcreate1`. All API versions are available by version number. For example, an application can call either `H5Gcreate1` or `H5Gcreate2`, depending on requirements. This is the default behavior; no compatibility flag is required. However, the flag `--enable-deprecated-symbols` can be used to explicitly invoke this setting.
	`--disable-deprecated-symbols`	Only current APIs are available. Macros are mapped to the current version of each API. For example, in Release 1.8.0, the macro `H5Gcreate` is mapped to the function `H5Gcreate2`. Since no deprecated APIs or symbols are included in the binary, `H5Gcreate1` will be unavailable. Usage: `./configure ... --disable-deprecated-symbols ...`
	`--with-default-api-version=v16`	Macros are mapped to the Release 1.6 version of each API. For example, the macro `H5Gcreate` is mapped to the function `H5Gcreate1`. APIs, symbols, and functionality that were introduced in the Release 1.8.x series will be included in the binary and will be directly callable, just not via the macros. For example, the Release 1.8.0 version of `H5Gcreate` will be available as `H5Gcreate2`. Usage: `./configure ... --with-default-api-version=v16 ...`
	`--with-default-api-version=v18`	Only HDF5 Release 1.6 APIs are available. Macros are mapped to the Release 1.6 version of each API. For example, the macro `H5Gcreate` is mapped to the function `H5Gcreate1`. Only APIs, symbols, or functionality that were available in the Release 1.6 series will be included in the binary, so `H5Gcreate2` will be unavailable. Usage: `./configure ... --with-default-api-version=v18 ...`
	Examples	Though there is some overlap in the functionality of these flags, they enable a full range of configurations. The following examples show how these flags can be combined. Note that in some cases, the same objective can be achieved with just one of the flags. To build an instance of the HDF5 Library with the Release 1.6.x APIs fully available as the defaults: `./configure ... -- enable-deprecated-symbols --with-default-api-version=v16 ...` To build an instance of the HDF5 Library with the Release 1.8.x APIs fully available as the defaults and Release 1.6.x symbols and APIs available through explicit calls: `./configure ... -- enable-deprecated-symbols --with-default-api-version=v18 ...` To build an instance of the HDF5 Library with the Release 1.8.x APIs fully available as the defaults and with none of the deprecated Release 1.6.x symbols and APIs: `./configure ... -- disable-deprecated-symbols --with-default-api-version=v18 ...`
	Illegal combination	This combination will result in an error either during configuration or at compile time as the first flag would eliminate all deprecated symbols, rendering implementation of the second flag impossible: `./configure ... -- disable-deprecated-symbols --with-default-api-version=v16 ...`