Merge pull request #410 in HDFFV/hdf5 from ~BRTNFLD/hdf5_msb:develop to develop

* commit '265950a83a68ea55b5bc8dcbefa2d09b4f8110be':
  updated with README changes
  Combined the README_DEVEL and README, and removed out-dated README material

3 files changed, 78 insertions, 221 deletions

diff --git a/MANIFEST b/MANIFEST
index b312cab..5710f6c 100644
--- a/MANIFEST
+++ b/MANIFEST
@@ -247,7 +247,6 @@
 ./fortran/src/HDF5.F90
 ./fortran/src/Makefile.am
 ./fortran/src/README
-./fortran/src/README_DEVELOPEMENT   _DO_NOT_DISTRIBUTE_
 ./fortran/src/h5fc.in
 ./fortran/src/hdf5_fortrandll.def.in
 
diff --git a/fortran/src/README b/fortran/src/README
index 7af5df3..a258e07 100644
--- a/fortran/src/README
+++ b/fortran/src/README
@@ -1,122 +1,18 @@
+===================================
+README for the Fortran APIs to HDF5
+===================================
 
-          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 
-     *  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
-     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
-   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
-+++++++++++++++++++
+This directory contains Fortran APIs for HDF5 Library functionality.
+A complete list of implemented Fortran subroutines can be found in the HDF5 
+Reference Manual.
 
 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
+Each module is in a separate file with the name H5*ff.F90.  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. 
+the file H5Fff.F90 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.  
@@ -124,31 +20,29 @@ 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 
-=======================
+Quick overview of the Fortran APIs 
+==============================================
+ 
+*  An in-depth description of each Fortran API and its parameters can 
+   be found in the HDF5 Reference Manual.
 
 *  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).
+   is h5fcreate_f.
 
-*  The parameter list for each Fortran subroutine has two more parameters
-   than the corresponding C function.  These additional parameters hold 
+*  The parameter list for each Fortran subroutine usually has two more parameters
+   than the corresponding C function.  These additional parameters typically 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: 
+   parameters may differ from the order of the C function parameters.
+ 
+   The Fortran subroutine parameters are usually listed in the following order: 
       -- required input parameters,
       -- output parameters, including return value and error code, and 
-      -- optional input parameters.
+         optional input parameters.
+
    For example, the C function to create a dataset has the following 
    prototype:
 
@@ -158,72 +52,35 @@ About the Fortran APIs
    
    The corresponding Fortran subroutine has the following form:
    
-       SUBROUTINE h5dcreate_f(loc_id, name, type_id, space_id, dset_id, 
-             hdferr, creation_prp)
-  
+       SUBROUTINE h5dcreate_f(loc_id, name, type_id, space_id, dset_id, &
+       hdferr, dset_creation_prp, link_creation_prp, dset_access_prop)
+
    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. 
+   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.
-   (XXX: Update this! - QAK)
-
-*  Parameters to the Fortran subroutines have one of the following 
-   predefined datatypes (see the file H5fortran_types.f90 for KIND 
-   definitions):
+   in the Reference Manual.)  The last three input parameters are optional 
+   and may be omitted, resulting in default values being used.
+
+*  Parameters to the Fortran subroutines typically include 
+   predefined datatypes (see the build-time generated file 
+   H5fortran_types.F90 for a complete listing):
    
         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 
+   depending on the Fortran 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 
+*  Each Fortran application must call the h5open_f 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
-                                
-    
+   subroutines.  The application should call the h5close_f subroutine 
+   after all calls to the HDF5 Fortran Library.
+
 *  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 
@@ -233,6 +90,45 @@ About the Fortran APIs
  
 *  Fortran indices are 1 based.
 
-*  Compound datatype datasets can be written or read by atomic fields only.
+============================
+FOR DEVELOPERS
+============================
+
+Procedure to add a new function
+----------------------------------
+
+(1) Edit the fortran/src/H5*ff.F90 file
+(2) Edit the fortran/src/H5*f.c file
+(3) Edit the fortran/src/H5f90proto.h file
+(4) Add the new function to fortran/src/hdf5_fortrandll.def.in
+
+Procedure for passing C variables to Fortran
+---------------------------------------------
+
+(1) Find the C struct name you are interested in: 
+	(a) src/H5public.h if it is a generic type, i.e. H5_*
+            or
+        (b) src/H5*public.h if is a specific type, i.e. H5*_ 
+                            
+(2) Put that structure into an array that will be passed to fortran in:
+        (a) fortran/src/H5_f.c (add to nh5init_flags_c subroutine)
+        (b) edit fortran/src/H5f90proto.h and edit nh5init_flags_c interface call
+                         
+(3) Edit the function call in fortran/src/H5_ff.F90
+        (a) edit the call:  FUNCTION h5init_flags_c 
+        (b) edit h5init_flags_c call in h5open_f to match the number of arguments passing
+                             
+(4) add the size of the array and array to fortran/src/H5f90global.F90 
+         - must match the size found it H5_f.c
+
+NOTE: To just add a default C value argument, do steps (2a) and (4) 
+
+
+Procedure for adding a new file to the repository
+--------------------------------------------------
+
+Add the name of the file to the: 
+    (1) Makefile.am located in the same directory as the newfile
+    (2) CMakeLists.txt located in the same directory as the newfile
+    (3) MANIFEST located in the top level directory
 
-Not all of the APIs provided with this prototype have been fully tested. 
diff --git a/fortran/src/README_DEVELOPEMENT b/fortran/src/README_DEVELOPEMENT
deleted file mode 100644
index 43982e1..0000000
--- a/fortran/src/README_DEVELOPEMENT
+++ /dev/null
@@ -1,38 +0,0 @@
-Procedure to add a new function
----------------------------------
-
-(1) Edit the fortran/src/H5*ff.f90 file
-(2) Edit the fortran/src/H5*f.c file
-(3) Edit the fortran/src/H5f90proto.h file
-(4) Add the new function to fortran/src/hdf5_fortrandll.def.in
-
-Procedure for passing C variables to Fortran
----------------------------------------------
-
-(1) Find the C struct name you are interested in: 
-	(a) src/H5public.h if it is a generic type, i.e. H5_*
-            or
-        (b) src/H5*public.h if is a specific type, i.e. H5*_ 
-                            
-(2) Put that structure into an array that will be passed to fortran in:
-        (a) fortran/src/H5_f.c (add to nh5init_flags_c subroutine)
-        (b) edit fortran/src/H5f90proto.h and edit nh5init_flags_c interface call
-                         
-(3) Edit the function call in fortran/src/H5_ff.f90
-        (a) edit the call:  FUNCTION h5init_flags_c 
-        (b) edit h5init_flags_c call in h5open_f to match the number of arguments passing
-                             
-(4) add the size of the array and array to fortran/src/H5f90global.f90 
-         - must match the size found it H5_f.c
-
-NOTE: To just add a default C value argument, do steps (2a) and (4) 
-
-
-Procedure for adding a new file to the repository
---------------------------------------------------
-
-Add the name of the file to the: 
-    (1) Makefile.am located in the same directory as the newfile
-    (2) CMakeLists.txt located in the same directory as the newfile
-    (3) MANIFEST located in the top level directory
-