1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
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
|
