Note: This install instruction is very similar to the HDF5 instruction
for windows platform. Users who are familiar with the installation of
HDF5 library should find the instruction easy to understand. 


H4TOH5 Library Build and Install Instructions for Windows XP
------------------------------------------------------------------------

The following instructions assume that you will be using the source code
release 'zip' file (h4h5tools.zip).

***************************WARNINGS*************************************
Please read CAREFULLY about Preconditions before you go to the following
sections.

Preconditions 

   1. Installed MicroSoft Developer Studio, Visual C++ 6.0 or .NET and 
      WinZip.

   2. Set up a directory structure to unpack the library.  For example:

         c:\                                (any drive)
         MyH4toH5stuff\                     (any folder name)

   3. Run WinZip on h4h5tools.zip (the entire source tree) and extract
      h4h5tool package into c:\MyH4toH5stuff(or whatever drive and
      folder name you would like to choose). This creates a directory
      called 'h4h5tools'(If you find that the folder name is not 
      'h4h5tools', change it to 'h4h5tools'); inside 'h4h5tools', you
      should find a directory called 'lib' under 'h4h5tools' which
      contains several files and directories.  You should also find a
      directory called 'utils' under 'h4h5tools' which contain h4toh5,
      h5toh4 and some other directories.

   4. You do need HDF4 (hdf and mfhdf) static and dll libraries for
      both debug and release versions, HDF5(hdf5) static and dll
      libraries for both debug and release versions.

      a) You may get hdf4 binary distribution from
       ftp://ftp.ncsa.uiuc.edu/HDF/HDF/;
       find the windows binary according to the instruction

      b) You may get hdf5 binary distribution from 
       ftp://ftp.ncsa.uiuc.edu/HDF/HDF5/;
       find the windows binary according to the instruction

   5. zlib and jpeg libraries are required for HDF4. So users need to
      have these two libraries for building the H4H5 library.

      zlib 1.2.2 and JPEG release 6b are used inside HDF4. To use Zlib
      library, you have to install your own Zlib DLL or go
      to ftp://hdf.ncsa.uiuc.edu/lib-external/zlib/bin/windows 
      to download the Zlib library. Zlib 1.2.2 DLL can also be 
	downloaded from http://www.zlib.net/zlib122-dll.zip. 
	To use JPEG library, you have to install your own JPEG library or go to
      ftp://hdf.ncsa.uiuc.edu/lib-external/jpeg/bin to download
      the JPEG library archive file jpeg-6b.exe.

   6. szip library is optional for both HDF4 and HDF5 and H4H5 tools.
      Szip is not a totally open-source free software.  Szip decoder is 
      free for distribution.  
      To use Szip library, you can download Szip source codes and binaries
      from ftp://hdf.ncsa.uiuc.edu/szip/2.0/bin/windows/
	For licensing issue of Szip, please check 
      "Licensing terms" at
      http://hdf.ncsa.uiuc.edu/doc_resource/SZIP/index.html.


The following sections discuss installation procedures in detail:                         

   Section I:    What do we build and install
   Section II:   Building and testing h4toh5 libraries,h4toh5 utility
                 and h5toh4 utility
   Section III:  Building an application using the H4TOH5 library 
   Section IV:   Helpful pointers
   Section V:    Some more helpful pointers
   Section VI.   Disabling szip 
************************************************************************

Section I:

What do we build and install? 

   H4TOH5 static library: 
        debug and release version

   H4TOH5 Dynamic Link Library (DLL): 
        debug and release version as well as export libraries for DLL

   H4TOH5 library testing programs:
        h4toh5 library related tests
                
   H4TOH5 example:
        A simple H4TOH5 example

   H4TOH5 conversion utility:
        debug and release version

   H5TOH4 conversion utility:
        debug and release version
                                
************************************************************************

Section II: 

Building and testing h4toh5 libraries

1. This section builds and tests all versions of h4toh5 libraries,
   testing programs.

2. We assume that you've installed HDF4(mfhdf and hdf) libraries into
   drive C. The top level path,say, for example, might be c:\HDF42r1.
   Under c:\HDF42r1 it should at least include the following six
   directories: 

   c:\HDF42r1\debug\dll where debug dll version of hdf and mfhdf 
   libraries and export libraries of dlls are stored

   c:\HDF42r1\debug\lib where debug version of hdf and mfhdf 
   libraries are stored

   c:\HDF42r1\debug\include where HDF4 public header files are included

   c:\HDF42r1\release\dll where release dll version of hdf and mfhdf 
   libraries and export libraries of dlls are stored

   c:\HDF42r1\release\lib where release version of hdf and mfhdf 
   libraries are stored

   c:\HDF42r1\release\include where HDF4 public header files are
   included

3. We assume that you've installed Zlib,szip and jpeg library into drive c. 
   The top level path, say, for example, may be c:\zlib122,c:/szip20,c:/jpeg-6b.

   Make sure that you copy all DLL files under c:\HDF42r1, c:\5-164-win
   c:\zlib122,c:/szip20  into Windows system directory. The system 
   directory can usually be found under the path c:\WINNT\system or c:\Windows\system

4. Set up environment variables

   Define the following environment variables: 

          H4H5_EXT_ZLIB
          H4H5_EXT_JPEG
          H4H5_EXT_SZIP
          HDF4_DEBUG_DLL
	    HDF4_DEBUG_LIB
          HDF4_RELEASE_DLL
          HDF4_RELEASE_LIB
          MFHDF4_DEBUG_DLL
	    MFHDF4_DEBUG_LIB
          MFHDF4_RELEASE_DLL
          MFHDF4_RELEASE_LIB

      
      In this section, Szip compression software is assumed to be used.
      Please read section VI as well as this section if you do not
      want to use Szip compression feature inside HDF4.
      
      To define these environment variables:
      
      Click "Start", click "Control Panel", and then double-click
      "System".  On the "Advanced" tab, click "Environment Variables".
      
      If you are logged on as administrator to the local computer AND
      want to let all other users use these three environment variables,
      click "New" under "System Variables" box; otherwise, click "New"
      under "User Variables" box.
      
      In the New Variable window, set "Variable name" as HDF4_EXT_ZLIB
      and "Variable value" as zdll.lib, then click OK.
      
      Similarly, you can set:

      HDF4_EXT_JPEG environment variable as libjpeg.lib
      HDF4_EXT_SZIP environment variable as szlibdll.lib
	HDF4_DEBUG_DLL environment variable as hd421md.lib
	HDF4_DEBUG_LIB  environment variable as hd421d.lib
      HDF4_RELEASE_DLL environment variable as hd421m.lib
      HDF4_RELEASE_LIB environment variable as hd421.lib
      MFHDF4_DEBUG_DLL environment variable as hm421md.lib
	MFHDF4_DEBUG_LIB environment variable as hm421d.lib
      MFHDF4_RELEASE_DLL environment variable as hm421m.lib
      MFHDF4_RELEASE_LIB environment variable as hm421.lib

      Notes:

         a. You might have to close and reopen running programs for the
            new environment variable settings to take effect. 

Step 1. Build the h4h5 tool.
  
    1. extract h4h5proj.zip to the folder 'c:\MyH4toH5stuff'.
      
    2. Invoke Microsoft Visual C++, go to "File" and select the 
       "Open Workspace" option. 

       Then open the c:\MyH4toH5stuff\h4h5tools\proj\all\all.dsw
       workspace. 
    
    3. Go to "Tools" and select "Options", find "Directories";

       3.1 Find the box "Show directories for", choose "Include files",
           See whether you can find the include path of HDF4, HDF5
           and Zlib, for example:

              c:\zlib122\include 
              c:\5-164-win\release\include
              c:\HDF42r1\release\include
              c:\szip20\include
	        c:\jpeg-6b

           at the directory listed,

           If not, add the above pathes to the included directories.
            
       3.2 Find the box "Show directories for", choose "Library files",
           Make sure that you have the following paths added to the box:

              c:\HDF42r1\release\lib
              c:\HDF42r1\release\dll
              c:\HDF42r1\debug\lib
              c:\HDF42r1\debug\dll
              c:\5-164-win\release\lib
              c:\5-164-win\release\dll
              c:\5-164-win\debug\lib
              c:\5-164-win\debug\dll
              c:\zlib122\lib
		  c:\szip20\dll
              c:\jpeg-6b

       Note: when you build DLL, you have to make sure the project
             settings includes "_HDFDLL_,_HDFLIB_,_HDF5USEDLL_" and
             "_H4TOH5DLL_" at your <Preprocessor defination> box under
             the category "Preprocessor" of C/C++ menu.

             The setting of the project file that tests for DLL must
             also include "_HDFDLL_,_HDFLIB_,_HDF5USEDLL_," and 
             "_H4TOH5USEDLL_" at your <Preprocessor defination> box
             under the category "Preprocessor" of C/C++ menu.

    4. Select "Build", then Select "Set Active Configuration".

       On Windows platform select as the active configuration

          "all -- Win32 Debug" to build debug versions of
          single-threaded static libraries, Debug multithreaded
          DLLs and tests. 
               
          or

          "all -- Win32 Release" to build release versions of
          single-threaded static libraries, multithreaded DLLs
          and tests.
            
       When the debug or release build is done the directories 
       listed below will contain the following files:

          c:\MyH4toH5stuff\h4h5tools\lib\h425lib\debug - 
          c:\MyH4toH5stuff\h4h5tools\lib\h425lib\release - 

              h425lib.lib- the h425 static library based on release
                           version of HDF4 and HDF5 libraries

          c:\MyH4toH5stuff\h4h5tools\lib\h425libdbg\debug - 
          c:\MyH4toH5stuff\h4h5tools\lib\h425libdbg\release -
              
              h425libdbg.lib- the h425 static library based on debug
                              version of HDF4 and HDF5 libraries
                  
          c:\MyH4toH5stuff\h4h5tools\lib\h425libdll\debug -
          c:\MyH4toH5stuff\h4h5tools\lib\h425libdll\release -
            
              h425libddll.dll- the h425 DLL
              h425libddll.lib- the dll export library

          c:\MyH4toH5stuff\h4h5tools\lib\h425libdlldbg\debug -
          c:\MyH4toH5stuff\h4h5tools\lib\h425libdlldbg\release -
            
              h425libddlldbg.dll- the h425 DLL
              h425libddlldbg.lib- the dll export library

          c:\MyH4toH5stuff\h4h5tools\lib\test\"test directory"-

          where test directory is one of the following:

              h4h5apitestadvgroup(dll)
              h4h5apitestbasvgroup(dll)
              h4h5apitestdefault(dll)
              h4h5apitestimage(dll)
              h4h5apitestimageattr(dll)
              h4h5apitestloneimage(dll)
              h4h5apitestlonesds(dll)
              h4h5apitestlonevdata(dll)
              h4h5apitestname(dll)
              h4h5apitestsds(dll)
              h4h5apitestsdsattr(dll)
              h4h5apitestvdata(dll)

          c:\MyH4toH5stuff\h4h5tools\utils\proj\h4toh5\debug -
          c:\MyH4toH5stuff\h4h5tools\utils\proj\h4toh5\release -

              h4toh5 static utility based on debug and release version
              of hdf4 and hdf5 libraries

          c:\MyH4toH5stuff\h4h5tools\utils\proj\h4toh5dll\debug -
          c:\MyH4toH5stuff\h4h5tools\utils\proj\h4toh5dll\release -

              h4toh5dll utility based on debug and release version
              of hdf4 and hdf5 DLLs

          c:\MyH4toH5stuff\h4h5tools\utils\proj\h5toh4\debug -
          c:\MyH4toH5stuff\h4h5tools\utils\proj\h5toh4\release -

              h5toh4 static utility based on debug and release version
              of hdf4 and hdf5 libraries

          c:\MyH4toH5stuff\h4h5tools\utils\proj\h5toh4dll\debug -
          c:\MyH4toH5stuff\h4h5tools\utils\proj\h5toh4dll\release -

              h5toh4dll utility based on debug and release version
              of hdf4 and hdf5 DLLs

            
Step 2. test the h4toh5 library

In a command prompt window run the test batch file which resides in the
h4h5tools\lib\test directory to make sure that the library was built
correctly.

You can possibly test four versions of h4h5tools library and tools.
They are:

   release version
   release dll version
   debug version
   debug dll version

NOTE: The h425libddlldbg.dll and h425libdlldbg.dll should be placed into
      the c:\WINNT\system or c:\WINDOWS\system directory before using
      the dlls.

We strongly suggest you to redirect your testing results into an output
file and you can easily check the testing results.  You may use either
NotePad or NoteTab Light or whatever other windows tools to check the
results.  For the purpose of printing, please choose font less than 14
for better alignment of the text.

H4toh5 library testing

cd into the h4h5tools\lib\test directory.

Before testing, make sure that you add the path where h5dump is located
in your system variable PATH.

Go to a) b) c) or d) to test your chosen version

   a) release static version
      type:             
         h4h5libtestrun release >"Your output filename" 

   b) release dll version
      type:
         h4h5libtestrun release dll > "Your output filename"
				
   c) debug static version
      type: 
         h4h5libtestrun debug >"Your output filename"

   d) debug dll version
      type:
         h4h5libtestrun debug dll >"Your output filename"
            
We are using "fc" command to compare whether h4toh5 library converts
HDF4 objects correctly, Please only pay attention to those lines which
start with "FC:" in "STEP FIVE" for each test, you should find 
"FC: no differences encountered" for all tested outputs. 

Step 3. install the h4toh5 library

This step is optional. Users can use a simple batch file
"install_h425lib.bat" under C:\MyH4toH5stuff\h4h5tools\lib to copy
H4toH5 static libraries, DLLs and public headers to the directory
c:\MyH4toH5stuff\h4h5tools\windows.
        
Step 4. test the h4toh5 and h5toh4 utilities

   1) h4toh5 converter tool testing
          
      Before testing, make sure that you add the path where h5dump is
      located in your system variable PATH.

      First cd into h4h5tools\utils\

      Go to a) b) to test your chosen version

      a) release static version
         type:             
            h4toh5testrun release >"Your output filename" 

      b) debug static version
         type: 
            h4toh5testrun debug >"Your output filename"

      We are using "fc" command to compare whether h4toh5 converter
      converts the hdf4 file into the correct hdf5 file.  In your output
      files, Please only pay attention to those lines which start with
      "FC:" in "STEP SIX", you should find "FC: no differences
      encountered" for all tested hdf4 files in your output.
                       
      
   2) h5toh4 converter tool testing                
                                                             
      To test the h5toh4 utility, you need to have HDF4 dumper utility
      "hdp" in your system variable PATH.


      A) Make sure that you add the path where hdp is located in your
         system variable PATH.       

      B) cd into h4h5tools\utils
 
         Go to a) b) to test your chosen version

         a) release static version
            type:             
               h5toh4testrun release >"Your output filename" 

 	   b) debug static version
            type: 
               h5toh4testrun debug >"Your output filename"

      We are using "fc" command to compare whether h5toh4 converter
      converts the HDF5 file into the correct HDF4 file. In your output
      files, Please only pay attention to those lines which start with
      "FC:" in "STEP SIX" ,you should find "FC: no differences
      encountered" for all tested hdf4 files in your output.

      Warnings appear on the prompt when testing h5toh4 converter
      can be ignored. 
                

Section III: Building an application using the H4TOH5 library

We only provide one example currently.

   1. Invoke Microsoft Visual C++, go to "File" and select the 
      "Open Workspace" option. 
      
      Then open the workspace
      c:\MyH4toH5stuff\h4h5tools\lib\examples\example1\example1.dsw.

   2. Select "Build", then Select "Set Active Configuration".

      On Windows platform select as the active configuration
      
      "example1 -- Win32 Debug" to build debug versions of the example.

      or

      "example1 -- Win32 Release" to build release versions of 
                                  the example.

   3. cd into lib

   4. Run installExamples. The testing file and executable file should
      be put into the proper directories.

   5. Go to either the directory examplesDBG or examplesREL to run the
      executable file example1.exe.

   6. You may use h5dump to check the output. Automatic checking will
      be provided in the next release.

   7. When you use H4toh5 DLL in your application, the H4toh5 DLL
      should be put at the system directory. The project setting must
      include the following information: "_HDFDLL_,_HDFLIB_,
      _HDF5USEDLL_," and "_H4TOH5USEDLL_" at your <Preprocessor
      defination> box under the category "Preprocessor" of C/C++ menu.


Note: The following two sections are adapted from HDF5 install_windows
      document Exactly. 

Section IV:  
SOME HELPFUL POINTERS FOR BUILDING AN APPLICATION USING H4TOH5 LIBRARY
========================================================================

Preconditions:

1.
YOU MUST HAVE BOTH DEBUG AND RELEASE VERSIONS OF HDF4 AND HDF5 STATIC
AND DLL INSTALLED ON YOUR MACHINE. 

2. YOU MUST BUILD H4TOH5 either static or DLLs successfully following
section II and III.  If you are building an application that uses the
H4TOH5 library the following locations will need to be specified for
locating header files and linking in the HDF4 and HDF5 libraries of
binary release:

   <top-level HDF4 directory>\include
   <top-level HDF5 directory>\include
   <top-level H4TOH5 directory>\src

where <top-level HDF5 directory> may be 

   C:\MyH4toH5stuff\hdf5\

You also need to include the H4TOH5 public header h4toh5.h file to
your application:

There are two ways to tune your project settings.

1. Go to TOOLS-->Options-->Directories

Add the corresponding include paths and library paths.  Those paths
should include HDF4, HDF5, Zlib include directories, HDF4,HDF5 and Zlib
library paths.

2. To specify this location in the settings for your VC++ project:

   1.) Open your VC project in Microsoft Visual C++ and make sure it is
       the active project.

   2.) Go to the Project menu and choose the 'Settings' option.

   3.) Choose the build configuration you would like to modify in the
       drop down menu labeled with 'Settings For:'

   4.) Choose the C/C++ tab

   5.) At the bottom of the window, there should be a text-area labeled
       with 'Additional include directories:'. type the 
       HDF4 path(<top-level HDF4 directory>\include) 
       HDF5 path(<top-level HDF5 directory>\include)
       H4TOH5 path(<top-level H4TOH5 directory>\src)
      
       then click OK.
        
To link the H4TOH5 library with your application:

   1. Open your VC project in Microsoft Visual C++ and make sure it is
      the active project.

   2. Go to the Project menu and chose the 'Add to Project' option and
      then 'Files' option.

   3. Change the 'Files of type:' to 'Library Files (.lib)'

   4. Navigate through the directories until you find the location of 
      the h425.lib. 

   5. Select h425.lib and click OK.

   Repeat 1-5 to add HDF4 and HDF5 libraries.

To use the DLL:

   1. Follow the steps for specifing the location of the header files
      as shown above.

   2. Follow the steps for linking the HDF5 library as shown above
      except now link the export library that is created with the DLL.
      The export library is called hdf5dll.lib or hdf5ddll.lib for
      debug version.

   3. Place the DLL in a location that Windows will be able to locate 
      it. The search path and order for DLL's is

      a) The directory where the executable module for the current
         process is located.
      b) The current directory. 
      c} The Windows system directory. The GetSystemDirectory function 
         retrieves the path of this directory. 
      d) The Windows directory. The GetWindowsDirectory function
         retrieves the path of this directory.
      e) The directories listed in the PATH environment variable. 

   4. The project setting must include the following information:
      "_HDFDLL_,_HDFLIB_,_HDF5USEDLL_," and "_H4TOH5USEDLL_" at your 
      <Preprocessor defination> box under the category "Preprocessor"
      of C/C++ menu.

   5. You should also use debug multi-threaded DLL or multi-threaded
      DLL for the DLL application. See the following section about
      how to check this setting.

Section V:
MORE HELPFUL POINTERS
=====================


Here are some notes that may be of help if you are not familiar with
using the Visual C++ Development Environment.

Project name and location issues: 
       
    The files in h425lib.zip must end up in the "lib" directory or
    "utils" directory installed by h4h5tools1.0.zip

    If you must install all.dsw and all.dsp in another directory,
    relative to hdf5\, you will be asked to locate the sub-project
    files, when you open the project all.dsw.

    If you want to rename all (the entire project), you will need to
    modify two files all.dsw and all.dsp as text (contrary to the
    explicit warnings in the files).

    You can also modify all.dsw and all.dsp as text, to allow these 2
    files to be installed in another directory.

  
Settings... details:

    If you create your own project, the necessary settings can be read
    from the all.dsp file(as text), or from the Project Settings in the
    Developer Studio project settings dialog.

    Project
       Settings
          C/C++
             Category
                PreProcessor
                   Code Generation
                      Use run-time Library
                         These are all set to use Single-Threaded

DLL... hints:
  
   If you want to use DLL versions of h4toh5 library in your application, 
   you should
  
      1) put h425 DLL into windows system directory
      2) add h425 DLL export library into your project
      3) Follow "Settings... details" into the last line:
         change Single-Threaded into Multithreaded DLL or 
         Debug Multithreaded DLL
      4) Follow "Settings.. details" into PreProcessor:
         Project
            Settings
               C/C++
                  Category
                     PreProcessor

         Find PreProcessor definations and Add _H4TOH5USEDLL_ at the
         end of the PreProcessor definations
         
Section VI:
Disable szip
============
You don't need to do anything inside H4H5tools to disable szip filter. 
You do need to build HDF4 and HDF5 libraries with szip Disabled and then
use these libraries to build H4H5tools. Please refer to windows installation
files for HDF4 and HDF5 on how to disable szip.


