hdf5/fortran/src

===================================
README for the Fortran APIs to HDF5
===================================

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.F90.  Corresponding C
stubs are in the H5*f.c files.  For example, the Fortran File APIs are in 
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.  

Users must use constant names in their programs instead of the numerical 
values, as the numerical values are subject to change without notice. 

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.

*  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 usually 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 H5Dcreate2(hid_it loc_id, char *name, hid_t type_id, 
             hid_t space_id, hid_t link_creation_prp, hid_t dset_creation_prp,
             hid_t dset_access_prop);
   
   The corresponding Fortran subroutine has the following form:
   
       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. 
   (Error code descriptions are provided with the subroutine descriptions 
   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 Fortran compiler and corresponding HDF5 
   C library definitions.
   
*  Each Fortran application must call the h5open_f subroutine to 
   initialize the Fortran predefined datatypes before calling the HDF5 Fortran 
   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 
   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.

============================
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