************************************************************************** Reading data from HDF-5, HDF-EOS and netCDF4 files with Fortran-90 Current version: 1.95 (23 February 2016) ************************************************************************** 0. Introduction --------------- This module is written to read user selected datasets and attributes from HDF-5, HDF-EOS and netCDF-4 datafiles for further processing without having to go into the details of reading such files. The user only needs to know what he/she wants to read and of what data type (integer, real, string, ...) and rank (scalar, vector, ...) it is. The package includes a sample data file and a sample program showing how the module has to be used. The routines have been tested on only a few HDF-5, HDF-EOS and netCDF-4 files and does certainly not cover all possible types of data in such files. Note that netCDF-3 files and some netCDF-4 files of a specific kind cannot be read with these routines, but these files can be converted to the right netCDF-4 format using "nccopy -k 4 foo3.nc foo4.nc". The most recent version of the package is available at: http://josvg.home.xs4all.nl/BIRA/tools/hdf5read.html or: http://uv-vis.aeronomie.be/software/tools/hdf5read.php 1. Contents of this file ------------------------ 0. Introduction 1. Contents of this file 2. Contents of the package 3. Compiling the module 4. Usage of the module 5. Overview of data read by the module 6. Error handling 7. Known issues and problems 8. Also available in the module 9. Authors and version history 2. Contents of the package -------------------------- The package contains the following files GPL.txt -- a copy of the GNU Public License, under which this package is released Makefile -- for compiling the sample program README.txt -- this file readh5dataset.f90 -- file with the F-90 modules sample-read.f90 -- sample program sample-file.h5 -- sample HDF-5 file *) sample-file.out -- output of sample program to screen when run on the sample file sample-file.txt -- dump with h5dump of sample-file.h5 *) The original name of the sample data file was S-O3M_GOME_O3-SO2_L2_20080201230940_002_METOPA_06681_DLR_01.HDF5 which is a GOME-2 level-2 file with SO2 data produced by DLR (Germany). 3. Compiling the module ------------------------ Requirements for the module to work are a Fortran-90 compiler and linker, a suitable make utility and properly installed HDF-5 libraries. To compile and link the sample program, a Makefile is supplied in the package; just typing 'make' should do the trick and compile the sample test program. Compiling and linking on your system may require adapting the compiler and linker settings and the paths to the HDF-5 libraries. The Makefile is made for and tested with the GNU make utility. In order to run the code, one may also have to set the LD_LIBRARY_PATH environment variable, so that at run time the libraries can be found, depending on the HDF5 installation (the Makefile gives an example). 4. Usage of the module ---------------------- To use the module, add a "USE ReadH5dataset" statement to the calling routine or program. The calling routine or program must contain a variable of the same type and dimension (rank) as the dataset or attribute that is to be read. The exact sizes of arrays are determined automatically. The usage of the module is illustrated in the sample-read program, which can be run on the sample-file.h5 datafile: sample-read sample-file.h5 This writes some elements of the data file to the screen; see the file sample-file.out [note that there may be small differences depending on the compiler and operating system in the number of spaces and rounding of the numbers]. When reading a dataset or attribute from an HDF 5 file, call the generic routine H5ReadDataset: CALL H5ReadDataset ( filename, dsetname, dataset ) or in the case of compound data: CALL H5ReadDataset ( filename, dsetname, compoundsetname, dataset ) Alternatively, one can make the following generic calls (which sound better when reading an attribute) with exactly the same functionality: CALL H5ReadAttribute ( filename, attribname, attribute ) CALL H5ReadAttribute ( filename, attribname, compoundsetname, attribute ) In these calls are: 'filename' = a character type variable containing the name of the HDF-5 file 'dsetname' = the character type name of the dataset or attribute, including the full HDF-5 group hierarchy, using slashes as the divider symbol (e.g. "/DATA/GEOMETRY/radius"); be sure to use the right case on the hierarchy names 'attribname' = same as 'dsetname' in functionality 'compoundsetname' = name of the part of a compound set to read 'dataset' = a pointer type variable of the right rank and type, that will contain the dataset or attribute 'attribute' = same as 'dataset' in functionality 5. Overview of data read by the module -------------------------------------- The module is designed to read individual, user selected datasets and attributes from an HDF-5, HDF-EOS or netCDF-4 file. The following data types are supported: a) 0-, 1-, 2-, 3- or 4-dimensional datasets or attributes, which can be of integer, real or double precision data type (0-dim. means here a scalar). b) 0- and 1-dimensional character strings in attributes or datasets (0-dim. means here a single string, 1-dim. a 1-D array of strings). c) 0- and 1-dimensional integer, real or double parts of compound attributes or datasets (0-dim. means here a scalar); note that the different parts of a compound set have to be read separately. See the sample-read.f90 program for some examples. The routines handle datasets of groups, attributes of groups, as well as attributes of datasets of groups: //dataset //attribute //dataset/attribute where 'N' is 0, 1, 2, ... 6. Error handling ----------------- If an error occurs in either of the steps of the access to the data or when reading the data, the routine returns to the calling routine or program with the variable ErrorFlag set to -1 and the ErrorMessage string filled with a message. These two can be used for error tracing in the calling routine. Note that some routines return a possitive ErrorFlag number, which does _not_ indicate an error (which is a bit confusing). 7. Known issues and problems on 32-bit -------------------------------------- For version 1.7 the routines where tried under additional compilers. They already worked with 'ifort' and 'pgf90'. Added to that 'g95' and 'gfortran'. Using 'g95' works fine. Using 'gfortran' does not work: when running the sample-read it crashes. Frist this was when reading the 2-dim integer FittingNumberOfIterations, but after rearranging the reading blocks in sample-read.f90 and adding some new dataset reading, the problem occurs when reading VCD ... On the screen it says [broken into two lines to print here]: *** glibc detected *** sample-read: free(): invalid next size \ (fast): 0x09c36050 *** Followed by a backtrace that reveals no further clues as to what the problem actually is. It could be an issue of the HDF5 library with 'gfortran', who knows. When compiling on 64-bit (checked for version 1.8), the 'gfortran' made executable runs without any problems. 8. Also available in the module ------------------------------- Apart from the data reading routines, the module also makes the following function available for use: INTEGER FUNCTION LengString(str) This function determines the length of a given string, that is: the last non-space character of a given string (omitting also the NULL character, tab, carriage return, line feed, etc). The function is used in the sample-read.f90 program. 9. Authors and version history ------------------------------ The original module was written by Jeroen van Gent, when at the Royal Netherlands Meteorological Institute (KNMI), De Bilt, The Netherlands. The module has been extended by Jos van Geffen and Jeroen van Gent at the Belgian Institute for Space Aeronomie (BIRA-IASB), Brussels, Belgium. For contact info, see the webpage(s) mentioned near the top of this file. v0.9 - 2003 - original version: reads 1-, 2- and 3-dimensional integer, real or double datasets (no attributes) v1.0 - 2004/12/20 - integer type mismatch resolved in calls to h5dread_f v1.1 - 2008/02/12 - comments extended v1.2 - 2008/04/09 - streamlined opening of groups, datasets, etc. - added attribute reading to existing routines - added error handling and debug messaging 2008/04/11 - added 0-dim. integer, real, double reading - added 0-dim. string reading 2008/04/13 - added 1-dim. string reading v1.3 - 2008/04/21 - added 0- and 1-dim compound reading (int,real,double) - move string and compound reading into interface - error handling of (de)allocate statements v1.5 - 2008/04/23 - public release as package via website of BIRA-IASB v1.6 - 2011/07/25 - made determination of object (group,dataset,...) type value more general, as it appears their definition had changed in the HDF5 package - corrected two typos and a string comparison - added public release via personal website v1.7 - 2012/04/19 - try compiling with "gfortran" and "g95"; adapted the Makefile accordingly - in subroutine DebugMessage had in the print format '(a,1x,i)' but "gfortran" and "g95" do not except that ["Nonnegative width required in format string"] so changed it to '(a,1x,i5)', which should be enough - running with "g95" gave "remaining memory" messages at the end, so added "deallocate" statements at the end of the sample-read.f90 program - two missing deallocation status variables added in readh5dataset.f90 - added a few other types of dataset reading in the sample-read.f90 program, reordered the reading, and updated the sample-file.out - updated README.txt PROBLEM - running with "gfortran" fails ... see point 7 above v1.8 - 2012/10/25 - when testing compilation on a 64-bit machine repaired some type declarations - compiling and running works on 64-bit for compilers 'ifort', 'pgf90', 'g95' and 'gfortran' v1.9 - 2015/12/01 - repaired a small bug in H5Read_init - added 4-dimension integer, real and double datasets PROBLEM - compilation with 'g95' cannot be tested anymore due to a problem with the appropriate HDF-5 library v1.95 - 2016/02/23 - repaired a small bug in H5ReadInteger2D **************************************************************************