diff options
Diffstat (limited to 'fortran/src/README')
| -rw-r--r-- | fortran/src/README | 134 |
1 files changed, 134 insertions, 0 deletions
diff --git a/fortran/src/README b/fortran/src/README new file mode 100644 index 0000000..a258e07 --- /dev/null +++ b/fortran/src/README @@ -0,0 +1,134 @@ +=================================== +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 + |