mirror of
https://github.com/HDFGroup/hdf5.git
synced 2024-11-21 01:04:10 +08:00
Combined the README_DEVEL and README, and removed out-dated README material
This commit is contained in:
M. Scot Breitenfeld
parent
ccb4e9ed9a
commit
e3d8dacaad
@ -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.
|
||||
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).
|
||||
|
||||
* 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)
|
||||
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 have one of the following
|
||||
predefined datatypes (see the file H5fortran_types.f90 for KIND
|
||||
definitions):
|
||||
* 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.
|
||||
subroutines. The application should call the h5close_f 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
|
||||
|
||||
|
||||
* 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.
|
||||
|
||||
@ -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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user