← Back to branch summary

~uhh-ssd/+junk/humidity_readout

« back to all changes in this revision

Viewing changes to plplot/plplot-5.9.9/bindings/f77/README.f77API

  • Committer: Joachim Erfle
  • Date: 2013-07-24 13:53:41 UTC
  • Revision ID: joachim.erfle@desy.de-20130724135341-1qojpp701zsn009p
initial commit

Show diffs side-by-side

added added

removed removed

Lines of Context:
plplot/plplot-5.9.9/bindings/f77/README.f77API
 
1
The following files work together to define the fortran API for PLplot.
 
2
The general rule is
 
3
 
 
4
* use sfstubs.fm4 for routines that have character strings;
 
5
 
 
6
* use configurable.f.in for fortran routines that must be configurable
 
7
(i.e, plparseopts).
 
8
 
 
9
* use sc3d.c for 3D perspective routines (plmesh, plot3d, and plsurf3d and
 
10
friends [which necessarily must have special handling of 2D arrays]);
 
11
 
 
12
* use sccont.c for contour and shade plots (which necessarily must have
 
13
special handling of 2D arrays and which are wrapped in sfstubs.f(m4)); and
 
14
 
 
15
* use scstubs.c for everything else (i.e., the non-special cases).
 
16
 
 
17
Here are more details about the files in this directory:
 
18
 
 
19
* plstubs.h defines the name style for the stub routines.  Every fortran
 
20
PLplot routine that has a corresponding C routine must have an entry in this
 
21
file.
 
22
 
 
23
* sc3d.c contains complete stubs for plmesh and plot3d.
 
24
 
 
25
* sfstubs.fm4 has a name which is a historical artifact because originally
 
26
this was an odd mixture of fortran and m4 processing directives which were
 
27
processed to form either a single-precision or double-precision version.
 
28
Now it is the double-precision form of the code only which is simply
 
29
copied when double-precision libraries are wanted, and a simple sed script
 
30
double2single.sed is used to convert to single-precision when single-precision
 
31
libraries are wanted.
 
32
 
 
33
* double2single.sed.  Simple sed commands to convert from sfstubs.fm4 from
 
34
double to single precision.  Currently the only double-precision construct
 
35
occurring in sfstubs.fm4 is "real*8" so that is the only string that
 
36
double2single.sed converts.  But if sfstubs.fm4 is changed to include
 
37
other double-precison constructs such as double-precision numbers, then
 
38
it will be necessary to change double2single.sed to deal with it.
 
39
 
 
40
* sfstubs.f is copied from sfstubs.fm4 at build time.  It (and sfstubs.fm4)
 
41
contains all PLplot fortran API where character strings or other
 
42
complications are more easily handled in fortran than C.  The called C
 
43
equivalents have a suffix of "7" on the name to avoid fortran name clashes
 
44
and also to identify in the following C routines those which have a special
 
45
wrapper in sfstubs.f.
 
46
 
 
47
* sfstubs.h contains fortran code (common block definitions) used repeatedly
 
48
in sfstubs.f(m4).
 
49
 
 
50
* strutil.f contains fortran string utilities that allows for translating from
 
51
fortran to C null-terminated strings or vice versa.
 
52
 
 
53
* sccont.c contains plcont and plshade related routines (with a 7 suffix
 
54
meaning there is a wrapper in sfstubs.f(m4). Also contains plvect routines.
 
55
 
 
56
* scstubs.c contains all the simple (non-3D, non-cont, non-shade) API plus
 
57
some 7-suffix routines that have a special wrapper in sfstubs.f(m4).
 
58
 
 
59
 
 
60
Linking DLLs on Windows
 
61
-----------------------
 
62
On Windows it is necessary to specify which routines and functions in
 
63
a DLL should be exported, i.e. made visible to external programs. While
 
64
there compiler-specific ways to do that within the source code we prefer
 
65
to do it via so-called linker definition files (.def).
 
66
 
 
67
Basically, these files contain a list of all the subroutines and functions
 
68
that need to be exported, one name per line. The difficulty is, however,
 
69
that these names are the names as constructed by the compiler. Each compiler
 
70
is free to use its own scheme for turning the name found in the Fortran code
 
71
into a "linker" name".
 
72
 
 
73
For the Compaq Visual Fortran the scheme is this:
 
74
 
 
75
subroutine/function Name( a, b ) ==> _NAME@8
 
76
 
 
77
where the @8 represents the number of bytes in the argument list (the
 
78
hidden argument representing the length of string arguments must be
 
79
included in that count)
 
80
 
 
81
For the MinGW gfortran compiler the scheme is somewhat simpler:
 
82
 
 
83
subroutine/function Name( a, b ) ==> name_
 
84
subroutine/function My_Name( a, b ) ==> my_name__
 
85
 
 
86
For the Cygwin gfortran compiler all symbols are automatically exported. There
 
87
is no need for a linker definition file.
 
88
 
 
89
One way to find out what the internally produced names are is to examine the
 
90
object file (.obj) that is produced by the compiler.