1
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
5
>Fortran Language</TITLE
8
CONTENT="Modular DocBook HTML Stylesheet Version 1.7"><LINK
10
TITLE="The PLplot Plotting Library"
11
HREF="index.html"><LINK
13
TITLE=" Language Bindings "
14
HREF="p2080.html"><LINK
19
TITLE="A C++ Interface for PLplot"
20
HREF="cplusplus.html"><LINK
23
HREF="stylesheet.css"></HEAD
34
SUMMARY="Header navigation table"
43
>The PLplot Plotting Library: Programmer's Reference Manual</TH
80
>Chapter 8. Fortran Language</H1
82
>As discussed in the preceding section, PLplot's integer representation is a
83
PLINT and its floating point representation is a PLFLT. To the
84
Fortran user, this most commonly translates to a type
92
>, respectively. This is somewhat system dependent (and up to
93
the installer of the package) so you should check the release notes to be
94
sure, or just try it and see what happens.
97
>Because the PLplot kernel is written in C, standard C syntax is used in the
98
description of each PLplot function. Thus to understand this manual it is
99
helpful to know a little about C, but fortunately the translation is very
100
easy and can be summarized here. As an example, the routine
107
> call from C would look like:
113
CLASS="programlisting"
120
while from Fortran it would look like:
126
CLASS="programlisting"
147
declared as type <VAR
150
> (arrays in this case).
152
used in the text translates roughly as follows:
154
CLASS="informaltable"
168
ALIGN="center"><TBODY
191
>real or real array</TD
223
In C there are two ways to pass a variable --- by value (the default) or by
224
reference (pointer), whereas only the latter is used by Fortran.
225
Therefore when you see references in the text to <SPAN
232
argument or a pointer argument (e.g. <VAR
235
>), you simply use an
236
ordinary Fortran variable or array name.
239
>The PLplot library comes with a set of Fortran interface routines that
240
allow the exact same call syntax (usually) regardless of whether calling
241
from C or Fortran. In some cases, this means the subroutine name <SPAN
245
>exceeds 8 characters in length</I
247
>. Nearly every Fortran compiler
249
today allows subroutine names longer than 8 characters, so this should not
250
be a problem (although if it ever is, in principle a truncated name could
251
be defined for that platform).
257
> routines handle transforming the data
258
from the normal Fortran representation to that typically used in C. This
265
>Variables passed by value instead of by reference.
268
>Fortran passes all subroutine arguments by reference, i.e., a pointer to the
269
argument value is pushed on the stack. In C all values, except for arrays
270
(including char arrays), are passed by value, i.e., the argument value
271
itself is pushed on the stack. The stub routine converts the Fortran call
272
by reference to a call by value. As an example, here is how the plpoin stub
273
routine works. In your Fortran program you might have a call to plpoin that
280
CLASS="programlisting"
281
> call plpoin(6,x,y,9)
287
where x and y are arrays with 6 elements and you want to plot symbol 9.
288
As strange as it seems (at least to C programmers) the constants 6 and
289
9 are passed by reference. This will actually call the following C
290
stub routine (included in entirety)
296
CLASS="programlisting"
297
>#include "plplot/plstubs.h"
300
PLPOIN(n, x, y, code)
304
c_plpoin(*n, x, y, *code);
311
All this stub routine does is convert the number of points
319
> to call by value (i.e. pushes their value on the stack)
320
and then calls the C plpoin library routine.
325
>Get mapping between Fortran and C namespace right (system dependent).
328
>The external symbols (i.e. function and subroutine names) as you see them
329
in your program often appear differently to the linker. For example, the
330
Fortran routine names may be converted to uppercase or lowercase, and/or
331
have an underscore appended or prepended. This translation is handled
332
entirely via redefinition of the stub routine names, which are macros.
333
There are several options for compiling PLplot that simplify getting the
334
name translation right (NEEDS DOCUMENTATION IF THESE STILL EXIST). In any
335
case, once the name translation is established during installation, name
336
translation is completely transparent to the user.
341
>Translation of character string format from Fortran to C.
344
>Fortran character strings are passed differently than other quantities, in
345
that a string descriptor is pushed on the stack along with the string
346
address. C doesn't want the descriptor, it wants a NULL terminated string.
347
For routines that handle strings two stub routines are necessary, one
348
written in Fortran and one written in C. Your Fortran program calls the
349
Fortran stub routine first. This stub converts the character string to a
350
null terminated integer array and then calls the C stub routine. The C
351
stub routine converts the integer array (type <VAR
355
string representation (which may be different, depending on whether your
356
machine uses a big endian or little endian byte ordering; in any case the
357
way it is done in PLplot is portable). See the <VAR
364
>Note that the portion of a Fortran character string that exceeds 299
365
characters will not be plotted by the text routines (<VAR
377
>Multidimensional array arguments are changed from row-dominant to
378
column-dominant ordering through use of a temporary array.
381
>In Fortran, arrays are always stored so that the first index increases most
382
rapidly as one steps through memory. This is called
385
>"row-dominant"</SPAN
387
storage. In C, on the other hand, the first index increases
397
>"column-dominant"</SPAN
398
> ordering. Thus, two dimensional arrays
399
(e.g. as passed to the contour or surface plotting routines) passed into
400
PLplot must be transposed in order to get the proper two-dimensional
401
relationship to the world coordinates. This is handled in the C stub
402
routines by dynamic memory allocation of a temporary array. This is then set
403
equal to the transpose of the passed in array and passed to the appropriate
404
PLplot routine. The overhead associated with this is normally not important
405
but could be a factor if you are using very large 2d arrays.
412
>This all seems a little messy, but is very user friendly. Fortran and C
413
programmers can use the same basic interface to the library, which is a
414
powerful plus for this method. The fact that stub routines are being used
415
is completely transparent to the Fortran programmer.
418
>For more information on calling PLplot from Fortran, please see the
419
example Fortran programs (<TT
435
SUMMARY="Footer navigation table"
464
HREF="cplusplus.html"
488
>A C++ Interface for PLplot</TD
b'\\ No newline at end of file'
added
removed
doc/docbook/src/fortran.html
