README for Optional HDF-EOS2/netCDF-4 Verifier
==============================================

This directory contains the optional HDF-EOS2/netCDF-4 verifier utility.
The HDF-EOS2/netCDF-4 Verifier is a UNIX-only utility.

This program determines whether each object in a source HDF-EOS2 file 
has been correctly converted to an equivalent object in an output 
netCDF-4-compliant HDF5 file.

1. Platform Tested
==================
This utility has been tested with HDF-EOS2 2.19, HDF4.2.13 and HDF5 1.8.19,
netCDF-4.4.1.1 on the following platform and compiler:
   Linux 3.10 (x86_64), gcc 4.8.5

2. New development since prior distribution
===========================================

3. Configuration and Installation
=================================
There is no binary release for the HDF-EOS2/netCDF-4 verifier utility.
It must be built from the source as follows:


    1. Prerequisites

       HDF4 library (--disable-netcdf)
       HDF5 library
       HDF-EOS2 library
       netCDF-4 library
       C++ compiler

       One important requirement is that --disable-netcdf configuration 
       option must be used when HDF4 is configured. This is required 
       because HDF4 enables the netcdf interface by default and the netcdf 
       interface interferes with the netCDF-4 library.

       This tool requires both HDF-EOS2 library and netCDF-4 library because 
       it opens the HDF-EOS2 file and the netCDF-4-compliant HDF5 file using 
       the HDF-EOS2 and netCDF-4 libraries, respectively.

       Since the verifier contains both C and C++ code, a C++ compiler is 
       required.

    2. Configure

       Note that the verifier is a stand-alone program. It has its own 
       configure script.

       C Compiler (CC), C++ Compiler (CXX)
         Using h4cc is not recommended. Just leave CC and CXX as the system 
         specifies.

       C Compiler option (CFLAGS), C++ Compiler option (CXXFLAGS)
         You don't need to specify -DH5_USE_16_API even if you use HDF5 1.8 
         or higher.

       HDF4 library (--with-hdf4=)
         The location of the HDF4 library should be specified. As mentioned 
         earlier, the HDF4 library should be built without the netcdf 
         interface.

       HDF5 library (--with-hdf5=)
         The location of the HDF5 library should be specified.

       HDF-EOS2 library (--with-hdfeos2=)
         The location of the HDF-EOS2 library must be specified. 
         This switch is not optional, but mandated.

       netCDF-4 library (--with-netcdf4=)  
         The location of the netCDF-4 library should be specified.

       ZLIB (--with-zlib=)
       JPEG (--with-jpeg=)
       SZLIB (--with-szlib=)
         Users need to know whether these external libraries are linked with 
         hdf4, hdf5, and hdf-eos2 properly. Users also need to specify the 
         path of these packages if they are not installed with the system.
    

       Example:
          ./configure \
             --with-hdf4=<hdf4libpath> --with-hdf5=<hdf5libpath> \
             --with-hdfeos2=<hdfeos2libpath> --with-netcdf4=<netcdf4libpath>

          If you need to specify the ZLIB, JPEG, or SZLIB libraries,
          you may want to try the following:

          ./configure \
             --with-hdf4=<hdf4libpath> --with-hdf5=<hdf5libpath> \
             --with-hdfeos2=<hdfeos2libpath> --with-netcdf4=<netcdf4libpath> \
             --with-zlib=<zlibpath> --with-jpeg=<jpeglibpath> \
             --with-szlib=<szlibpath>

       On Linux 3.10, -lm and -ldl need to be linked.
       One may do this by adding these options in the CC and CXX.

    3. Build
       GNU make is recommended to build the HDF-EOS2/netCDF-4 verifier.
         $ gmake
       
       Warnings can be ignored.

    4. Usage
       Two options are available. Both of them are about verbosity of messages.

       -v
         This option lets the verifier show verified objects. By default, the 
         verifier shows messages only when it finds some problems.

       -p
         This option makes the verifier print all object names it accesses. 
         Since it gives more readable output, this option is useful when an 
         error is detected.

       Using both options is recommended unless you want to get just the 
       result.  For example, one can use the following command to compare an 
       HDF-EOS2 file "grid_1_2d.hdf" with a netCDF-4-compliant HDF5 file 
       "grid_1_2d.h5". 
       
       $ verify -p -v grid_1_2d.hdf grid_1_2d.h5

       Note "grid_1_2d.h5" could be generated as follows:

       $ cd utils/h4toh5
       $ ./h4toh5 -eos -nc4strict grid_1_2d.hdf grid_1_2d.h5
       The grid_1_2d.hdf can be found under /src.

    5. Note about false alarms
       The HDF-EOS2/netCDF-4 verifier is neither sound nor complete in the 
       sense that it may give false alarms and it may miss incorrect 
       conversion. 

       False alarms can be introduced by either a netCDF-4 library problem 
       or excessive strictness of the HDF-EOS2/netCDF-4 verifier. We found one
       problem when we used netCDF-4.0.0, and the problem disappeared after 
       moving to netCDF-4.0.1-beta2. So, you may need to upgrade netCDF-4.

       Also, the HDF-EOS2/netCDF-4 verifier does not catch all incorrect 
       conversions.  The verifier traverses each object with the HDF-EOS2 
       API; objects that are invisible to the HDF-EOS2 library will not be
       verified.