[svn-r2576] Purpose:

	Adding the Fortran interface to the HDF5 library
Description:
	Fortran is now a subdirectory of the HDF5 library tree.
Platforms tested:
	Solaris and IRIX (O2K)

1 files changed, 240 insertions, 0 deletions

diff --git a/fortran/src/README b/fortran/src/README
new file mode 100644
index 0000000..6dcc0e0
--- /dev/null
+++ b/fortran/src/README
@@ -0,0 +1,240 @@
+
+          README for the FORTRAN90 Prototype APIs to HDF5
+
+
+This distribution contains the HDF5 FORTRAN90 APIs source code (prototype) 
+based on the HDF5 1.2.2 release (ftp://ftp.ncsa.uiuc.edu/HDF/HDF5/current), 
+tests and examples.
+
+This prototype supports a selected subset of the HDF5 Library functionality. 
+A complete list of the Fortran subroutines can be found in the HDF5 
+Reference Manual provided with this release.
+Check the online documentation at http://hdf.ncsa.uiuc.edu/HDF5/doc (select 
+the "HDF5 Fortran90 Docs" link at the bottom of the left-hand column) or 
+H5_F90.R1.2.2.RefMan.tar at ftp://hdf.ncsa.uiuc.edu/HDF5/fortran .
+
+Changes since last release (October 1999)
+=========================================
+* Support for Linux 
+* Support for parallel features (tested on O2K platform only)
+* Most of the functions from the H5R, H5P, H5T, H5E and H5I interfaces were 
+  implemented. See Reference Manual for complete list. The new functions  
+  include support for object and dataset region references, and for 
+  compound datatypes.
+* This prototype supports more predefined types. See list below in 
+  the "About the Fortran APIs" section.
+* This prototype supports T3E and T3E with mpt 1.3. One has to modify
+  H5Dff.f90, H5Aff.f90, H5Pff.f90 to comment lines with the module procedures for
+  double precision datatypes. See source code.
+
+Supported platforms
+===================
+The FORTRAN90 APIs provided here are known to work with the
+following platforms and compilers:
+
+     *  SunOS 5.6  with  WorkshopCompilers 4.2 Fortran 90 1.2
+     *  SunOS 5.7  with  WorkshopCompilers 5.0 Fortran 90 2.0 
+     *  OSF1 V4.0  with  Digital Fortran 90 4.1 
+     *  IRIX64 6.5 (64 option only) with  MIPSpro Compilers: Version 7.3.1m    
+                          mpt.1.4
+     *  Linux RedHat 6.1, Kernel 2.2.12 with PGF90
+     *  T3E with Cray Fortran: Version 3.4.0.0
+            with mpt 1.3
+
+Compilation
+===========
+
+1. Install HDF5 Release 1.2.2 on your system
+   (ftp://ftp.ncsa.uiuc.edu/HDF/HDF5/current).  If you are using a
+   binary distribution provided by the HDF group, make sure that a GZIP 
+   library is installed on your system. If you do not have a GZIP library,
+   you may copy it from the HDF FTP server.
+
+2. In the src directory copy H5fortran_types.f90_<system> to 
+   H5fortran_types.f90, where <system> is one of the following:
+
+     solaris
+     digunix
+     irix
+     linux
+
+   Example: On Digital Unix systems use the following command
+            cp H5fortran_types.f90_digunix H5fortran_types.f90
+
+3. Edit Makefile_<system >in the src/, test/ and examples/ directories
+   to specify the locations of the HDF5 C Library, the GZIP Library, and the 
+   corresponding include files on your system.
+
+4. In the src directory, run make to create the HDF5 FORTRAN90 library 
+   hdf5_fortran.a
+             make -f Makefile_<system>
+             
+   Example: On Solaris run
+            make -f Makefile_solaris
+
+   The Fortran library hdf5_fortran.a will be created.
+
+5. In the test directory, build tests by running  
+            make -f Makefile_<system>
+   This command will build fortranlib_test, fflush1 and fflush2 executables.
+   Run those executables to make sure that the library works on your system.
+
+6. In the examples directory, run
+            make -f Makefile_<system>
+   to build the following examples:
+   
+   fileexample       - creates an HDF5 file
+   dsetexample       - creates an empty dataset of integers
+   rwdsetexample     - writes and reads to the dataset created by dsetexample
+   groupexample      - creates a group in the file
+   grpsexample       - creates groups using absolute and relative names
+   grpdsetexample    - creates datasets in the groups
+   hyperslabexample  - writes and reads a hyperslab
+   selectele         - writes element selections
+   grpit             - iterates through the members of the group
+   attrexample       - creates and writes a dataset attribute
+   compound          - creates, writes and reads one dim array of structures
+   mountexample      - shows how to use mounting files to access a dataset
+   refobjexample     - creates and stores references to the objects
+   refregexample     - creates and stores references to the dataset regions
+
+   The script run_example.sh runs the examples in the appropriate order. 
+
+   Use the HDF5 utility, h5dump, to see the content of the created HDF5 files.
+
+7. Install the HDF5 Reference Manual (in HTML format).  The manual
+   can be found in the Unix tar file H5_F90.R1.2.2.RefMan.tar
+   on the ftp server and is served over the Web from
+   http://hdf.ncsa.uiuc.edu/HDF5/doc/ (select the "HDF5 Fortran90 Docs" 
+   link at the bottom of the left-hand column).
+
+
+8. Send bug reports and comments to hdfhelp@ncsa.uiuc.edu
+
+User's Guide Notes
++++++++++++++++++++
+
+About the source code organization
+==================================
+
+The Fortran APIs are organized in modules parallel to the HDF5 Interfaces.
+Each module is in a separate file with the name H5*ff.f.  Corresponding C
+stubs are in the H5*f.c files.  For example, the Fortran File APIs are in 
+the file H5Fff.f and the corresponding C stubs are in the file H5Ff.c. 
+
+Each module contains Fortran definitions of the constants, interfaces to 
+the subroutines if needed, and the subroutines themselves.  
+
+Users must use constant names in their programs instead of the numerical 
+values, as the numerical values are subject to change without notice. 
+
+About the Fortran APIs 
+=======================
+
+*  The Fortran APIs come in the form of Fortran subroutines.
+
+*  Each Fortran subroutine name is derived from the corresponding C function
+   name by adding "_f" to the name.  For example, the name of the C function 
+   to create an HDF5 file is H5Fcreate;  the corresponding Fortran subroutine 
+   is h5fcreate_f. 
+
+*  A description of each Fortran subroutine and its parameters can be found 
+   following the description of the corresponding C function in the 
+   Reference Manual provided with this release.  The manual can be found in 
+   the Unix tar file H5_F90.R1.2.2.tar in this directory and
+   is served over the Web from http://hdf.ncsa.uiuc.edu/HDF5/doc/ (select 
+   the "HDF5 Fortran90 Docs" link at the bottom of the left-hand column).
+
+*  The parameter list for each Fortran subroutine has two more parameters
+   than the corresponding C function.  These additional parameters hold 
+   the return value and an error code.  The order of the Fortran subroutine 
+   parameters may differ from the order of the C function parameters. 
+   The Fortran subroutine parameters are listed in the following order: 
+      -- required input parameters,
+      -- output parameters, including return value and error code, and 
+      -- optional input parameters.
+   For example, the C function to create a dataset has the following 
+   prototype:
+
+       hid_t H5Dcreate(hid_it loc_id, char *name, hid_t type_id, 
+             hid_t space_id, hid_t creation_prp);
+   
+   The corresponding Fortran subroutine has the following form:
+   
+       SUBROUTINE h5dcreate_f(loc_id, name, type_id, space_id, dset_id, 
+             hdferr, creation_prp)
+  
+   The first four parameters of the Fortran subroutine correspond to the 
+   C function parameters.  The fifth parameter dset_id is an output 
+   parameter and contains a valid dataset identifier if the value of the 
+   sixth output parameter hdferr indicates successful completion. 
+   (Error code descriptions are provided with the subroutine descriptions 
+   in the Reference Manual.)  The seventh input parameter creation_prp 
+   is optional, and may be omitted when the default creation property 
+   list is used.
+
+*  Parameters to the Fortran subroutines have one of the following 
+   predefined datatypes (see the file H5fortran_types.f90 for KIND 
+   definitions):
+   
+        INTEGER(HID_T)      compares with hid_t type in HDF5 C APIs
+        INTEGER(HSIZE_T)    compares with hsize_t in HDF5 C APIs
+        INTEGER(HSSIZE_T)   compares with hssize_t in HDF5 C APIs
+        INTEGER(SIZE_T)     compares with the C size_t type
+   These integer types usually correspond to 4 or 8 byte integers, 
+   depending on the FORTRAN90 compiler and corresponding HDF5 
+   C library definitions.
+   
+   The H5R module defines two types: 
+        TYPE(HOBJ_REF_T_F)  compares to the hobj_ref_t in HDF5 C API
+        TYPE(HDSET_REG_REF_T_F) compares to hdset_reg_ref_t in HDF5 C API
+   These types are represented by character arrays now. 
+   The internal representation can be changed in the future.
+
+*  Each Fortran application must call the h5init_types subroutine to 
+   initialize the Fortran predefined datatypes before calling the HDF5 Fortran 
+   subroutines.  The application must call the h5close_types subroutine 
+   after all calls to the HDF5 Fortran Library. 
+
+*  The following predefined types are implemented in this prototype: 
+
+                                H5T_NATIVE_INTEGER
+                                H5T_NATIVE_REAL
+                                H5T_NATIVE_DOUBLE
+                                H5T_NATIVE_CHARACTER
+                                H5T_STD_REF_OBJ
+                                H5T_STD_REF_DSETREG
+                                H5T_IEEE_F32BE
+                                H5T_IEEE_F32LE
+                                H5T_IEEE_F64BE
+                                H5T_IEEE_F64LE
+                                H5T_STD_I8BE
+                                H5T_STD_I8LE
+                                H5T_STD_I16BE
+                                H5T_STD_I16LE
+                                H5T_STD_I32BE
+                                H5T_STD_I32LE
+                                H5T_STD_I64BE
+                                H5T_STD_I64LE
+                                H5T_STD_U8BE
+                                H5T_STD_U8LE
+                                H5T_STD_U16BE
+                                H5T_STD_U16LE
+                                H5T_STD_U32BE
+                                H5T_STD_U32LE
+                                H5T_STD_U64BE
+                                H5T_STD_U64LE
+                                
+    
+*  When a C application reads data stored from a Fortran program, the data 
+   will appear to be transposed due to the difference in the C - Fortran 
+   storage order.  For example, if Fortran writes a 4x6 two-dimensional dataset 
+   to the file, a C program will read it as a 6x4 two-dimensional dataset into 
+   memory.  The HDF5 C utilities h5dump and h5ls display transposed data, if
+   data is written from a Fortran program.
+ 
+*  Fortran indices are 1 based.
+
+*  Compound datatype datasets can be written or read by atomic fields only.
+
+Not all of the APIs provided with this prototype have been fully tested.