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 LIB Build and Install Instructions for Windows NT 5.0/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 h4toh5lib 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 and zlib library to build up h4toh5 library,h4toh5 utility and
	h5toh4 utility.

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 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. In case 
      You don't install hdf4, hdf5 and zlib libraries in your machine:
      (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
	You may get zlib binary distribution from
	ftp://ftp.ncsa.uiuc.edu/HDF/gzip/windows/; since HDF5 and the new release of HDF4 will 
	use 1.1.4 version of zlib library; we prefer you to use that one.

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

C:\HDF41r5\bin where hdf4 utilities are stored

C:\HDF41r5\dlllib where release dll versions of hdf and mfhdf 
libraries and export libraries of dlls are stored

C:\HDF41r5\dlllibdbg where debug dll versions of hdf and mfhdf 
libraries and export libraries of dlls are stored

C:\HDF41r5\lib where release versions of hdf and mfhdf 
libraries are stored

C:\HDF41r5\libdbg where debug versions of hdf and mfhdf 
libraries are stored

C:\HDF41r5\include where header files are included 

We assume that you've installed hdf5 libraries into drive C. The top 
level path say, for example, C:\5-161-win.

C:\5-161-win\c\debug\dll where debug dll version of hdf5 library and export library of dll are stored. 

C:\5-161-win\c\debug\lib where debug version of hdf5 library is stored.

C:\5-161-win\c\debug\include where hdf5 public header files are included. 

C:\5-161-win\c\release\dll where release dll version of hdf5 library and export library of dll are stored. 

C:\5-161-win\c\release\lib where release version of hdf5 library is stored.

C:\5-161-win\c\release\include where hdf5 public header files are included. 

We assume that you've installed zlib library into drive C. The top 
level path, say, for example, may be C:\zlib114.

C:\zlib114\include where zlib public header files are included.

C:\zlib114\lib where zlib static library is located.

C:\zlib114\dll where zlib dll and dll export library are located.

Make sure that you copy all *.dll files under C:\HDF41r5, C:\5-161-win\c and 
C:\zlib114\dll into Windows system 
directory. The system directory can usually be found under the path 
		C:\WINNT\system or C:\windows\system


Step 1. Build the h4toh5 library 
  
    1. Unpack h425lib.zip in 'h4h5tools\lib'.
      
    2. Invoke Microsoft Visual C++, go to "File" and select the 
       "Open Workspace" option. 

       Then open the c:\MyH4toH5stuff\h4h5tools\lib\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:\zlib114\include 
			 C:\5-161-win\c\release\include
		 	 C:\HDF41r5\include 
	      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 pathes added to the box:
		C:\5-161-win\c\release\lib
		c:\zlib114\lib
		c:\HDF41r5\lib
		c:\HDF41r5\libdbg
		c:\5-161-win\c\debug\lib
		c:\5-161-win\c\debug\dll
            c:\5-161-win\c\release\dll
		c:\hdf41r5\dlllib
		c:\hdf41r5\dlllibdbg
      
     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\proj\h425lib\debug - 
            c:\MyH4toH5stuff\h4h5tools\lib\proj\h425lib\release - 

                  h425lib.lib- the h425 static library based on release version
                  of hdf4 and hdf5 libraries

            c:\MyH4toH5stuff\h4h5tools\lib\proj\h425libdbg\debug - 
            c:\MyH4toH5stuff\h4h5tools\lib\proj\h425libdbg\release -
              
                   h425libdbg.lib- the h425 static library based on debug version
                    of hdf4 and hdf5 libraries
                  
            c:\MyH4toH5stuff\h4h5tools\lib\proj\h425libdlldbg\debug -
            
                  h425libddlldbg.dll- the h425 DLL
                  h425libddlldbg.lib- the dll export library

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


            c:\MyH4toH5stuff\hdf5\test\"test directory"-

            where test directory is one of the following:

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

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

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

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

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

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

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

		c:\MyH4toH5stuff\h4h5tools\utils\h5toh4dll\debug -
		c:\MyH4toH5stuff\h4h5tools\utils\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 hdf5\test directory(for example: C:\MyH4toH5stuff\h4h5tools\lib\test)to make 
sure that the library was built correctly.

You can possibly test four versions of hdf5 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 
     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:",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) c) or d) to test your chosen version

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

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

           d) debug dll version
           type:
            h4toh5testrun debug dll >"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:",you should find "FC: no differences encountered"  
        for all tested hdf4 files in your output.
                       
	**Note: h4toh5 utility DLL may fail due to the combinating use of DLL,
		  this is a known problem. If people have concerns about this, please
		  contact with hdfhelp@ncsa.uiuc.edu.

      2) h5toh4 converter tool testing                
                                                             
        To test the h5toh4 utility, you need to have hdf4  
        dumper utility "hdp" in your system.

        Note: Currently h5toh4 release dll doesn't work
        for all test cases possibly due to windows dealing
        with "free memory" conventions for dll versions.      

       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) c) or d) to test your chosen version

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

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

           d) debug dll version
           type:
            h5toh4testrun debug dll >"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:",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 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 pathes and library pathes.
Those pathes should include HDF4,HDF5,zlib include directories, HDF4,HDF5 and zlib library 
pathes.

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 hdf5.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
         


