summaryrefslogtreecommitdiffstats
path: root/doxygen/dox/api-compat-macros.dox
diff options
context:
space:
mode:
Diffstat (limited to 'doxygen/dox/api-compat-macros.dox')
-rw-r--r--doxygen/dox/api-compat-macros.dox898
1 files changed, 898 insertions, 0 deletions
diff --git a/doxygen/dox/api-compat-macros.dox b/doxygen/dox/api-compat-macros.dox
new file mode 100644
index 0000000..4a1578d
--- /dev/null
+++ b/doxygen/dox/api-compat-macros.dox
@@ -0,0 +1,898 @@
+/** \page api-compat-macros API Compatibility Macros
+
+ \section audience Audience
+ The target audience for this document has existing applications that use the
+ HDF5 library, and is considering moving to the latest HDF5 release to take
+ advantage of the latest library features and enhancements.
+
+ \section compat-issues Compatibility Issues
+ With each major release of HDF5, such as 1.12 or 1.10, certain compatibility
+ issues must be considered when migrating applications from an earlier major
+ release.
+
+ This document describes the approach taken by The HDF Group to help existing
+ users of HDF5 address compatibility issues in the HDF5 API.
+
+ \section summary Summary and Motivation
+ In response to new and evolving requirements for the library and data format,
+ several basic functions have changed since HDF5 was first released. To allow
+ existing applications to continue to compile and run properly, all versions
+ of these functions have been retained in the later releases of the HDF5 library.
+
+ Given the scope of changes available with each major release of HDF5, and
+ recognizing the potentially time-consuming task of editing all the affected
+ calls in user applications, The HDF Group has created a set of macros that
+ can be used to flexibly and easily map existing API calls to previous release
+ functions. We refer to these as the \Emph{API compatibility macros}.
+
+ The HDF Group generally encourages users to update applications to work with
+ the latest HDF5 library release so that all new features and enhancements are
+ available to them. At the same time, The HDF Group understands that, under
+ some circumstances, updating applications may not be feasible or necessary.
+ The API compatibility macros, described in this document, provide a bridge
+ from old APIs to new and can be particularly helpful in situations such as these:
+ <ul>
+ <li>Source code is not available - only binaries are available; updating the
+ application is not feasible.</li>
+ <li>Source code is available, but there are no resources to update it.</li>
+ <li>Source code is available, as are resources to update it, but the old
+ version works quite well so updates are not a priority. At the same time,
+ it is desirable to take advantage of certain efficiencies in the newer HDF5
+ release that do not require code changes.</li>
+ <li>Source code is available, as are resources to update it, but the applications
+ are large or complex, and must continue to run while the code updates are
+ carried out.</li>
+ </ul>
+
+ \section using Understanding and Using the Macros
+ As part of latest HDF5 release, several functions that existed in previous
+ versions of the library were updated with new calling parameters and given
+ new names. The updated versions of the functions have a number (for, e.g., '2')
+ at the end of the original function name. The original versions of these
+ functions were retained and renamed to have an earlier number (for, e.g., '1')
+ at the end of the original function name.
+
+ For example, consider the function \Code{H5Lvisit} in HDF5 release 1.10
+ as compared with 1.12:
+
+ <table>
+ <tr>
+ <th>Original function name and signature in 1.10.0</th>
+ <td colspan="1">
+ \Code{herr_t H5Lvisit(hid_t grp_id, H5_index_t idx_type, H5_iter_order_t order, H5L_iterate_t op, void *op_data)}
+ </td>
+ </tr>
+ <tr>
+ <th>Updated function and signature, introduced in release 1.12.0</th>
+ <td colspan="1">
+ \Code{herr_t H5Lvisit2(hid_t group_id, H5_index_t idx_type, H5_iter_order_t order, H5L_iterate2_t op, void *op_data)}
+ </td>
+ </tr>
+ <tr><th>Original function and signature, renamed in release 1.12.0</th>
+ <td colspan="1">
+ \Code{herr_t H5Lvisit1(hid_t group_id, H5_index_t idx_type, H5_iter_order_t order, H5L_iterate1_t op, void *op_data)}
+ </td>
+ </tr>
+ <tr><th>API compatibility macro, introduced in release 1.12.0</th>
+ <td colspan="1">
+ \Code{H5Lvisit}
+ <p>The macro, \Code{H5Lvisit}, will be mapped to either \Code{H5Lvisit1} or
+ \Code{H5Lvisit2}. The mapping is determined by a combination of the
+ configuration options use to build the HDF5 library and compile-time
+ options used to build the application. The calling parameters used with the
+ \Code{H5Lvisit} compatibility macro should match the number and type of the
+ function the macros will be mapped to (\Code{H5Lvisit1} or \Code{H5Lvisit2}).
+ </p>
+ <p>The function names ending in '1' or '2' are referred to as \Emph{versioned names},
+ and the corresponding functions are referred to as \Emph{versioned functions}.
+ For new code development, The HDF Group recommends use of the compatibility macro
+ mapped to the latest version of the function. The original version of the function
+ should be considered deprecated and, in general, should not be used when developing
+ new code.
+ </p>
+ </td>
+ </tr>
+ </table>
+
+ \section options Compatibility Macro Mapping Options
+ To determine the mapping for a given API compatibility macro in a given application,
+ a combination of user-controlled selections, collectively referred to as the
+ \Emph{compatibility macro mapping options}, is considered in the following sequence:
+
+ <table border="0" style="width: 100.0%;">
+ <tr>
+ <td valign="top" width="50%">
+ <ol>
+ <li>What compatibility macro configuration option was used to build the HDF5 library?
+ We refer to this selection as the \Emph{library mapping}.</li>
+ <li>Was a compatibility macro global compile-time option specified when the application
+ was built? We refer to this (optional) selection as the \Emph{application mapping}.
+ If an application mapping exists, it overrides the library mapping.
+ \Emph{(See adjacent notes.)}</li>
+ <li>Were any compatibility macro function-level compile-time options specified when the
+ application was built? We refer to these (optional) selections as \Emph{function mappings}.
+ If function mappings exist, they override library and application mappings for the
+ relevant API compatibility macros. \Emph{(See adjacent notes.)}</li>
+ </ol>
+ </td>
+ <td valign="top" width="50%">
+ <table border="1" cellpadding="10" style="width: 100.0%;">
+ <tr><td>
+ \Bold{Notes:} An application mapping can map APIs to the same version or to a version
+ older than the configured library mapping. When the application attempts to map APIs
+ to a newer version of the API than the library was configured with, it will fail to
+ "upgrade" the mapping (and may fail silently).
+
+ When it is necessary to "upgrade" the macro mappings from those set in the library mapping,
+ it must be done at the per-function level, using the function-level mappings. As long as
+ one does not try to map a function to a version that was compiled out in the library mapping,
+ individual functions can be upgraded or downgraded freely.
+ </td>
+ </tr>
+ </table>
+ </td>
+ </tr>
+ </table>
+
+ \subsection lib-options Library Mapping Options
+ When the HDF5 library is built, \Code{configure} flags can be used to control the API
+ compatibility macro mapping behavior exhibited by the library. This behavior can be
+ overridden by application and function mappings. One configure flag excludes deprecated
+ functions from the HDF5 library, making them unavailable to applications linked with the
+ library.
+
+ <div align="center">Table 1: Library Mapping Options
+ <table border="1" cellpadding="3">
+ <tr>
+ <th>\Code{configure} flag</th>
+ <th>Macros map to release <br/> (versioned function; \Code{H5Lvisit} shown)</th>
+ <th>Deprecated functions available? <br/> (\Code{H5Lvisit1})</th>
+ </tr>
+ <tr align="center">
+ <td>\Code{--with-default-api-version=v112} <br/> (the default in 1.12)</td>
+ <td>1.12.x (\Code{H5Lvisit2})</td>
+ <td>yes</td>
+ </tr>
+ <tr align="center">
+ <td align="left">\Code{--with-default-api-version=v110}</td>
+ <td>1.10.x (\Code{H5Lvisit1})</td>
+ <td>yes</td>
+ </tr>
+ <tr align="center">
+ <td align="left">\Code{--with-default-api-version=v18}</td>
+ <td>1.8.x (\Code{H5Lvisit1})</td>
+ <td>yes</td>
+ </tr>
+ <tr align="center">
+ <td align="left">\Code{--with-default-api-version=v16}</td>
+ <td>1.6.x (\Code{H5Lvisit1})</td>
+ <td>yes</td>
+ </tr>
+ <tr align="center">
+ <td align="left">\Code{--disable-deprecated-symbols}</td>
+ <td>1.12.x (\Code{H5Lvisit2})</td>
+ <td>no</td>
+ </tr>
+ </table>
+ </div>
+ Refer to the file \Code{libhdf5.settings} in the directory where the HDF5 library is
+ installed to determine the \Code{configure} flags used to build the library. In particular,
+ look for the two lines shown here under \Emph{Features}:
+
+ \Code{Default API mapping: v112}
+
+ \Code{With deprecated public symbols: yes}
+
+ \subsection app-options Application Mapping Options
+ When an application using HDF5 APIs is built and linked with the HDF5 library,
+ compile-time options to \Code{h5cc} can be used to control the API compatibility
+ macro mapping behavior exhibited by the application. The application mapping
+ overrides the behavior specified by the library mapping, and can be overridden
+ on a function-by-function basis by the function mappings.
+
+ If the HDF5 library was configured with the \Code{--disable-deprecated-symbols} flag, then
+ the deprecated functions will not be available, regardless of the application mapping options.
+
+ <div align="center">Table 2: Application Mapping Options
+ <table border="1" cellpadding="3">
+ <tr>
+ <th>\Code{h5cc} option</th>
+ <th>Macros map to release <br/>(versioned function; \Code{H5Lvisit} shown)</th>
+ <th>Deprecated functions available? <br/>(\Code{H5Lvisit1})</th>
+ </tr>
+ <tr align="center">
+ <td align="left">\Code{-DH5_USE_112_API} <br/> \Emph{(Default behavior if no option specified.)}</td>
+ <td>1.12.x (\Code{HLvisit2})</td>
+ <td>yes* <br/> \Emph{*if available in library}</td>
+ </tr>
+ <tr align="center">
+ <td align="left">\Code{-DH5_USE_110_API}</td>
+ <td>1.10.x (\Code{HLvisit1})</td>
+ <td>yes* <br/> \Emph{*if available in library}</td>
+ </tr>
+ <tr align="center">
+ <td align="left">\Code{-DH5_USE_18_API}</td>
+ <td>1.8.x (\Code{H5Lvisit1})</td>
+ <td>yes* <br/> \Emph{*if available in library}</td>
+ </tr>
+ <tr align="center">
+ <td align="left">\Code{-DH5_USE_16_API}</td>
+ <td>1.6.x (\Code{H5Lvisit1})</td>
+ <td>yes* <br/> \Emph{*if available in library}</td>
+ </tr>
+ <tr align="center">
+ <td align="left">\Code{-DH5_NO_DEPRECATED_SYMBOLS}</td>
+ <td>1.10.x (\Code{H5Lvisit1})</td>
+ <td>no</td>
+ </tr>
+ </table>
+ </div>
+
+ \subsection fun-options Function Mapping Options
+ Function mappings are specified when the application is built. These mappings
+ can be used to control the mapping of the API compatibility macros to
+ underlying functions on a function-by-function basis. The function mappings
+ override the library and application mappings discussed earlier.
+
+ If the HDF5 library was configured with the \Code{--disable-deprecated-symbols}
+ flag, or \Code{-DH5_NO_DEPRECATED_SYMBOLS} is used to compile the application,
+ then the deprecated functions will not be available, regardless of the function
+ mapping options.
+
+ For every function with multiple available versions, a compile-time version flag
+ can be defined to selectively map the function macro to the desired versioned
+ function. The function mapping consists of the function name followed by
+ &quot;\Code{_vers}&quot; which is mapped by number to a specific function or
+ struct:
+ <table>
+ <tr>
+ <th>Macro</th>
+ <th>Function Mapping</th>
+ <th>Mapped to function or struct</th>
+ </tr>
+ <tr><td>\Code{H5xxx}</td>
+ <td>\Code{H5xxx_vers=1}</td>
+ <td>\Code{H5xxx1}</td>
+ </tr>
+ <tr>
+ <td> </td>
+ <td>\Code{H5xxx_vers=2}</td>
+ <td>\Code{H5xxx2}</td>
+ </tr>
+ </table>
+
+ For example, in version 1.10 the \Code{H5Rreference} macro can be mapped to
+ either \Code{H5Rreference1} or \Code{H5Rreference2}. When used, the value of
+ the \Code{H5Rreference_vers} compile-time version flag determines which
+ function will be called:
+
+ <ul>
+ <li>When \Code{H5Rreference_vers} is set to \Code{1}, the macro \Code{H5Rreference}
+ will be mapped to \Code{H5Rreference1}. <br/>
+ \Code{H5cc ... -DH5Rreference_vers=1 ...}</li>
+ <li>When \Code{H5Rdereference_vers} is set to \Code{2}, the macro \Code{H5Rdereference}
+ will be mapped to \Code{H5Rdereference2}. <br/>
+ \Code{h5cc ... -DH5Rreference_vers=2 ...}</li>
+ <li>When \Code{H5Rreference_vers} is not set, the macro \Code{H5Rreference} will be
+ mapped to either \Code{H5Rreference1} or \Code{H5Rreference2}, based on the
+ application mapping, if one was specified, or on the library mapping. <br/>
+ \Code{h5cc ... }</li>
+ </ul>
+
+ \warning Please be aware that some function mappings use mapped structures, as
+ well. If compiling an application with a function mapping that uses
+ a mapped structure, you must include each function and mapped structure
+ plus EVERY function that uses the mapped structure, whether or not that
+ function is used in the application. \Emph{In 1.12, mappings of structures
+ are used by the H5L and H5O function mappings.}\n\n
+ For example, an application \Code{application.c} only calls \Code{H5Lvisit},
+ \Code{H5Ovisit}, and \Code{H5Oget_info_by_name}. To compile this application
+ with 1.10 APIs in 1.12 with the function specific mappings, then not only must
+ \Code{H5Lvisit_vers}, \Code{H5Ovisit_vers}, and \Code{H5Oget_info_by_name_vers}
+ be specified on the command line, but the mapped structures and every
+ function that uses the mapped structures must be included, as well.
+ The full compile line is shown below:
+ \code{.sh}
+ h5cc -DH5Lvisit_vers=1 -DH5Ovisit_vers=1 -DH5Oget_info_by_name_vers=1 \
+ -DH5Lvisit_by_name_vers=1 -DH5Literate_vers=1 \
+ -DH5Literate_by_name_vers= -DH5O_info_t_vers=1 -DH5L_info_t_vers=1 \
+ -DH5L_iterate_t_vers=1 -DH5Lget_info_by_idx_vers=1 \
+ -DH5Lget_info_vers=1 application.c
+ \endcode
+
+ \subsubsection fun-options-112 Function Mapping Options in Releases 1.12.x
+ <table>
+ <tr>
+ <th style="text-align: left;">Macro <br/> (\Code{H5xxx})</th>
+ <th>Default function used if no macro specified
+ <ul><li>Function/struct mapping:\Code{H5xxx_vers=N}</li></ul>
+ </th>
+ <th>Function used if specifying 1.10
+ <ul><li>Function/struct mapping: \Code{H5xxx_vers=1}</li></ul>
+ </th>
+ </tr>
+ <tr>
+ <td>H5Lget_info()</td>
+ <td>H5Lget_info2()
+ <ul>
+ <li>Function mapping:\Code{H5Lget_info_vers=2}</li>
+ <li>Struct mapping:\Code{H5L_info_t_vers=2}</li>
+ </ul>
+ </td>
+ <td>H5Lget_info1()
+ <ul>
+ <li>Function mapping \Code{H5Lget_info_vers=1}</li>
+ <li>Struct mapping: \Code{H5L_info_t_vers=1}</li>
+ </ul>
+ </td>
+ </tr>
+ <tr>
+ <td>H5Lget_info_by_idx()</td>
+ <td>H5Lget_info_by_idx2()
+ <ul>
+ <li>Function mapping: \Code{H5Lget_info_by_idx_vers=2}</li>
+ <li>Struct mapping: \Code{H5L_info_t_vers=2}</li>
+ </ul>
+ </td>
+ <td>H5Lget_info_by_idx1()
+ <ul>
+ <li>Function mapping: \Code{H5Lget_info_by_idx_vers=1}</li>
+ <li>Struct mapping: \Code{H5L_info_t_vers=1}</li>
+ </ul>
+ </td>
+ </tr>
+ <tr>
+ <td>H5Literate()</td>
+ <td>H5Literate2()
+ <ul>
+ <li>Function mapping: \Code{H5Literate_vers=2}</li>
+ <li>Struct mapping: \Code{H5L_iterate_t_vers=2}</li>
+ </ul>
+ </td>
+ <td>H5Literate1()
+ <ul>
+ <li>Function mapping: \Code{H5Literate_vers=1}</li>
+ <li>Struct mapping: \Code{H5L_iterate_t_vers=1}</li>
+ </ul>
+ </td>
+ </tr>
+ <tr>
+ <td>H5Literate_by_name()</td>
+ <td>H5Literate_by_name2()
+ <ul>
+ <li>Function mapping: \Code{H5Literate_by_name_vers=2}</li>
+ <li>Struct mapping: \Code{H5L_iterate_t_vers=2}</li>
+ </ul>
+ </td>
+ <td>H5Literate_by_name1()
+ <ul>
+ <li>Function mapping: \Code{H5Literate_by_name_vers=1}</li>
+ <li>Struct mapping: \Code{H5L_iterate_t_vers=1}</li>
+ </ul>
+ </td>
+ </tr>
+ <tr>
+ <td>H5Lvisit()</td>
+ <td>H5Lvisit2()
+ <ul>
+ <li>Function mapping: \Code{H5Lvisit_vers=2}</li>
+ <li>Struct mapping: \Code{H5L_iterate_t_vers=2}</li>
+ </ul>
+ </td>
+ <td>H5Lvisit1()
+ <ul>
+ <li>Function mapping: \Code{H5Lvisit_vers=1}</li>
+ <li>Struct mapping: \Code{H5L_iterate_t_vers=1}</li>
+ </ul>
+ </td>
+ </tr>
+ <tr>
+ <td>H5Lvisit_by_name()</td>
+ <td>H5Lvisit_by_name2()
+ <ul>
+ <li>Function mapping: \Code{H5Lvisit_by_name_vers=2}</li>
+ <li>Struct mapping: \Code{H5L_iterate_t_vers=2}</li>
+ </ul>
+ </td>
+ <td>H5Lvisit_by_name1()
+ <ul>
+ <li>Function mapping: \Code{H5Lvisit_by_name_vers=1}</li>
+ <li>Struct mapping: \Code{H5L_iterate_t_vers=1}</li>
+ </ul>
+ </td>
+ </tr>
+ <tr>
+ <td>H5Oget_info()</td>
+ <td>H5Oget_info3()
+ <ul>
+ <li>Function mapping: \Code{H5Oget_info_vers=3}</li>
+ <li>Struct mapping: \Code{H5O_info_t_vers=2}</li>
+ </ul>
+ </td>
+ <td>H5Oget_info1()
+ <ul>
+ <li>Function mapping: \Code{H5Oget_info_vers=1}</li>
+ <li>Struct mapping: \Code{H5O_info_t_vers=1}</li>
+ </ul>
+ </td>
+ </tr>
+ <tr>
+ <td>H5Oget_info_by_idx()</td>
+ <td>H5Oget_info_by_idx3()
+ <ul><li>Function mapping: \Code{H5Oget_info_by_idx_vers=3}</li>
+ <li>Struct mapping: \Code{H5O_info_t_vers=2}</li>
+ </ul>
+ </td>
+ <td>H5Oget_info_by_idx1()
+ <ul>
+ <li>Function mapping: \Code{H5Oget_info_by_idx_vers=1}</li>
+ <li>Struct mapping: \Code{H5O_info_t_vers=1}</li>
+ </ul>
+ </td>
+ </tr>
+ <tr>
+ <td>H5Oget_info_by_name()</td>
+ <td>H5Oget_info_by_name3()
+ <ul>
+ <li>Function mapping: \Code{H5O_get_info_by_name_vers=3}</li>
+ <li>Struct mapping: \Code{H5O_info_t_vers=2}</li>
+ </ul>
+ </td>
+ <td>H5Oget_info_by_name1()
+ <ul>
+ <li>Function mapping: \Code{H5O_get_info_by_name_vers=1}</li>
+ <li>Struct mapping: \Code{H5O_info_t_vers=1}</li>
+ </ul>
+ </td>
+ </tr>
+ <tr>
+ <td>H5Ovisit()</td>
+ <td>H5Ovisit3()
+ <ul>
+ <li>Function mapping: \Code{H5Ovisit_vers=3}</li>
+ <li>Struct mapping: \Code{H5O_iterate_t_vers=2}</li>
+ </ul>
+ </td>
+ <td>H5Ovisit1()
+ <ul><li>Function mapping: \Code{H5Ovisit_vers=1}</li>
+ <li>Struct mapping: \Code{H5O_iterate_t_vers=1}</li>
+ </ul>
+ </td>
+ </tr>
+ <tr>
+ <td>H5Ovisit_by_name()</td>
+ <td>H5Ovisit_by_name3()
+ <ul>
+ <li>Function mapping: \Code{H5Ovisit_by_name_vers=3}</li>
+ <li>Struct mapping: \Code{H5O_iterate_t_vers=2}</li>
+ </ul>
+ </td>
+ <td>H5Ovisit_by_name1()
+ <ul>
+ <li>Function mapping: \Code{H5Ovisit_by_name_vers=1}</li>
+ <li>Struct mapping: \Code{H5O_iterate_t_vers=1}</li>
+ </ul>
+ </td>
+ </tr>
+ <tr>
+ <td>H5Pencode()</td>
+ <td>H5Pencode2()
+ <ul>
+ <li>Function mapping: \Code{H5Pencode_vers=2}</li>
+ </ul>
+ </td>
+ <td>H5Pencode1()
+ <ul>
+ <li>Function mapping: \Code{H5Pencode_vers=1}</li>
+ </ul>
+ </td>
+ </tr>
+ <tr>
+ <td>H5Sencode()</td>
+ <td>H5Sencode2()
+ <ul>
+ <li>Function mapping: \Code{H5Sencode_vers=2}</li>
+ </ul>
+ </td>
+ <td>H5Sencode1()
+ <ul>
+ <li>Function mapping: \Code{H5Sencode_vers=1}</li>
+ </ul>
+ </td>
+ </tr>
+ </table>
+
+ \subsubsection fun-options-110 Function Mapping Options in Releases 1.10.x
+ <table>
+ <tr>
+ <th>Macro</th>
+ <th>Default function used <br/> <sub>(if no macro specified)</sub></th>
+ <th>Introduced in</th>
+ <th>\Code{h5cc} version flag and value</th>
+ <th>Mapped to function or struct</th>
+ </tr>
+ <tr>
+ <td rowspan="2">H5Rdereference()</td>
+ <td rowspan="2">H5Rdereference2()</td>
+ <td rowspan="2">HDF5-1.10.0</td>
+ <td>\Code{-DH5Rdereference_vers=1}</td>
+ <td>H5Rdereference1()</td>
+ </tr>
+ <tr>
+ <td>\Code{-DH5Rdereference_vers=2}</td>
+ <td>H5Rdereference2()</td>
+ </tr>
+ <tr>
+ <td rowspan="2">H5Fget_info()</td>
+ <td rowspan="2">H5Fget_info2()</td>
+ <td rowspan="2">HDF5-1.10.0</td>
+ <td>\Code{-DH5Fget_info_vers=1}</td>
+ <td>H5Fget_info1() with struct \ref H5F_info1_t</td>
+ </tr>
+ <tr>
+ <td>\Code{-DH5Fget_info_vers=2}</td>
+ <td>H5Fget_info2() with struct \ref H5F_info2_t</td>
+ </tr>
+ <tr>
+ <td rowspan="2">H5Oget_info()</td>
+ <td rowspan="2">H5Oget_info1()</td>
+ <td rowspan="2">HDF5-1.10.3</td>
+ <td>\Code{-DH5Oget_info_vers=1}</td>
+ <td>H5Oget_info1()</td>
+ </tr>
+ <tr>
+ <td>\Code{-DH5Oget_info_vers=2}</td>
+ <td>H5Oget_info2()</td>
+ </tr>
+ <tr>
+ <td rowspan="2">H5Oget_info_by_idx()</td>
+ <td rowspan="2">H5Oget_info_by_idx1()</td>
+ <td rowspan="2">HDF5-1.10.3</td>
+ <td>\Code{-DH5Oget_info_by_idx_vers=1}</td>
+ <td>H5Oget_info_by_idx1()</td>
+ </tr>
+ <tr>
+ <td>\Code{-DH5Oget_info_by_idx_vers=2}</td>
+ <td>H5Oget_info_by_idx2()</td>
+ </tr>
+ <tr>
+ <td rowspan="2">H5Oget_info_by_name()</td>
+ <td rowspan="2">H5Oget_info_by_name1()</td>
+ <td rowspan="2">HDF5-1.10.3</td>
+ <td>\Code{-DH5Oget_info_by_name_vers=1}</td>
+ <td>H5Oget_info_by_name1()</td>
+ </tr>
+ <tr>
+ <td>\Code{-DH5Oget_info_by_name_vers=2}</td>
+ <td>H5Oget_info_by_name2()</td>
+ </tr>
+ <tr>
+ <td rowspan="2">H5Ovisit()</td>
+ <td rowspan="2">H5Ovisit1()</td>
+ <td rowspan="2">HDF5-1.10.3</td>
+ <td>\Code{-DH5Ovisit_vers=1}</td>
+ <td>H5Ovisit1()</td>
+ </tr>
+ <tr>
+ <td>\Code{-DH5Ovisit_vers=2}</td>
+ <td>H5Ovisit2()</td>
+ </tr>
+ <tr>
+ <td rowspan="2">H5Ovisit_by_name()</td>
+ <td rowspan="2">H5Ovisit_by_name1()</td>
+ <td rowspan="2">HDF5-1.10.3</td>
+ <td>\Code{-DH5Ovisit_by_name_vers=1}</td>
+ <td>H5Ovisit_by_name1()</td>
+ </tr>
+ <tr>
+ <td>\Code{-DH5Ovisit_by_name_vers=2}</td>
+ <td>H5Ovisit_by_name2()</td>
+ </tr>
+ </table>
+
+ \subsubsection fun-options-18 Function Mapping Options in Releases 1.8.x
+ At release 1.8.0, the API compatibility macros, function mapping compile-time
+ version flags and values, and corresponding versioned functions listed in the
+ following table were introduced. If the application being compiled to run with
+ any 1.10.x release was written to use any 1.6.x release of HDF5, you must also
+ consider these macros and mapping options.
+
+ <div align="center">Table 5: Function Mapping Options in Releases 1.8.x
+ <table border="1" cellpadding="3" style="width: 90.0%;">
+ <tr>
+ <th>Macro</th>
+ <th><code>h5cc</code> version flag and value</th>
+ <th>Mapped to function <br/> or struct</th>
+ </tr>
+ <tr>
+ <td rowspan="2">H5Acreate()</td>
+ <td>\Code{DH5Acreate_vers=1}</td>
+ <td>H5Acreate1()</td>
+ </tr>
+ <tr>
+ <td>\Code{DH5Acreate_vers=2}</td>
+ <td>H5Acreate2()</td>
+ </tr>
+ <tr>
+ <td rowspan="2">H5Aiterate()</td>
+ <td>\Code{DH5Aiterate_vers=1}</td>
+ <td>H5Aiterate1() <br/> with struct \ref H5A_operator1_t</td>
+ </tr>
+ <tr>
+ <td>\Code{DH5Aiterate_vers=2}</td>
+ <td>H5Aiterate2() <br/> with struct \ref H5A_operator2_t</td>
+ </tr>
+ <tr>
+ <td rowspan="2">H5Dcreate()</td>
+ <td>\Code{DH5Dcreate_vers=1}</td>
+ <td>H5Dcreate1()</td>
+ </tr>
+ <tr>
+ <td>\Code{DH5Dcreate_vers=2}</td>
+ <td>H5Dcreate2()</td>
+ </tr>
+ <tr><td rowspan="2">H5Dopen()</td>
+ <td>\Code{DH5Dopen_vers=1}</td>
+ <td>H5Dopen1()</td>
+ </tr>
+ <tr>
+ <td>\Code{DH5Dopen_vers=2}</td>
+ <td>H5Dopen2()</td>
+ </tr>
+ <tr>
+ <td rowspan="2">H5Eclear()</td>
+ <td>\Code{DH5Eclear_vers=1}</td>
+ <td>H5Eclear1()</td>
+ </tr>
+ <tr>
+ <td>\Code{DH5Eclear_vers=2}</td>
+ <td>H5Eclear2()</td>
+ </tr>
+ <tr>
+ <td rowspan="2">H5Eprint()</td>
+ <td>\Code{DH5Eprint_vers=1}</td>
+ <td>H5Eprint1()</td>
+ </tr>
+ <tr>
+ <td>\Code{DH5Eprint_vers=2}</td>
+ <td>H5Eprint2()</td>
+ </tr>
+ <tr>
+ <td rowspan="2">H5Epush()</td>
+ <td>\Code{DH5Epush_vers=1}</td>
+ <td>H5Epush1()</td>
+ </tr>
+ <tr>
+ <td>\Code{DH5Epush_vers=2}</td>
+ <td>H5Epush2()</td>
+ </tr>
+ <tr>
+ <td rowspan="2">H5Eset_auto()</td>
+ <td>\Code{DH5Eset_auto_vers=1}</td>
+ <td>H5Eset_auto1()</td>
+ </tr>
+ <tr>
+ <td>\Code{DH5Eset_auto_vers=2}</td>
+ <td>H5Eset_auto2()</td>
+ </tr>
+ <tr>
+ <td rowspan="2">H5Eget_auto()</td>
+ <td>\Code{DH5Eget_auto_vers=1}</td>
+ <td>H5Eget_auto1()</td>
+ </tr>
+ <tr>
+ <td>\Code{DH5Eget_auto_vers=2}</td>
+ <td>H5Eget_auto2()</td>
+ </tr>
+ <tr>
+ <td rowspan="2">\ref H5E_auto_t <br/> struct for H5Eset_auto() <br/> and H5Eget_auto()</td>
+ <td>\Code{DH5E_auto_t_vers=1}</td>
+ <td>\ref H5E_auto1_t</td>
+ </tr>
+ <tr>
+ <td>\Code{DH5E_auto_t_vers=2}</td>
+ <td>\ref H5E_auto2_t</td>
+ </tr>
+ <tr>
+ <td rowspan="2">H5Ewalk()</td>
+ <td>\Code{DH5Ewalk_vers=1}</td>
+ <td>H5Ewalk1() <br/> with callback \ref H5E_walk1_t <br/> and struct \ref H5E_error1_t</td>
+ </tr>
+ <tr>
+ <td>\Code{DH5Ewalk_vers=2}</td>
+ <td>H5Ewalk2() <br/> with callback \ref H5E_walk2_t <br/> and struct \ref H5E_error2_t</td>
+ </tr>
+ <tr>
+ <td rowspan="2">H5Gcreate()</td>
+ <td>\Code{DH5Gcreate_vers=1}</td>
+ <td>H5Gcreate1()</td>
+ </tr>
+ <tr>
+ <td>\Code{DH5Gcreate_vers=2}</td>
+ <td>H5Gcreate2()</td>
+ </tr>
+ <tr>
+ <td rowspan="2">H5Gopen()</td>
+ <td>\Code{DH5Gopen_vers=1}</td>
+ <td>H5Gopen1()</td>
+ </tr>
+ <tr>
+ <td>\Code{DH5Gopen_vers=2}</td>
+ <td>H5Gopen2()</td>
+ </tr>
+ <tr>
+ <td rowspan="2">H5Pget_filter()</td>
+ <td>\Code{DH5Pget_filter_vers=1}</td>
+ <td>H5Pget_filter1()</td>
+ </tr>
+ <tr>
+ <td>\Code{DH5Pget_filter_vers=2}</td>
+ <td>H5Pget_filter2()</td>
+ </tr>
+ <tr>
+ <td rowspan="2">H5Pget_filter_by_id()</td>
+ <td>\Code{DH5Pget_filter_by_id_vers=1}</td>
+ <td>H5Pget_filter_by_id1()</td>
+ </tr>
+ <tr>
+ <td>\Code{DH5Pget_filter_by_id_vers=2}</td>
+ <td>H5Pget_filter_by_id2()</td>
+ </tr>
+ <tr>
+ <td rowspan="2">H5Pinsert()</td>
+ <td>\Code{DH5Pinsert_vers=1}</td>
+ <td>H5Pinsert1()</td>
+ </tr>
+ <tr>
+ <td>\Code{DH5Pinsert_vers=2}</td>
+ <td>H5Pinsert2()</td>
+ </tr>
+ <tr>
+ <td rowspan="2">H5Pregister()</td>
+ <td>\Code{DH5Pregister_vers=1}</td>
+ <td>H5Pregister1()</td>
+ </tr>
+ <tr>
+ <td>\Code{DH5Pregister_vers=2}</td>
+ <td>H5Pregister2()</td>
+ </tr>
+ <tr>
+ <td rowspan="2">H5Rget_obj_type()</td>
+ <td>\Code{DH5Rget_obj_typevers=1}</td>
+ <td>H5Rget_obj_type1()</td>
+ </tr>
+ <tr>
+ <td>\Code{DH5Rget_obj_type_vers=2}</td>
+ <td>H5Rget_obj_type2()</td>
+ </tr>
+ <tr>
+ <td rowspan="2">H5Tarray_create()</td>
+ <td>\Code{DH5Tarray_create_vers=1}</td>
+ <td>H5Tarray_create1()</td>
+ </tr>
+ <tr>
+ <td>\Code{DH5Tarray_create_vers=2}</td>
+ <td>H5Tarray_create2()</td>
+ </tr>
+ <tr>
+ <td rowspan="2">H5Tcommit()</td>
+ <td>\Code{DH5Tcommit_vers=1}</td>
+ <td>H5Tcommit1()</td>
+ </tr>
+ <tr>
+ <td>\Code{DH5Tcommit_vers=2}</td>
+ <td>H5Tcommit2()</td>
+ </tr>
+ <tr>
+ <td rowspan="2">H5Tget_array_dims()</td>
+ <td>\Code{DH5Tget_array_dims_vers=1}</td>
+ <td>H5Tget_array_dims1()</td>
+ </tr>
+ <tr>
+ <td>\Code{DH5Tget_array_dims_vers=2}</td>
+ <td>H5Tget_array_dims2()</td>
+ </tr>
+ <tr>
+ <td rowspan="2">H5Topen()</td>
+ <td>\Code{DH5Topen_vers=1}</td>
+ <td>H5Topen1()</td>
+ </tr>
+ <tr>
+ <td>\Code{DH5Topen_vers=2}</td>
+ <td>H5Topen2()</td>
+ </tr>
+ <tr>
+ <td rowspan="2">\ref H5Z_class_t struct for H5Zregister()</td>
+ <td>\Code{DH5Z_class_t_vers=1}</td>
+ <td>\ref H5Z_class1_t</td>
+ </tr>
+ <tr>
+ <td>\Code{DH5Z_class_t_vers=2}</td>
+ <td>\ref H5Z_class2_t</td>
+ </tr>
+ </table>
+ </div>
+
+ \subsubsection further Further Information
+ It is possible to specify multiple function mappings for a single application build:
+ \code{.sh}
+ h5cc ... -DH5Rdereference_vers=1 -DH5Fget_info_vers=2 ...
+ \endcode
+ As a result of the function and struct mappings in this compile example, all
+ occurrences of the macro \Code{H5Rdereference} will be mapped to \Code{H5Rdereference1}
+ and all occurrences of the macro \Code{H5Fget_info} will be mapped to \Code{H5Fget_info2}
+ for the application being built.
+
+ The function and struct mappings can be used to guarantee that a given API compatibility
+ macro will be mapped to the desired underlying function or struct version regardless of
+ the library or application mappings. In cases where an application may benefit greatly
+ from features offered by some of the later APIs, or must continue to use some earlier
+ API versions for compatibility reasons, this fine-grained control may be very important.
+
+ As noted earlier, the function mappings can only reference versioned functions that are
+ included in the HDF5 library, as determined by the configure flag used to build the
+ library. For example, if the HDF5 library being linked with the application was built
+ with the \Code{--disable-deprecated-symbols} option, version 1 of the underlying functions
+ would not be available, and the example above that defined \Code{H5Rdereference_vers=1}
+ would not be supported.
+
+ The function mappings do not negate any available functions. If \Code{H5Rdereference1}
+ is available in the installed version of the HDF5 library, and the application was not
+ compiled with the \Code{-DH5_NO_DEPRECATED_SYMBOLS} flag, the function \Code{H5Rdereference1}
+ will remain available to the application through its versioned name. Similarly,
+ \Code{H5Rdereference2} will remain available to the application as \Code{H5Rdereference2}.
+ The function mapping version flag \Code{H5Rdereference_vers} only controls the mapping of
+ the API compatibility macro \Code{H5Rdereference} to one of the two available functions.
+
+ This can be especially useful in any case where the programmer does not have direct control
+ over global macro definitions, such as when writing code meant to be copied to multiple
+ applications or when writing code in a header file.
+
+ \section macros Compatibility Macros in HDF5 1.6.8 and Later
+ A series of similar compatibility macros were introduced into the release 1.6
+ series of the library, starting with release 1.6.8. These macros simply alias the
+ '1' version functions, callbacks, and typedefs listed above to their original
+ non-numbered names.
+
+ These macros were strictly a forward-looking feature at that time; they were not
+ necessary for compatibility in 1.6.x. These macros were created at that time to
+ enable writing code that could be used with any version of the library after 1.6.8
+ and any library compilation options except \Code{H5_NO_DEPRECATED_SYMBOLS}, by always
+ using the '1' version of versioned functions and types. For example, \Code{H5Dopen1}
+ will always be interpreted in exactly the same manner by any version of the library
+ since 1.6.8.
+
+ \section use-case Common Use Case
+ A common scenario where the API compatibility macros may be helpful is the migration
+ of an existing application to a new HDF5 release. An incremental migration plan is
+ outlined here:
+ <ol>
+ <li>Build the HDF5 library without specifying any library mapping \Code{configure}
+ flag. In this default mode, the 1.6.x, 1.8.x, and 1.10.x versions of the
+ underlying functions are available, and the API compatibility macros will
+ be mapped to the current HDF5 versioned functions.</li>
+ <li>Compile the application with the \Code{-DH5_USE_NN_API} application mapping
+ option if it was written for use with an earlier HDF5 library. Because the
+ application mapping overrides the library mapping, the macros will all be
+ mapped to the earlier versions of the functions.</li>
+ <li>Remap one API compatibility macro at a time (or sets of macros), to use the
+ current HDF5 versions. At each stage, use the function mappings to map the macros
+ being worked on to the current versions. For example, use the
+ \Code{-DH5Rdereference_vers=2} version flag setting to remap the \Code{H5Rdereference}
+ macro to \Code{H5Rdereference2}, the 1.10.x version.
+
+ During this step, the application code will need to be modified to change the calling
+ parameters used with the API compatibility macros to match the number and type
+ of the 1.10.x versioned functions. The macro name, for example \Code{H5Rdereference},
+ should continue to be used in the code, to allow for possible re-mappings to later
+ versioned functions in a future release.</li>
+ <li>After all macros have been migrated to the latest versioned functions in step 3,
+ compile the application without any application or function mappings. This build
+ uses the library mappings set in step 1, and maps API compatibility macros to the
+ latest versions.</li>
+ <li>Finally, compile the application with the application mapping
+ \Code{-DH5_NO_DEPRECATED_SYMBOLS}, and address any failures to complete
+ the application migration process.</li>
+ </ol>
+
+ */ \ No newline at end of file