path: root/release_docs/RELEASE.txt

HDF5 version 1.6.3-pre4 currently under development
================================================================================


INTRODUCTION

This document describes the differences between HDF5-1.6.2 and
HDF5-1.6.2-*, and contains information on the platforms tested and
known problems in HDF5-1.6.2-*. For more details check the HISTORY.txt
file in the HDF5 source.

The HDF5 documentation can be found on the NCSA ftp server
(ftp.ncsa.uiuc.edu) in the directory:

     /HDF/HDF5/docs/

For more information look at the HDF5 home page at:
   
    http://hdf.ncsa.uiuc.edu/HDF5/

If you have any questions or comments, please send them to:

    hdfhelp@ncsa.uiuc.edu

CONTENTS

- New Features
- Support for new platforms and languages
- Bug Fixes since HDF5-1.6.2
- Documentation
- Platforms Tested
- Supported Configuration Features Summary
- Known Problems


New Features
============

    Configuration:
    --------------
        - Added some initial support for making purify (or similar memory
            checking products) happier by initializing buffers to zero and
            disabling the internal free list code.  To take advantage of this,
            define 'H5_USING_PURIFY' in your CFLAGS when building the library.
            QAK - 2004/07/23

        - WINDOWS building,testing and installing improvements

          - On Windows, FORTRAN,C++ and C projects are merged into one zip file, 
            users can choose an option to build either FORTRAN or C++ or both 
            with basic C library.For detailed information,
            please read INSTALL_Windows.txt.

          - On Windows, szip compression library with or without encoder can be easily
            turned off or on when building HDF5.  For detailed information,
            please read INSTALL_Windows.txt, especially section V. 
  
          - On Windows, an optional procedure for building,testing and installing
            HDF5 from command line is provided. This procedure is supposed to be
            convenient for experienced users, please read 
            INSTALL_windows_From_Command_Line.txt for details.

          - On Windows, an alternative short instruction document for building,
            testing and installing HDF5 is provided. This instruction is supposed to
            be convenient for general users, please read 
            INSTALL_Windows_Short.txt for details.

          - On Windows, h5repack,h5diff,h5ls and h5import tool tests have been added.
          KY - 2004/9/16
  

    Library:
    --------
        - Modified the way how HDF5 calculates 'pixels_per_scanline' parameter for
          SZIP compression. Now there is no restriction on the size and shape of the 
          chunk except that the total number of elements in the chunk cannot be 
          bigger than 'pixels_per_block' parameter provided by the user.
                                                                    EIP - 2004/07/21 
        - HDF5 can now link to SZIP with or without szip's encoder.
          The new API function H5Zget_filter_info can be used to check
          szip's status.  Attempting to assign szip to a dataset property
          list or attempting to write with szip will generate an error if
          szip's encoder is disabled.  JL/NF - 2004/6/30
        - SZIP always uses K13 compression.  This flag no longer needs to
          be set when calling H5Pset_szip.  If the flag for CHIP
          compression is set, it will be ignored (since the two are mutually
          exclusive).  JL/NF - 2004/6/30
        - A new API function H5Fget_name was added.  It returns the name
          of the file by object(file, group, data set, named data type,
          attribute) ID.  SLU - 2004/06/29
        - A new API function H5Fget_filesize was added.  It returns the
          actual file size of the opened file.  SLU - 2004/06/24
	- Added option that if $HDF5_DISABLE_VERSION_CHECK is set to 2,
	  will suppress all library version mismatch warning messages.
	  AKC - 2004/4/14

    Parallel Library:
    -----------------

    Tools:
    ------
        - h5repack was added to the tools suite. h5repack regenerates an HDF5 file 
	  from another HDF5 file, optionally applying HDF5 filters (compression) 
	  and/or chunking to the copied file. The filters options are read from 
	  the command line. See /doc/html/Tools.html for more details.
	  PVN - 2004/9/13

        - h5dump includes new features:
           1) Printing of dataset filters, storage layout and fill value information.
           2) Print a list of the file contents.
	   3) Escape non printing characters.
	   4) Print the content of the boot block.
	   5) Print array indices with the data (the default).
	  These options are all switch controlled. See /doc/html/Tools.html for more details.
	  PVN - 2004/9/13
	      

    F90 API:
    --------
        - added new h5fget_name_f and h5fget_filesize_f subroutines
                                         EIP 2004/07/08

    C++ API:
    --------
	- Added wrappers for array and variable length datatypes APIs
	- Added wrappers for newly added APIs from H5T, H5F, and H5I
	- Added many wrappers that were missing from the H5P API
	- Added the ability to reference HDF5 objects to these classes:
	  DataSet, DataType, Group, and H5File (wrappers for H5R APIs)
	BMR 2004/08/04


Support for new platforms, languages and compilers.
=======================================
        - Added PGI Fortran support for Linux64 (x86_64) systems
                            EIP - 2004/08/19
        - Absoft compiler f95 v9.0 is supported on Linux 2.4 32bit
                            EIP - 2004/07/29 
        - HDF5 Fortran APIs are supported on Mac OSX with IBM XL Fortran
          compiler version 8.1. This is a default compiler.
        - HDF5 Fortran APIs are supported on MAC OSX with Absoft F95 compiler
          version 8.2; set F9X environment varibale to f95, for example
          setenv F9X f95
          Use --disable-shared --enable-static configure flags when Absoft
          compiler is used.
                             EIP - 2004/07/27

Bug Fixes since HDF5-1.6.2 release
==================================

    Library
    -------
	- Fixed parallel bug in which some processes attempted collective
	  I/O while others did independent I/O.  Bug appeared when some
	  processes used point selections, and others didn't.  JRM - 2004/9/15
        - Corrected error where dataset region references were written in an
          incorrect way on Cray machines.  PVN & QAK - 2004/09/13
        - The H5Tget_native_type now determines the native type for integers
          based on the precision. This is to avoid cases of wrongly converting        
          an int to a short in machines that have a short of 8 bytes but with
	  32bit precision (e.g Cray SV1). PVN - 2004/09/07 
        - Changed H5Dread() to not overwrite data in an application's buffer
          with garbage when accessing a chunked dataset with an undefined fill
          value and an unwritten chunk is uncountered.  QAK - 2004/08/25
        - Fixed error which could cause a core dump when a type conversion
          routine was registered after a compound datatype had been
          converted and then an equivalment compound datatype was converted
          again.  QAK - 2004/08/07
        - Fixed memory overwrite when encoding "multi" file driver information
          for file's superblock.  QAK - 2004/08/05
        - Fixed obscure bug where a filter which failed during chunk allocation
          could allow library to write uncompressed data to disk but think
          the data was compressed.  QAK - 2004/07/29
        - Fixed bug where I/O to an extendible chunked dataset with zero-sized
          dimensions would cause library to fail an assertion.
          QAK - 2004/07/27
        - Fixed bug where chunked datasets which have filters defined,
          allocation time set to "late" and whose chunks don't align with
          the dataspace bounds could have incorrect data stored when
          overwriting the entire dataset on the first write.  QAK - 2004/07/27
        - Added check to ensure that dataspaces have extents set. JML-2004/07/26
        - Fixed bug on some Solaris systems where HDF5 would try to use
          gettimeofday() when that function didn't work properly.
          JML - 2004/07/23
        - Fixed bug in H5Sset_extent_simple where setting maximum size to
          non-zero, then to zero would cause an error.  JML - 2004/07/20
        - Allow NULL pointer for buffer parameter to H5Dread & H5Dwrite
          when not writing data ("none" selection or hyperslab or point
          selection with no elements defined).  QAK - 2004/07/20
        - Calling H5Gcreate() on "/" or "." throws an error instead of
          failing quietly. JML - 2004/07/19
        - Fixed bug where setting file address size to be very small could
          trigger an assert if the file grew to more than 64 KB.  Now throws
          an error and data can be recovered. JL/NF - 2004/07/14
        - Fixed bug where "resurrecting" a dataset was failing.
          QAK - 2004/07/14
        - Fixed bug where incorrect data could be read from a chunked dataset
          after it was extended.  QAK - 2004/07/12
        - After compound datatype with variable-length string in the fields
          is committed to file, the size is messed up when it's read back.
          Fixed.  SLU - 2004/06/11
        - Fixed potential file corruption bug when a block of metadata could
          overlap the end of the internal metadata accumulator buffer and
          the buffer would be extended correctly, but would incorrectly 
          change it's starting address.  QAK - 2004/06/09
        - Opaque datatype with no tag failed for some operations.  Fixed.
          SLU - 2004/6/3
        - Fixed potential file corruption bug where dimensions that were
          too large (a value greater than could be represented in 32-bits)
          could cause the incorrect amount of space to be allocated in a
          file for the raw data for the dataset.  QAK - 2004/06/01
	- Fixed dtypes "sw long double -> double" failure in QSC class
	  machines.  AKC - 2004/4/16

    Configuration
    -------------
        - Fixed the long compile time of H5detect.c when v7.x Intel Compiler
	  is used with optimization NOT off.  AKC - 2004/05/20

    Performance
    -------------

    Tools
    -----
        - On SGI h5dump displayed only part of the data due to the bug
          in the system printf; fixed.
                                             EIP - 2004/09/21 
    Documentation 
    ------------- 

    F90 API
    -------
    
    Fortran functions h5dwrite/read_f and h5awrite/read_f do not
    accept dims parameter of INTEGER type anymore. Code was removed.
                                                    2004/04/15
    C++ API
    -------
	- H5::Exception's and its subclasses' constructors that were 
	  overloaded to take char pointers are removed and constructors
	  that passed in reference of 'string' are changed to pass 
	  by value.  In addition, the default value of the data member
	  H5::Exception::detailMessage is changed from 0/NULL to 
	  DEFAULT_MSG ("No detailed information provided".)
	- Prototype for DSetCreatPropList::setLayout is changed: 1st parameter
          is removed because it was there only by mistake.
	BMR 2004/08/04

Documentation
=============
    Windows 
    -------
        -  INSTALL_Windows.txt has been enhanced to include instructions building 
           HDF5 with FORTRAN and C++. 
        -  Two optional installation documents have been added. They are
           INSTALL_Windows_Short.txt and INSTALL_Windows_From_Command_Line.txt.
           INSTALL_Windows_Short.txt is supposed to help general users who
           only want to build,test and install HDF5 in a quick way.
           INSTALL_Windows_From_Command_Line.txt is supposed to help users who
           would like to compile,test and install HDF5 in command line environment.
        -  INSTALL_Windows_withcpp.txt and INSTALL_Windows_withF90.txt become
           obsolete. Users should NOT refer to those documents anymore.
        KY 2004/09/16
        


Platforms Tested
================

    AIX 5.1  (32 and 64-bit)      xlc 6.0.0.2
                                  xlf 8.1.0.3
    				  xlC 6.0.0.4
				  xlc 5.0.2.5
				  xlf 7.1.1.2
				  xlC 5.0.2.5
				  mpcc_r 5.0.2.5
				  mpxlf_r 7.1.1.2
                                  poe 3.2.0.10
    AIX 5.2                       xlc 6.0
    Cray T90 sn7001 10.0.0md      Cray Standard C Version 6.4.0.3
                                  Cray Fortran Version 3.4.0.0
    Cray T3E sn6606 2.0.6.08      Cray Standard C Version 6.6.0.3
                                  Cray Fortran Version 3.6.0.3
    Cray SV1 sn9617 10.0.1.2      Cray Standard C Version 6.6.0.3.6
                                  Cray Fortran Version 3.6.0.3.1
    FreeBSD 4.9                   gcc 2.95.4
                                  g++ 2.95.4
    HP-UX B.11.00                 HP C  HP92453-01 A.11.01.20 
                                  HP F90 v2.4
                                  HP ANSI C++ B3910B A.03.13
                                  MPIch 1.2.4
    IRIX64 6.5 (64 & n32)         MIPSpro cc 7.3.1.3m
                                  F90 MIPSpro 7.3.1.3m (64 only)
                                  C++ MIPSpro cc 7.3.1.3m
    Linux 2.4.18                  gcc 2.96, 3.3.2
                                  g++ 3.3.2
                                  Intel(R) C++ Version 7.1
                                  Intel(R) Fortran Compiler Version 7.1
                                  PGI compilers (pgcc, pgf90, pgCC) version 5.0-2
                                  MPIch 1.2.4
                                  Absoft Fortran compiler v9.0
    Linux 2.4.20-8                gcc 3.3.2
                                  PGI compilers (pgcc, pgf90, pgCC) version 5.0-2
                                  MPIch 1.2.4
    Linux 2.4.21-2.9.5ws #3       gcc 3.2.3 (Red Hat Linux 3.2.3-16)
          SMP x86_64              g++ 3.2.3
    Linux 2.4.19-SMP  x86_64      gcc (GCC) 3.2.2 (SuSE Linux)
                                  g++ 3.2.2
    Linux 2.6.4-52smp x86_64      gcc 3.3.3 (SuSE Linux 9.1 AMD64))
                                  PGI 5.2-1 C and F90 

    Linux 2.4.21-sgi Altix 
          SMP ia64                Intel(R) C++ Version 8.0
                                  Intel(R) Fortran Itanium(R) Version 8.0
                                  SGI MPI
    OSF1 V5.1                     Compaq C V6.5-303 
                                  HP Fortran V5.5A-3548
				  Compaq C++ V6.5-040  
				  MPI_64bit_R13
    SunOS 5.7(32 and 64 bit)      WorkShop Compilers 5.0 98/12/15 C 5.0
     (Solaris 2.7)                WorkShop Compilers 5.0 98/12/15 C++ 5.0 
                                  WorkShop Compilers 5.0 98/10/25 
                                  FORTRAN 90 2.0 Patch 107356-04 
    SunOS 5.8(32 and 64 bit)      Sun WorkShop 6 update 2 C 5.3
     (Solaris 2.8)                Sun WorkShop 6 update 2 Fortran 90
                                  Sun WorkShop 6 update 2 C++ 5.3
    TFLOPS r1.0.4 v4.4.2 i386     pgcc Rel 3.1-4i with mpich-1.2.4 with
                                          local modifications
    IA-32 Linux 2.4.18            gcc 2.96
                                  Intel(R) C++ Version 7.0
                                  Intel(R) Fortran Compiler Version 7.0

    Xeon Linux 2.4.20-31.9smp_perfctr_lustre
	                          Intel(R) C++ Version 8.0
                                  Intel(R) Fortran Compiler Version 8.0
                                  
    IA-64 Linux 2.4.16 ia64       gcc version 3.0.4
                                  Intel(R) C++ Version 7.1
                                  Intel(R) Fortran Compiler Version 7.1

    IA-64 Linux 2.4.21.SuSE_128.bef1 ia64
                                  Intel(R) C++ Version 8.0
                                  Intel(R) Fortran Compiler Version 8.0
				  mpich-gm-1.2.5..intel

    Windows 2000 (NT5.0)          MSVC++ 6.0
                                  MSVC++ .NET
                                  DEC Visual Fortran 6.0
                                  Intel C and F90 compilers version 7.1
				  Code Warrior 8.0
    Windows XP                    MSVC++.NET
                                  MSVC++ 6.0
                                  DEC Visual Fortran 6.0

    MAC OS X                      Darwin 7.5
                                  gcc and g++ Apple Computer, Inc. GCC 
                                  version 1175, based on gcc version 3.3.2
                                  IBM XL Fortran version 8.1 
                                  Absoft Fortran compiler v8.2
                                  


Supported Configuration Features Summary
========================================

  *******************************************************************
  A copy of the current version of the table that belongs in this
  spot is placed for review in the HDF Lobby or can be obtained from 
  Frank Baker.  Please review and give any revisions to him.
  All changes entered into the table in RELEASE.txt on or prior to 
  15 Sept '04 will be captured and posted for review on 16 Sept.
  *******************************************************************

Known Problems
==============
* Fortran subroutine h5pget_driver_f doesn't return a correct driver information.

* There are two h5dump xml tests(h5dump --xml thlink.h5 and h5dump --xml tmany.h5)
  failed on windows xp with .NET for debug and debug dll. Release and Release
  dll work fine. 

* The h5dump tests may fail to match the expected output on some platforms
  (e.g. parallel jobs, Windows) where the error messages directed to
  "stderr" do not appear in the "right order" with output from stdout.
  This is not an error.

* The stream-vfd test uses ip port 10007 for testing. If another
  application is already using that port address, the test will hang
  indefinitely and has to be terminated by the kill command. To try the
  test again, change the port address in test/stream_test.c to one not
  being used in the host.

* The --enable-static-exec configure flag fails to compile for Solaris
  platforms. This is due to the fact that not all of the system
  libraries on Solaris are available in a static format.

  The --enable-static-exec configure flag also fails to correctly compile
  on IBM SP2 platform for the serial mode. The parallel mode works fine
  with this option.
  
  It is suggested that you don't use this option on these platforms
  during configuration.

* The Stream VFD was not tested yet under Windows. It is not supported
  in the TFLOPS machine.


* The ./dsets tests failed in the TFLOPS machine if the test program,
  dsets.c, is compiled with the -O option.  The hdf5 library still works
  correctly with the -O option.  The test program works fine if it is
  compiled with -O1 or -O0.  Only -O (same as -O2) causes the test
  program to fail.

* Certain platforms give false negatives when testing h5ls:
    - Cray J90 and Cray T90IEEE give errors during testing when displaying
      some floating-point values. These are benign differences due to
      the different precision in the values displayed and h5ls appears to
      be dumping floating-point numbers correctly.

* Before building HDF5 F90 Library from source on Crays 
  replace H5Aff.f90, H5Dff.f90 and H5Pff.f90 files in the fortran/src
  subdirectory in the top level directory with the Cray-specific files
  from the site:
  ftp://hdf.ncsa.uiuc.edu/pub/outgoing/hdf5/hdf5-1.6.2/F90_source_for_Crays

* On some platforms that use Intel and Absoft compilers to build HDF5 fortran library,
  compilation may fail for fortranlib_test.f90, fflush1.f90 and fflush2.f90
  complaining about exit subroutine. Comment out the line 
  IF (total_error .ne. 0) CALL exit (total_error)

* On IA32 and IA64 systems, if you use a compiler other than GCC (such as
  Intel's ecc or icc compilers), you will need to modify the generated
  "libtool" program after configuration is finished. On or around line 104 of
  the libtool file, there are lines which look like:

      # How to pass a linker flag through the compiler.
      wl=""

  change these lines to this:

      # How to pass a linker flag through the compiler.
      wl="-Wl,"

  UPDATE: This is now done automatically by the configure script. However, if
  you still experience a problem, you may want to check this line in the
  libtool file and make sure that it has the correct value.

* Information about building with PGI and Intel compilers is available in
  INSTALL file sections 5.7 and 5.8

* In LANL QSC, the new cc compiler has problems converting small values of
  long long (absolute values less than 1**-308) to double.  This triggers
  the test/dtypes to report failure in the
      Testing random sw long double -> double conversions
  If -ieee is used, the converted doubles spread over the range 0.0 to 1**-308.
  If -ieee is not used, the converted double values are mostly 0.0 but
  occassionaly as 1**-308.  This has been reported to the system staff.
  All other tests have passed.

* On at least one system, (SDSC DataStar), the scheduler (in this case
  LoadLeveler) sends job status updates to standard error when you run
  any executable that was compiled with the parallel compilers.

  This causes problems when running "make check" on parallel builds, as
  many of the tool tests function by saving the output from test runs,
  and comparing it to an exemplar.

  The best solution is to reconfigure the target system so it no longer
  inserts the extra text.  However, this may not be practical.

  In such cases, one solution is to "setenv HDF5_Make_Ignore yes" prior to
  the configure and build.  This will cause "make check" to continue after
  detecting errors in the tool tests.  However, in the case of SDSC DataStar,
  it also leaves you with some 150 "failed" tests to examine by hand.

  A second solution is to write a script to run serial tests and filter
  out the text added by the scheduler.  A sample script used on SDSC
  DataStar is given below, but you will probably have to customize it
  for your installation.

  Observe that the basic idea is to insert the script as the first item
  on the command line which executes the test.  The script then
  executes the test and filters out the offending text before passing
  it on.

        #!/bin/csh

        set STDOUT_FILE=~/bin/serial_filter.stdout
        set STDERR_FILE=~/bin/serial_filter.stderr

        rm -f $STDOUT_FILE $STDERR_FILE

        ($* > $STDOUT_FILE) >& $STDERR_FILE

        set RETURN_VALUE=$status

        cat $STDOUT_FILE

        tail +3 $STDERR_FILE

        exit $RETURN_VALUE

  You get the HDF make files and test scipts to execute your filter script
  by setting the environment variable "RUNSERIAL" to the full path of the
  script prior to running configure for parallel builds.  Remember to
  "unsetenv RUNSERIAL" before running configure for a serial build.

  Note that the RUNSERIAL environment variable exists so that we can
  can prefix serial runs as necessary on the target system.  On DataStar,
  no prefix is necessary.  However on an MPICH system, the prefix might
  have to be set to something like "/usr/local/mpi/bin/mpirun -np 1" to
  get the serial tests to run at all.

  In such cases, you will have to include the regular prefix in your
  filter script.