As discussed in the preceding section, PLplot's integer representation is a PLINT and its floating point representation is a PLFLT. To the Fortran 77 user, this most commonly translates to a type integer and type real, respectively. This is somewhat system dependent (and up to the installer of the package) so you should check the release notes to be sure, or just try it and see what happens.
Because the PLplot kernel is written in C, standard C syntax is used in the
description of each PLplot function. Thus to understand this manual it is
helpful to know a little about C, but fortunately the translation is very
easy and can be summarized here. As an example, the routine
plline call from C would look like:
plline(n,x,y);
|
call plline(n,x,y)
|
| PLFLT | real |
| PLINT | integer |
| char * | character |
| PLFLT * | real or real array |
| PLFLT ** | real array |
| "string" | 'string' |
| array[0] | array(1) |
The PLplot library comes with a set of Fortran 77 interface routines that allow the exact same call syntax (usually) regardless of whether calling from C or Fortran 77. In some cases, this means the subroutine name exceeds 8 characters in length. Nearly every Fortran 77 compiler available today allows subroutine names longer than 8 characters, so this should not be a problem (although if it ever is, in principle a truncated name could be defined for that platform).
These "stub" routines handle transforming the data from the normal Fortran 77 representation to that typically used in C. This includes:
Variables passed by value instead of by reference.
Fortran 77 passes all subroutine arguments by reference, i.e., a pointer to the argument value is pushed on the stack. In C all values, except for arrays (including char arrays), are passed by value, i.e., the argument value itself is pushed on the stack. The stub routine converts the Fortran 77 call by reference to a call by value. As an example, here is how the plpoin stub routine works. In your Fortran 77 program you might have a call to plpoin that looks something like
call plpoin(6,x,y,9) |
#include "plplot/plstubs.h"
void
PLPOIN(n, x, y, code)
PLINT *n, *code;
PLFLT *x, *y;
{
c_plpoin(*n, x, y, *code);
}
|
Get mapping between Fortran 77 and C namespace right (system dependent).
The external symbols (i.e. function and subroutine names) as you see them in your program often appear differently to the linker. For example, the Fortran 77 routine names may be converted to uppercase or lowercase, and/or have an underscore appended or prepended. This translation is handled entirely via redefinition of the stub routine names, which are macros. There are several options for compiling PLplot that simplify getting the name translation right (NEEDS DOCUMENTATION IF THESE STILL EXIST). In any case, once the name translation is established during installation, name translation is completely transparent to the user.
Translation of character string format from Fortran 77 to C.
Fortran 77 character strings are passed differently than other quantities, in that a string descriptor is pushed on the stack along with the string address. C doesn't want the descriptor, it wants a NULL terminated string. For routines that handle strings two stub routines are necessary, one written in Fortran 77 and one written in C. Your Fortran 77 program calls the Fortran 77 stub routine first. This stub converts the character string to a null terminated integer array and then calls the C stub routine. The C stub routine converts the integer array (type long) to the usual C string representation (which may be different, depending on whether your machine uses a big endian or little endian byte ordering; in any case the way it is done in PLplot is portable). See the plmtex stubs for an example of this.
Note that the portion of a Fortran 77 character string that exceeds 299 characters will not be plotted by the text routines (plmtex and plptex).
Multidimensional array arguments are changed from row-dominant to column-dominant ordering through use of a temporary array.
In Fortran 77, arrays are always stored so that the first index increases most rapidly as one steps through memory. This is called "row-dominant" storage. In C, on the other hand, the first index increases least rapidly, i.e. "column-dominant" ordering. Thus, two dimensional arrays (e.g. as passed to the contour or surface plotting routines) passed into PLplot must be transposed in order to get the proper two-dimensional relationship to the world coordinates. This is handled in the C stub routines by dynamic memory allocation of a temporary array. This is then set equal to the transpose of the passed in array and passed to the appropriate PLplot routine. The overhead associated with this is normally not important but could be a factor if you are using very large 2d arrays.
This all seems a little messy, but is very user friendly. Fortran 77 and C programmers can use the same basic interface to the library, which is a powerful plus for this method. The fact that stub routines are being used is completely transparent to the Fortran 77 programmer.
For more information on calling PLplot from Fortran 77, please see the example Fortran 77 programs (/examples/f77/x??f.f) through distributed with PLplot.