diff options
author | Scot Breitenfeld <brtnfld@hdfgroup.org> | 2023-11-21 17:05:23 (GMT) |
---|---|---|
committer | GitHub <noreply@github.com> | 2023-11-21 17:05:23 (GMT) |
commit | 046440400f877ce1f6c94ccce0c17c0619647b42 (patch) | |
tree | 113fdfae4c543a01bdcebb922506a5a2e9490a39 /fortran/src/README | |
parent | 37c75e057b1dadc1837ba5ae351565f8763fe89c (diff) | |
download | hdf5-046440400f877ce1f6c94ccce0c17c0619647b42.zip hdf5-046440400f877ce1f6c94ccce0c17c0619647b42.tar.gz hdf5-046440400f877ce1f6c94ccce0c17c0619647b42.tar.bz2 |
Moved the README to markdown and expanded its overview of the files, file generation, and other Fortran wrapper development practices as mentioned in the HDF5 architectural document. I added a new figure and included the SVG file and the original xfig file it was generated from. (#3862)
Diffstat (limited to 'fortran/src/README')
-rw-r--r-- | fortran/src/README | 133 |
1 files changed, 0 insertions, 133 deletions
diff --git a/fortran/src/README b/fortran/src/README deleted file mode 100644 index f73a59a..0000000 --- a/fortran/src/README +++ /dev/null @@ -1,133 +0,0 @@ -=================================== -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 - |