\chapter{Programmer interface}
\label{ap:lang}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section {C language}

The argument types given in this manual (PLFLT and PLINT) are typedefs for
the actual argument type.  A PLINT is actually a type {\tt long} and should
not be changed.  A PLFLT can be either a {\tt float} or {\tt double}; this
choice is made when the package is installed and on a Unix system (for
example) may result in a PLplot library named {\tt libplplotf.a} in single
precision and {\tt libplplotd.a} in double precision.

These and other constants used by PLplot are defined in the main header file
{\tt plplot.h}, which must be included by the user program.  This file also
contains all of the function prototypes, machine dependent defines, and
redefinition of the C-language bindings that conflict with the Fortran names
(more on this later).  {\tt plplot.h} obtains its values for PLFLT, PLINT,
and PLARGS (a macro for conditionally generating prototype argument lists)
from FLOAT (typedef), INT (typedef), and PROTO (macro), respectively.
The latter are defined in the file
{\tt chdr.h}.  The user is encouraged to use FLOAT, INT, and PROTO in
his/her own code, and modify {\tt chdr.h} according to taste.  It is not
actually necessary to declare variables as FLOAT and INT except when they
are pointers, as automatic conversion to the right type will otherwise occur
(if using a Standard C compiler; else K\&R style automatic promotion will
occur).  The only code in {\tt plplot.h} that directly depends on these
settings is as follows:
\begin{verbatim}
#include "chdr.h"

/* change from chdr.h conventions to plplot ones */

typedef FLOAT PLFLT;
typedef INT   PLINT;
#define PLARGS(a) PROTO(a)
\end{verbatim}

PLplot is capable of being compiled with Standard C (ANSI) mode on or off.
This is toggled via the macro PLSTDC, and set automatically if \_\_STDC\_\_
is defined.  If PLSTDC is defined, all functions are prototyped as allowed
under Standard C, and arguments passed exactly as specified in the
prototype.  If PLSTDC is not defined, however, function prototypes are
turned off and K\&R automatic argument promotion will occur, e.g.  {\tt
float $\rar$ double, int $\rar$ long}.  There is no middle ground!  A PLplot
library built with PLSTDC defined will not work (in general) with a program
built with PLSTDC undefined, and vice versa.  It is possible in principle to
build a library that will work under both Standard C and K\&R compilers
simultaneously (i.e.  by duplicating the K\&R promotion with the Standard C
prototype), but this seems to violate the spirit of the C standard and can
be confusing.  Eventually we will drop support for non-standard C compilers 
but for now have adopted this compromise.

In summary, PLplot will work using either a Standard or non-standard C
compiler, provided that you :
\begin{enumerate}
\item Include the PLplot main header file {\tt plplot.h}.
\item Make sure all pointer arguments are of the correct type
(the compiler should warn you if you forget, so don't worry, be happy).
\item Do not link a code compiled with PLSTDC defined to a PLplot library
compiled with PLSTDC undefined, or vice versa.
\item Use prototypes whenever possible to reduce type errors.
\end{enumerate}

Note that some Standard C compilers will give warnings when converting a
constant function argument to whatever is required by the prototype.  These
warnings can be ignored.

The one additional complicating factor concerns the use of stub routines to
interface with Fortran (see the following section for more explanation).  On
some systems, the Fortran \& C namespaces are set up to clobber each other.
More reasonable (from our viewpoint) is to agree on a standard map between
namespaces, such as the appending of an underscore to Fortran routine names
as is common on many Unix-like systems.  The only case where the shared
Fortran/C namespaces do any good is when passing a pointer to a like data
type, which represents only a small fraction of the cases that need to
be handled (which includes constant values passed on the stack, strings, and
two-dimensional arrays).

There are several ways to deal with this situation, but the least messy from
a user's perspective is to redefine those PLplot C function names which
conflict with the Fortran-interface stub routines.  The actual function
names are the same as those described in this document, but with a ``c\_''
prepended.  These macro definitions appear in the {\tt plplot.h} header file
and are otherwise harmless.  Therefore you can (and should) forget that most
of the names are being redefined to avoid the conflict and simply adhere to
the bindings as described in this manual.  Codes written under old versions
of PLplot (previous to 4.0) will require a recompile, however.

It is possible to compile the PLplot library so that the affected functions
retain their documented names, by specifying {\tt -DNOBRAINDEAD} on the
compile line.  Some reasons for doing this might be:  (a) you don't want to
include {\tt plplot.h} into your program for whatever reason, or (b) you are
debugging PLplot and wish to specify the documented names to the debugger.
In fact this procedure will work fine under SUNOS, with no Fortran/C
namespace collision.  But on other systems a special compiler switch may be
required to get it to work similarly, which is an extra burden on the user
and best avoided.

For more information on calling PLplot from C, please see the 14 example C
programs ({\tt x01c.c} through {\tt x14c.c}) distributed with PLplot.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section {Fortran language}

As discussed in the preceding section, PLplot's integer representation is a
PLINT and its floating point representation is a PLFLT.  To the
Fortran user, this most commonly translates to a type {\tt integer} and
type {\tt 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 {\tt plline}
call from C would look like:
%
\begin{verbatim}
    plline(n,x,y);}
\end{verbatim}
%
while from Fortran would look like:
%
\begin{verbatim}
	call plline(n,x,y)
\end{verbatim}
%
typically with {\tt n} declared as type {\tt integer} and {\tt x}, {\tt y}
declared as type {\tt real} (arrays in this case).  Each C language type
used in the text translates roughly as follows:
\begin{tabbing}
01234567\=
	890123456789012345678901\=\kill
%
	\>PLFLT			\>real\\
	\>PLINT			\>integer\\
	\>char *		\>character\\
	\>PLFLT *		\>real or real array\\
	\>PLFLT **		\>real array\\
	\>{\tt"}string{\tt"}	\>{\tt'}string{\tt'}\\
	\>array[0]		\>array(1)\\
\end{tabbing}
In C there are two ways to pass a variable --- by value (the default) or by
reference (pointer), whereas only the latter is used by Fortran.
Therefore when you see references in the text to {\em either} an ordinary
argument or a pointer argument (e.g.  {\tt *data}), you simply use an
ordinary Fortran variable or array name.

The PLplot library comes with a set of Fortran interface routines that
allow the exact same call syntax (usually) regardless of whether calling
from C or Fortran.  In some cases, this means the subroutine name {\em
exceeds 8 characters in length}.  Nearly every Fortran compiler on sale
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 representation to that typically used in C.  This
includes:
\begin{enumerate}
\item Variables passed by value instead of by reference.

Fortran 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 call
by reference to a call by value.  As an example, here is how the plpoin stub
routine works.  In your Fortran program you might have a call to plpoin that
looks something like
\begin{verbatim}
      call plpoin(6,x,y,9)
\end{verbatim}

where x and y are arrays with 6 elements and you want to plot symbol 9.
As strange as it seems (at least to C programmers) the constants 6 and
9 are passed by reference.   This will actually call the following C
stub routine (included in entirety)
\begin{verbatim}
#include "plstubs.h"

void 
PLPOIN(n, x, y, code)
PLINT *n, *code;
PLFLT *x, *y;
{
    c_plpoin(*n, x, y, *code);
}
\end{verbatim}
All this stub routine does is convert the number of points ({\tt *n} and the
symbol {\tt *code} to call by value (i.e.  pushes their value on the stack)
and then calls the C plpoin library routine.

\item Get mapping between Fortran 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 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 (see Appendix \ref{ap:sys} for more info).  In any
case, once the name translation is established during installation, name
translation is completely transparent to the user.

\item Translation of character string format from Fortran to C.

Fortran 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 and one written in C.  Your Fortran program calls the
Fortran 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 {\tt 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 {\tt plmtex} stubs for an
example of this. 

Note that the portion of a Fortran character string that exceeds 299
characters will not be plotted by the text routines ({\tt plmtex} and {\tt
plptex}). 

\item Multidimensional array arguments are changed from row-dominant to
column-dominant ordering through use of a temporary array.

In Fortran, 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 {\em 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.
\end{enumerate}

This all seems a little messy, but is very user friendly.  Fortran 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 programmer.

For more information on calling PLplot from Fortran, please see the 13
example Fortran programs ({\tt x01f.f} through {\tt x13f.f}) distributed
with PLplot.
