H4H5tools History
=================

This file contains development history of H4H5tools

7.		Release Information for H4H5TOOLS version 2.2.4
6.      Release Information for H4H5TOOLS version 2.2.3
5.      Release Information for H4H5TOOLS version 2.2.2
4.      Release Information for H4H5TOOLS version 2.2.1
3.      Release Information for H4H5TOOLS version 2.2.0
2.      Release Information for H4H5TOOLS version 2.1.1
1.      Release Information for H4H5TOOLS version 2.1

[Search on the string '%%%%' for per-release section breaks.]

%%%%2.2.4%%%%   
H4H5TOOLS version 2.2.4 released on 2018-09-13
================================================================================

1. Introduction
===============

This document describes the H4H5TOOLS and contains information on
the platforms tested and limitations. The H4H5TOOLS distribution includes
three products: H4toH5 conversion library, H4toH5 conversion utility,
and H5toH4 conversion utility.

Both the H4toH5 conversion library and the H4toH5 conversion utility follow
the HDF4 to HDF5 mapping document.  This document can be found at:
    https://portal.hdfgroup.org/display/HDF5/Mapping+HDF4+Objects+to+HDF5+Objects

The H4toH5 conversion library user guide and reference manual can be found at:
    https://portal.hdfgroup.org/display/support/h4h5+User%27s+Guide
    https://portal.hdfgroup.org/display/support/h4h5+Reference+Manual

If you have any questions or comments, please send them to:
    help@hdfgroup.org


2. Platforms Tested
===================
This release is tested with HDF4 v4.2.14 and HDF5 v1.8.21 and v1.10.4 on the following
platforms and compilers:

    Linux 2.6.32-696.16.1.el6.ppc64 gcc (GCC) 4.4.7 20120313 (Red Hat 4.4.7-18)
    #1 SMP ppc64 GNU/Linux        IBM XL C/C++ V13.1
    (ostrich)

    Linux 3.10.0-327.10.1.el7   GNU C (gcc)
    #1 SMP x86_64 GNU/Linux       compilers:
    (kituo/moohan)                Version 4.8.5 20150623 (Red Hat 4.8.5-4)
                                    Version 4.9.3, Version 5.2.0,
                                  Intel(R) C (icc)
                                  compilers:
                                     Version 17.0.0.098 Build 20160721

    SunOS 5.11 32- and 64-bit     Sun C 5.12 SunOS_sparc
    (emu)

    Windows 7                     Visual Studio 2015 (cmake)

    Windows 7 x64                 Visual Studio 2012 (cmake)
                                  Visual Studio 2013 (cmake)
                                  Visual Studio 2015 (cmake)
                                  Visual Studio 2015 w/ Intel C (cmake)

    Windows 10                    Visual Studio 2015 (cmake)

    Windows 10 x64                Visual Studio 2015 (cmake)
                                  Visual Studio 2017 (cmake)

    Mac OS X Yosemite 10.10.5     Apple clang/clang++ version 6.1 from Xcode 7.0
    64-bit
    (osx1010dev/osx1010test)      Intel icc version 15.0.3

    Mac OS X El Capitan 10.11.6   Apple clang/clang++ version 7.3.0 from Xcode 7.3
    64-bit
    (osx1011dev/osx1011test)      Intel icc version 16.0.2

    Mac OS Sierra 10.12.6         Apple LLVM version 8.1.0 (clang/clang++-802.0.42)
    64-bit
    (kite)                        Intel icc 17.0.2

2.1 Optional Feature
====================
The h4toh5 command-line utility, with the options (-eos -nc4 -nc4strict)
that can convert HDF-EOS2 to netCDF-4, is tested with HDF4 V4.2.14,
HDF5 1.8.21 and HDF5 1.10.3, HDF-EOS2 2.20, and ncdump from the netCDF 4.4.1.1 
distribution on the following platform and compiler:

   Linux 3.10 (x86_64), gcc 4.8.5
   Mac OS X EI Capitan 10.11.4 Apple LLVM version 7.3.0 (clang-703.0.29)
   MacOS X Sierra 10.12.6 Apple LLVM version 8.1.0 (clang-802.0.42)


3. New Features and Bug Fixes Since Version 2.2.3
=================================================
   Configuration
   -------------
    - CMake

      Update CMake commands configuration.

      A number of improvements were made to the CMake commands. Most
      changes simplify usage or eliminate unused constructs. Also,
      some changes support better cross-platform support. Changes
      follow from hdf5.

      (ADB - 2018/02/01, HDFFV-10398)

   Library
   -------
   - The HDF5 1.8.21 and HDF5 1.10.3 fix a bug that causes the failures of
     dumping the converted NASA AIRS and MODIS HDF5 files.

   Tools
   -----
   - When the HDF4 SDS has dimension names but doesn't specific the dimension 
     scales, the conversion tool will check if there is a 1-dimensional SDS 
     that shares the above mentioned dimension names; if yes, the conversion
     tool will use treat this SDS as the dimension scale. With this improvement,
     NASA MODIS level 1B products can be successfully converted to HDF5 files
     that follow the netCDF-4 data model. This option is only available for
     the default option(./h4toh5 M1.hdf M1.h5).
     

   Documentation
   -------------
   - No major update


4. Known problems
=================

   - [None]

5. Optional HDF-EOS2/netCDF-4 Verifier
======================================
An optional HDF-EOS2/netCDF-4 verifier utility is available with the
2.2.3 release in the subdirectory misc/verify_eos2nc4/.  See the
README.txt file under that directory.

6. Limitations
==============
1. h4toh5: For the option -na(h4toh5 -na), if a dimension name is assigned to 
           an HDF4 SDS dimension, that dimension must have a dimension scale.
           Otherwise, an error will be generated.
2. h5toh4: Check the h5toh4_limitation.txt under /release_docs.



CMake vs. Autotools installations
=================================
While both build systems produce similar results, there are differences.
Each system produces the same set of folders on linux (only CMake works
on standard Windows); bin, include, lib and share. Autotools places the
COPYING and RELEASE.txt file in the root folder, CMake places them in
the share folder.

The bin folder contains the tools and the build scripts (autotools only).
Additionally, CMake creates dynamic versions of the tools with the suffix
"-shared". Autotools installs one set of tools depending on the
"--enable-shared" configuration option.
  build scripts
  -------------
  Autotools: h4h5cc

The include folder holds the header files.

The lib folder contains the library files.

The share folder will have the most differences because CMake builds include
a number of CMake specific files for support of CMake's find_package and support
for the H4H5 Examples CMake package.

%%%%2.2.3%%%%   
H4H5TOOLS version 2.2.3 released on 2017-09-08.
================================================================================

1. Introduction
===============

This document describes the H4H5TOOLS and contains information on
the platforms tested and limitations. The H4H5TOOLS distribution includes
three products: H4toH5 conversion library, H4toH5 conversion utility,
and H5toH4 conversion utility.

Both the H4toH5 conversion library and the H4toH5 conversion utility follow
the HDF4 to HDF5 mapping document.  This document can be found at:
    https://support.hdfgroup.org/HDF5/doc/ADGuide/H4toH5Mapping.pdf

The H4toH5 conversion library user guide and reference manual can be found at:
    https://support.hdfgroup.org/ftp/HDF5/h4toh5/src/unpacked/doc/h4toh5lib_UG.pdf
    https://support.hdfgroup.org/ftp/HDF5/h4toh5/src/unpacked/doc/h4toh5lib_RM.pdf

If you have any questions or comments, please send them to:
    help@hdfgroup.org


2. Platforms Tested
===================
This release is tested with HDF4 v4.2.13 and HDF5 v1.8.19 and v1.10.1 on the following
platforms and compilers:

   Linux 2.6 (x86_64), gcc 4.4.7
   Linux 2.6 (ppc64), gcc 4.4.7
   Linux 3.10 (x86_64), gcc 4.8.5
   Mac OS X Mavericks 10.9.5   Apple LLVM version 6.0   (clang-600.0.57)
   Mac OS X Yosemite 10.10.5   Apple LLVM version 6.1.0 (clang-602.0.53)
   Mac OS X EI Capitan 10.11.4 Apple LLVM version 7.3.0 (clang-703.0.29)
   SunOS 5.11, 32/64bits (sun4u), Sun C 5.12

   Windows 7                     Visual Studio 2012
                                 Visual Studio 2013
                                 Visual Studio 2015

   Windows 7 x64                 Visual Studio 2012
                                 Visual Studio 2013
                                 Visual Studio 2015

   Windows 10                    Visual Studio 2015

   Windows 10 x64                Visual Studio 2015

2.1 Optional Feature
====================
The h4toh5 command-line utility, with the options (-eos -nc4 -nc4strict)
that can convert HDF-EOS2 to netCDF-4, is tested with HDF4 V4.2.13,
HDF5 1.8.19, HDF-EOS2 2.19, and ncdump from the netCDF 4.4.1.1 distribution
on the following platform and compiler:

   Linux 3.10 (x86_64), gcc 4.8.5
   Mac OS X EI Capitan 10.11.4 Apple LLVM version 7.3.0 (clang-703.0.29)


3. New Features and Bug Fixes Since Version 2.2.2
=================================================
   Configuration
   -------------
   - [None]

   Library
   -------
   - Fix all the memory leakings discovered the valgrind run of the testsuite.
   - Add more testing files to test the conversion of SDS by following
     the HDF5 dimension scale specification.

   Tools
   -----
   - h4toh5 follows the HDF5 dimension scale specification to handle HDF4 SDS
     dimensions.
   - h4toh5 adds an option to support the conversion of 1 field vdata to HDF5
     dataset with the atomic datatype
   - h4toh5 uses the latest HDF4 APIs to retrieve the compression information
     for SDS and GR.
   - h4toh5 uses HDF5 variable length string to store palette names.
   - h4toh5 -eos option, fixes a bug that causes the segmentation fault of
     conversion of 1-D HDF-EOS2 swath.
   - h4toh5, add more testing files to test the conversion of SDS by following
     the HDF5 dimension scale specification.
   - h4toh5, add one testing file to test the option to convert 1 field vdata
     to an HDF5 dataset of atomic datatype.
   - Fix all the memory leakings for both h4toh5 and h5toh4 utilities discovered
     by the valgrind run of the testsuite.
   - Update the toolkit to compile and run with the HDF5 1.10 release.
   - h5h4.c file in function convert_dataset and convert_table the
     H5Tget_member_name must use the H5free_memory() to release the
     fieldame resource on Windows.

   Documentation
   -------------
   - H4toH5 mapping document is updated to version 4. The main part is to provide
     the mapping of SDS dimensions to HDF5 by following the HDF5 dimension scale
     specification.
   - The limitation of h5toh4 is documented in the h5toh4_limitation.txt under
     the directory release_docs.


4. Known problems
=================

   - [None]

5. Optional HDF-EOS2/netCDF-4 Verifier
======================================
An optional HDF-EOS2/netCDF-4 verifier utility is available with the
2.2.3 release in the subdirectory misc/verify_eos2nc4/.  See the
README.txt file under that directory.


%%%%2.2.2%%%%   

H4H5TOOLS version 2.2.2 released on 2013-07-26
================================================================================

1. Introduction
===============

This document describes the H4H5TOOLS and contains information on 
the platforms tested and limitations. The H4H5TOOLS distribution includes
three products: H4toH5 conversion library, H4toH5 conversion utility,
and H5toH4 conversion utility.

Both the H4toH5 conversion library and the H4toH5 conversion utility follow 
the HDF4 to HDF5 mapping document.  This document can be found at:
    http://hdfgroup.org/HDF5/doc/ADGuide/H4toH5Mapping.pdf

The H4toH5 conversion library user guide and reference manual can be found at:
    http://hdfgroup.org/h4toh5/h4toh5lib_UG.pdf
    http://hdfgroup.org/h4toh5/h4toh5lib_RM.pdf

If you have any questions or comments, please send them to:
    help@hdfgroup.org


2. Platforms Tested
===================
This release is tested with HDF4 v4.2.9 and HDF5 v1.8.11 on the following
platforms and compilers:

   Linux 2.6 (i686), gcc 4.1.2
   Linux 2.6 (x86_64), gcc 4.1.2
   Linux 2.6 (ppc64), gcc 4.4.7
   SunOS 5.11, 32/64bits (sun4u), Sun C 5.12

CMake was tested with HDF4 v4.2.9 and HDF5 v1.8.11 on the following platforms:

    Windows 7                     Visual Studio 2008
                                  Visual Studio 2010
                                  Visual Studio 2012

    Windows 7 x64                 Visual Studio 2008
                                  Visual Studio 2010
                                  Visual Studio 2012

2.1 Optional Feature
====================
The h4toh5 command-line utility, with the options (-eos -nc4 -nc4strict) 
that can convert HDF-EOS2 to netCDF-4, is tested with HDF4 V4.2.9, 
HDF5 1.8.11, HDF-EOS2 2.18, and ncdump from the netCDF 4.2.1.1 distribution
on the following platform and compiler:

   Linux 2.6 (i686), gcc 4.1.2


3. New Features and Bug Fixes Since Version 2.2.1
=================================================
   Configuration
   -------------
   - Configure has been improved to find other libraries on which the HDF5 library
     depends (uses). It consults the file libhdf5.la in the same directory
     where the HDF5 Library resides. This also fixes the previously known problem
     where the h4cc compiler command does not link the -lm library.
     (AKC 2013-07-23 HFRHFVTOOLS-74 and HFRHFVTOOLS-79).

   Library
   -------
   - [None]

   Tools
   -----
   - For the HDF5 compound datatype mapping of the h5toh4 conversion tool, 
     the map of fixed-size HDF5 string to HDF4 char type was added.
   - A new HDF5 testing file and the corresponding expected output were also
     added. (KY -2012-07-18)
    
   Documentation
   -------------
   - [None]


4. Known problems
=================
   - The srcdir build option doesn't work with this distribution; 
     see Bugzilla #1798 (EIP, 2010-02-25, OTHER-8)


5. Optional HDF-EOS2/netCDF-4 Verifier
======================================
An optional HDF-EOS2/netCDF-4 verifier utility is available with the
2.2.2. release in the subdirectory misc/verify_eos2nc4/.  See the 
README.txt file in that directory.


%%%%2.2.1%%%%   

H4H5TOOLS version 2.2.1 released on 2012-02-15.
================================================================================

1. Introduction
===============

This document describes the H4H5TOOLS and contains information on 
the platforms tested and limitations. The H4H5TOOLS distribution includes
three products: H4toH5 conversion library, H4toH5 conversion utility,
and H5toH4 conversion utility.

Both the H4toH5 conversion library and the H4toH5 conversion utility follow 
the HDF4 to HDF5 mapping document.  This document can be found at:
    http://hdfgroup.org/HDF5/doc/ADGuide/H4toH5Mapping.pdf

The H4toH5 conversion library user guide and reference manual can be found at:
    http://hdfgroup.org/h4toh5/h4toh5lib_UG.pdf
    http://hdfgroup.org/h4toh5/h4toh5lib_RM.pdf

If you have any questions or comments, please send them to:
    help@hdfgroup.org


2. Platforms Tested
===================
This release is tested with HDF4 v4.2.7 and HDF5 v1.8.8 on the following
platforms and compilers:

   Linux 2.6 (i686), gcc 4.1.2
   Linux 2.6 (x86_64), gcc 4.1.2
   Linux 2.6 (ppc64), gcc 4.4.6
   SunOS 5.10, 32/64bits (sun4u), Sun C 5.9
   Microsoft Windows XP 32/64, Visual Studio 2008*

CMake was tested with HDF4 v4.2.7 and HDF5 v1.8.8 on the following platforms:

   Windows XP                    Visual Studio 2008*
                                 Visual Studio 2010
   Windows XP x64                Visual Studio 2008*
                                 Visual Studio 2010
   Windows 7                     Visual Studio 2008*
   Windows 7 x64                 Visual Studio 2008*

*Note: Visual Studio 2008 will not be tested after this release (v2.2.1).

The h4toh5 command-line utility, with the options (-eos -nc4 -nc4strict) 
that can convert HDF-EOS2 to netCDF-4, is tested with HDF4 V4.2.7, 
HDF5 1.8.8, HDF-EOS2 2.17, and ncdump from the netCDF 4.1.2 distribution
on the following platform and compiler:

   Linux 2.6 (i686), gcc 4.1.2


3. New features and bug fixes since Version 2.2.0
=================================================
   Configuration
   -------------
   - Remove the dependency for the preprocessor option,
     CPPFLAGS=-DH5_USE_16_API, if using HDF5 1.8 or higher. (LD, KY -2011-12-20)

   Library
   -------
   - Remove the macro LIBH4TOH5_VERSION from h4toh5main.c and h4toh5util.h
     since it is not used to output the version number (KY -2011-12-22)

   Tools
   -----
   - Update expected output HDF4 files for the h5toh4 conversion utility
     based on the bug fix of the HDF5 image conversion. (KY - 2011-12-22)
   - Update expected output HDF5 files for the -eos2 option of the h4toh5 
     conversion utility with HDF5 1.8.7. (LD,KY -2011-12-20)
   - Starting with version 2.2.1, the -nc4 and -nc4fakedim options for
     converting HDF-EOS2 to netCDF-4 is no longer supported.  
    
   Documentation
   -------------
   - Entries have been added in the Reference Manual for the command-line 
     utilities 'h4toh5' and 'h5toh4'.


4. Known problems
=================
   - configure sometimes failed with the following message:
       checking for H5open in -lhdf5... no
       configure: error: cannot find HDF5 library.
     This was due to libhdf5.a uses functions in libm.a. The h4cc usually has
     -lm included but some newer compilers (e.g., gcc v4.4.x) decides,
     correctly, h4cc does not need -lm and does not include -lm in the
     generated h4cc.  One way to go around this error is by adding -lm to $CC
     when running configure. E.g.,
	env CC="/usr/local/hdf4/h4cc -lm" ./configure --with-hdf5=<hdf5libpath>
    This problem will be fixed in the next release. (AC, 2012-02-13)
   - Windows linking issues with non-CMake builds of HDF5 library. Usual error
     reported is that timezone structure cannot be found. (ADB, 2012-02-13)
   - The srcdir build option doesn't work with this distribution; 
     see Bugzilla #1798 (EIP, 2010-02-25)


5. Optional HDF-EOS2/netCDF-4 Verifier
======================================
An optional HDF-EOS2/netCDF-4 verifier utility is available with this
distribution in the subdirectory misc/verify_eos2nc4/.  See the file
README.txt in that directory.

%%%%2.2.0%%%%   

H4H5TOOLS version 2.2.0 released on 2011-06-29.
================================================================================

1. Introduction
===============

This document describes the H4H5TOOLS and contains information on 
the platforms tested and limitations. The H4H5TOOLS deistribution includes
three products: H4toH5 conversion library, H4toH5 conversion utility,
and H5toH4 conversion utility.

Both the H4toH5 conversion library and the H4toH5 conversion utility follow 
the HDF4 to HDF5 mapping document.  This document can be found at:
    http://hdfgroup.org/HDF5/doc/ADGuide/H4toH5Mapping.pdf

The H4toH5 conversion library user guide and reference manual can be found at:
    http://hdfgroup.org/h4toh5/h4toh5lib_UG.pdf
    http://hdfgroup.org/h4toh5/h4toh5lib_RM.pdf

If you have any questions or comments, please send them to:
    help@hdfgroup.org


2. Platforms Tested
===================
This release is tested with HDF4 v4.2.6 and HDF5 v1.6.10 or v1.8.7* on the
following platforms and compilers:

   Linux 2.6 (i686), gcc 4.1.2
   Linux 2.6 (x86_64), gcc 4.1.2
   SunOS 5.10, 32/64bits (sun4u), Sun C 5.9
   Microsoft Windows XP 32/64, Visual Studio 2008

CMake was tested with HDF4 v4.2.6 and HDF5 v1.8.7 (H5_USE_16_API used) on 
the following platforms:

   Windows XP                    Visual Studio 2008
                                 Visual Studio 2010
   Windows XP x64                Visual Studio 2008
                                 Visual Studio 2010
   Windows 7                     Visual Studio 2008
   Windows 7 x64                 Visual Studio 2008

The h4toh5 command-line utility, with the option (-eos -nc4 -nc4strict) 
that can convert HDF-EOS2 to netCDF-4, is tested with HDF4 V4.2.6, 
HDF5 1.8.7*, HDF-EOS2 2.17, and ncdump from the netCDF 4.1.2 distribution
on the following platform and compiler:
   Linux 2.6 (i686), gcc 4.1.2

* Note that if you use HDF5 v1.8.0 or higher, H5_USE_16_API must be defined.
  See INSTALL_Unix.txt for details.


3. New features and bug fixes since Version 2.1.1
=================================================
   Configuration
   -------------
   - CMake Support: This release adds support for building H4H5TOOLS using
     the CMake system. Initial work has targeted Windows, but other platforms
     can be used. See the CMake.TXT file for more information. Version
     2.8.4 of CMake is required. (ADB, 2011/06/27)

   Library
   -------
   - Some HDF4 files have vgroup names with the length bigger than 
     VGNAMELENMAX, the maximum size the old HDF4 library allowed. Since the 
     h4toh5 conversion tool used VGNAMELENMAX, it caused a memory buffer 
     overrun for those files.  The current version of the conversion tool 
     uses the new HDF4 APIs (in hdf4.2.5) Vgetnamelen and Vgetclassnamelen to 
     obtain the length of vgroup and class names and to allocate a buffer of 
     the appropriate size. (KY, 2010/07/01)

   Tools
   -----
   - Update h4toh5, h5toh4, and h4toh5test to exit status to EXIT_SUCCESS(0)
     if succeeded; otherwise EXIT_FAILURE(1). (AKC, 2011/01/19)

4. Known problems
=================
   - CMake fails to build static executables on linux_x64. (ADB, 2011-06-28)
     
   - the srcdir build option doesn't work with this distribution; 
     see Bugzilla #1798 (EIP, 2010-02-25)

5. Optional HDF-EOS2/netCDF-4 Verifier
======================================
An optional HDF-EOS2/netCDF-4 verifier utility is available with this
distribution in the subdirectory misc/verify_eos2nc4/.  See the file
README.txt in that directory.


%%%%2.1.1%%%%   

H4H5TOOLS version 2.1.1 released on February 25, 2010

1. Introduction
===============

This document describes the H4H5TOOLS and contains information on 
the platforms tested and limitations. H4H5TOOLS include three products, 
H4toH5 conversion library, H4toH5 conversion utility and H5toH4 
conversion utility.

Both H4toH5 conversion library and H4toH5 conversion utility follow HDF4 to 
HDF5 mapping document.  This document can be found at:
http://hdfgroup.com/HDF5/doc/ADGuide/H4toH5Mapping.pdf

The H4toH5 conversion library user's guide and reference manual can be 
found at:
http://hdfgroup.com/h4toh5/h4toh5lib_UG.pdf
http://hdfgroup.com/h4toh5/h4toh5lib_RM.pdf

If you have any questions or comments, please send them to:
help@hdfgroup.org


2. Platforms Tested
===================
This release was tested with HDF 4.2.5 and HDF5 1.8.4-patch1 on the following 
platforms and compilers:
   GNU/Linux(x86), gcc 4.1.2
   GNU/Linux(x86_64),gcc 4.1.2
   SunOS 5.10, Sun C 5.9
   Microsoft Windows XP 32/64, Visual Studio 2005/2008
   Mac OSX Intel, gcc 4.2.1
The optionally HDF-EOS2/netCDF-4 verifier has been tested on the following
platforms and compilers:
    GNU/Linux(x86), gcc 4.1.2
    GNU/Linux(x86_64),gcc 4.1.2
    SunOS 5.10, Sun C 5.9
  

3. New features  and bug fixes (Version 2.1.1)
==============================================
 1) Configuration
    - Updated versions of autotools used to generate configure
      and Makefile.in template files. Versions are as follows:
      Autoconf 2.65
      Automake 1.11.1

 2) - Updated windows project files for 64-bit Windows. Also added script to
      build the library and utilities from the command line.
 
 3) Bug fixes since Verison 2.1
    None

4. Known problems
=================
   1) srcdir build option doesn't work with this distribution; 
      see Bugzilla #1798 (EIP 2010-02-25)

%%%%2.1%%%%   

H4H5TOOLS version 2.1 released in February 2009

1. Introduction

This document describes the H4H5TOOLS and contains information on 
the platforms tested and limitations. H4H5TOOLS include three products, 
H4toH5 conversion library, H4toH5 conversion utility and H5toH4 
conversion utility.

Both H4toH5 conversion library and H4toH5 conversion utility follow HDF4 to 
HDF5 mapping document.  This document can be found at:
http://hdfgroup.com/HDF5/doc/ADGuide/H4toH5Mapping.pdf

The H4toH5 conversion library user's guide and reference manual can be 
found at:
http://hdfgroup.com/h4toh5/h4toh5lib_UG.pdf
http://hdfgroup.com/h4toh5/h4toh5lib_RM.pdf

If you have any questions or comments, please send them to:
help@hdfgroup.org


2. Platforms Tested

H4H5TOOLS have been tested on the following platforms and compilers:
   GNU/Linux(x86), gcc 4.1.2
   GNU/Linux(x86_64),gcc 4.1.2
   SunOS 5.10, cc 5.8
   SGI IRIX64 6.5 MIPSpro Compilers: Version 7.4.4m
   SGI Altix, Intel C Compiler 10.1 (IA-64)
   Microsoft Windows xp, Visual Studio 2005 (x86)
The optionally HDF-EOS2/netCDF-4 verifier has been tested on the following
platforms and compilers:
    GNU/Linux(x86), gcc 4.1.2
    GNU/Linux(x86_64),gcc 4.1.2
    SunOS 5.10, cc 5.8
  

3. Prerequisites

1) HDF4 (version 4.2r4) and supported libraries 
2) HDF5 (version 1.8.2 or higher) library
3) Optionally, if one wants to use dynamically-linked(shared) HDF5 library, 
   the absolute path of HDF5 library may need to  be added to LD_LIBRARY_PATH 
4) Optionally, if one built either HDF4 or HDF5 libraries with 
   dynamically-linked(shared) SZIP library, the absolute path of SZIP library
   may need to be added to in LD_LIBRARY_PATH 
5) Optionally, if one wants to convert HDF-EOS2 files to HDF5/NetCDF4 files,
   HDF-EOS2 (version 2.15 or higher) library is needed.
6) Optionally, if one wants to build HDF-EOS2/netCDF-4 verifier, 
   Both HDF-EOS2 and netCDF-4(version 4.0 or higher) is needed. 

4. Install  

Unix install: see INSTALL_Unix.txt
Windows XP install: see INSTALL_Windows.txt 
(see h4h5proj.zip in the windows directory)

5. New features (Version 2.1)
 1) General Enhancement
   a) The maximum length of HDF5 attribute is 64K byte for HDF5 1.6 or eariler. However, 
      we find that the length of some attribute is longer than 64K byte. If
      case happens, h4toh5 splits it into several HDF5 attributes.
   b) Conversion is performed more quickly with less memory.
 2) Enhancement related to converting HDF-EOS2 files to NetCDF4/HDF5 files
   a) h4toh5  allows HDF-EOS2 grid files where 'XDim' and 'YDim' have
      actual lon/lat values to be converted. Usually, 'XDim' and 'YDim' are empty because
      values can be calculated using HDF-EOS2 API. When these are not empty,
      h4toh5 verifies values and keeps converting.
   b) h4toh5 allows unusual HDF-EOS2 grid files where 'nlon' and 'nlat' are
      used in lieu of 'XDim' and 'YDim' to be converted. If 'XDim' and 'YDim' are not associated
      with any fields, h4toh5 checks if 'nlon' and 'nlat' are used instead.
      This enhancement produces semantically correct HDF5 files.
   c) h4toh5 preserves the fill value by converting or generating _FillValue
      attribute that netCDF-4 recognizes.
   d) h4toh5 reduces the possibility of name clash by putting HDF-EOS2 dimensions
      in the group equivalent to the given HDF-EOS2 grid.
   f) h4toh5 allows HDF-EOS2 swath files that have one-dimensional Longitude
      Latitude to be converted. They are usually two-dimensional.
   g) h4toh5 can create fake dimensions for hybrid files that have SDS that do
      not belong to the HDF-EOS2 structure.

 3) Bug fixes
   a) An HDF4 SDS that has an unlimited dimension but no elements was not
      always converted unless HDF-EOS2 conversion is specified. This was
      fixed, and h4toh5 also guess a fine HDF5 chunk size.
   b) When Vdata is empty, h4toh5 failed to convert it. Fixed.
   c) One argument of GDfieldinfo() and SWfieldinfo() was too short, and it
      may result in buffer overrun. The buffer size is now 512 as one
      HDF-EOS2 developer recommended.
   d) The buffer size for reference numbers was too small, which may
      result in buffer overrun. The buffer size was increased.
   e) When the chunk size is larger than the actual number of elements,
      h4toh5 has failed to convert because HDF5 does not allow this. Now,
      h4toh5 forces the chunk size to be equal to or smaller than the
      number of elements.
   f) H4H5TOOLS has not been built if HDF4 is built with --disable-netcdf
      option because h4toh5 uses MAX_VAR_DIMS and MAX_NC_NAME, which are
      defined only if netcdf interface is enabled. They are replaced by
      H4_MAX_VAR_DIMS and FIELDNAMELENMAX, respectively.
   g) Dimension scales in Empty SDS have not been converted. Fixed.
   h) h4toh5 has modified object names only if an object name slashes.
      This may be fine, but netCDF-4 can reject the generated HDF5 file due to
      some symbols in object names. Now, h4toh5 makes all object names
      [_a-zA-Z][_a-zA-Z0-9]*. This makes 'Data Fields' become 'Data_Fields'.
   i) HDF-EOS2 fields of character type have been converted into HDF5 datasets
      of SCALAR space. This made netCDF-4 reject the generated HDF5 file. Now,
      SIMPLE space is used.
   j) If HDF-EOS2 dimensions are never associated, they have not been
      converted. Fixed.
   k) REFERENCE_LIST attribute required by HDF5 Dimension Specification was not
      always stored. Fixed.

 4) Others 
   a) H4H5TOOLS includes a tool that checks if the generated netCDF-4-compliant
      HDF5 file is equivalent to the given HDF-EOS2 file. This has been a separated
      package, but it is included in misc/verify_eos2nc4 directory.

6. New features (Version 2.0)
 1) HDF-EOS2 conversion (--with-hdfeos2 option)
   a) If H4H5TOOLS is configured with --with-hdfeos2 option, h4toh5 conversion utility
      will recognize HDF-EOS2 files and handle these files by using both HDF4
      APIs and HDF-EOS2 APIs. Three command line options (-eos -nc4 -nc4strict) were added.
   b) If converting an HDF-EOS2 file, h4toh5 conversion tool can generate HDF5 files that can be read by netCDF4.
       --- C. Lee May 23rd, 2008

 2) Windows development
   a) We use environment variables to represent HDF4 libraries 
      and external libraries. In this way, users can change their own HDF4 and external
      libraries easily.
   b) Only DLL versions of szip and zlib libraries are used.
      Please read the details at INSTALLh425_Windows.txt inside h4h5proj.zip.

      --- K. Yang  2005
 3) Handling of external libraries
    Since zlib and jpeg libraries are required for HDF4, so to use H4toH5
    library, zlib and jpeg are required. szip can be optional. To avoid using
    szip, users must build HDF4 and HDF5 with szip disabled, H4toH5 library
    then should be built with the new HDF4 and HDF5. 

     --- K. Yang  2005
 

7. Limitations and known problems
 1) When HDF-EOS2 is being handled,
   a) To make the output HDF5 file readable by netCDF4 APIs, the original
      structure of HDF-EOS2 is not always kept. h4toh5 may move some datasets to a
      sibling group. Also, it may introduce a hard link that didn't exist in the
      original file.
   b) Some HDFEOS2-specific data structures such as dimension maps are not converted
      because they are not HDF4 objects.
   --- C. Lee May 23rd, 2008

   c) Some broken HDF-EOS2 files may result in buffer overrun. An HDF-EOS2 file
      can be broken if users modify HDF-EOS2 objects using the HDF4 library, not
      HDF-EOS2 library. H4H5TOOLS cannot avoid this problem for the time being.
   --- C. Lee Jan 31st, 2009

 2) In this release, all HDF5 property list parameters are set as H5P_DEFAULT. 
   --- K. Yang 2005
 3) Windows DLL versions of conversion tools may not work.
   --- K. Yang 2005

