<!-- -*-  mode: nxml -*- -->
<!--
    fortran95.xml: "Fortran 95 Language" chapter

Copyright (C) 1994  Geoffrey Furnish and Maurice LeBrun
Copyright (C) 1999, 2000, 2001, 2002, 2003  Alan W. Irwin and Rafael Laboissiere
Copyright (C) 2003  Joao Cardoso

Redistribution and use in source (XML DocBook) and "compiled" forms
(HTML, PDF, PostScript, DVI, TeXinfo and so forth) with or without
modification, are permitted provided that the following conditions are
met:

1. Redistributions of source code (XML DocBook) must retain the
above copyright notice, this list of conditions and the following
disclaimer as the first lines of this file unmodified.

2. Redistributions in compiled form (transformed to other DTDs,
converted to HTML, PDF, PostScript, and other formats) must
reproduce the above copyright notice, this list of conditions and
the following disclaimer in the documentation and/or other
materials provided with the distribution.

Important: THIS DOCUMENTATION IS PROVIDED BY THE PLPLOT PROJECT "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE PLPLOT PROJECT BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS DOCUMENTATION,
EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-->

<chapter id="fortran95">
  <title>Fortran 95 Language</title>
  <para>
    As discussed in the preceding section, PLplot's integer representation is a
    PLINT and its floating point representation is a PLFLT.  To the
    Fortran 95 user, this most commonly translates to a type
    <literal>integer</literal> and
    type <literal>real</literal>, 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.
  </para>
  <para>
    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:
    <programlisting>
      plline(n,x,y);
    </programlisting>
    The argument <literal>n</literal> is the number of points that make
    up the line and the arguments <literal>x</literal> and <literal>y</literal>
    are arrays of floating-point numbers containing the x- and y-coordinates of the
    points.
  </para>
  <para>
    In C you need to specify the array dimensions explicitly, whereas in
    Fortran 95 the array dimension can be implicit, which leads to less
    mistakes. The interface to <literal>plline</literal> would ideally look
    like this:
    <programlisting>
      interface
      subroutine plline(x,y)
      real, dimension(:) :: x, y
      end subroutine plline
      end interface
    </programlisting>

  </para>
  <para>
    There is one slight complication: PLplot can be compiled with either
    single-precision reals or double-precision reals. It is <emphasis>very
    important</emphasis> to keep the variables that are passed to PLplot in
    the same precision. Fortunately, Fortran 95 provides the
    <literal>KIND</literal> mechanism for this.
  </para>
  <para>
    The actual interface to <literal>plline</literal> therefore looks like:
    <programlisting>
      interface
      subroutine plline(x,y)
      real(kind=plflt), dimension(:) :: x, y
      end subroutine plline
      end interface
    </programlisting>
    The parameter <literal>plflt</literal> is defined in the
    <literal>PLplot</literal> module and should be used consistently with
    all real variables that you pass to PLplot routines.
  </para>
  <para>
    Here is a short overview of how C data types correspond to Fortran 95
    data types:
    <informaltable frame="none" pgwide="0">
      <tgroup align="center" cols="2">
	<colspec colnum="1" align="center" colwidth="1*"/>
	<colspec colnum="2" align="center" colwidth="1*"/>
	<tbody>
	  <row>
	    <entry>PLFLT</entry><entry>real(kind=plflt)</entry>
	  </row>
	  <row>
	    <entry>PLINT</entry><entry>integer</entry>
	  </row>
	  <row>
	    <entry>char *</entry><entry>character</entry>
	  </row>
	  <row>
	    <entry>PLFLT *</entry><entry>real(kind=plflt) or real(kind=plflt), dimension(:)</entry>
	  </row>
	  <row>
	    <entry>PLFLT **</entry><entry>real(kind=plflt), dimension(:,:)</entry>
	  </row>
	  <row>
	    <entry><literal>"string"</literal></entry><entry><literal>'string'</literal></entry>
	  </row>
	  <row>
	    <entry>array[0]</entry><entry>array(1)</entry>
	  </row>
	</tbody>
      </tgroup>
    </informaltable>
    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 95.
    Therefore when you see references in the text to <emphasis>either</emphasis> an ordinary
    argument or a pointer argument (e.g.  <literal>*data</literal>), you simply use an
    ordinary Fortran 95 variable or array name (the interfacing
    routines take care of any transformations that may be necessary).
  </para>
  <para>
    The PLplot library comes with a set of Fortran 95 interface routines that
    allow the same call semantics (usually) regardless of whether calling
    from C or Fortran 95.  In some cases, the Fortran 95 interface uses
    implicit array dimensions, so that it has fewer arguments than the C
    counterpart.
  </para>
  <para>
    These <quote>stub</quote> routines handle transforming the data
    from the normal Fortran 95 representation to that typically used in C.  This
    includes:
    <itemizedlist>
      <listitem><para>
	Variables passed by value instead of by reference.
      </para>
      <para>
	Fortran 95 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 95 call
	by reference to a call by value.  As an example, here is how the plpoin stub
	routine works.  In your Fortran 95 program you might have a call to plpoin that
	looks something like
	<programlisting>
	  real(kind=pllft), dimension(6) :: x, y
	  x = ...
	  y = ...
	  call plpoin(x,y,9)
	</programlisting>
	where x and y are arrays with 6 elements and you want to plot symbol 9.
	The routine <literal>plpoin</literal> calls the underlying routine
	<literal>plpoinf95</literal>:
	<programlisting>
	  subroutine plpoin( x, y, code )
	  integer                        :: code
	  real(kind=plflt), dimension(:) :: x, y

	  call plpoinf95( size(x), x, y, code )
	  end subroutine plpoin
	</programlisting>
	This takes care of the size of the arrays - it is not possible to
	transfer this information to C in an implicit way.
      </para>
      <para>
	The routine plpoinf95 is implemented in C to take care of the question
	pass by value or pass by reference:

	<footnote>
	  <para>
	    <literal>PLPOIN</literal> is a macro that get translated into the correct name
	    for this routine - various Fortran compilers use different conventions, such as
	    adding an underscore or translating the name into capitals.
         </para>
	</footnote>

	<programlisting>
	  #include "plplot/plstubs.h"

	  void
	  PLPOIN(n, x, y, code)
	  PLINT *n, *code;
	  PLFLT *x, *y;
	  {
	  c_plpoin(*n, x, y, *code);
	  }
	</programlisting>
	All this stub routine does is convert the number of points
	(<literal>*n</literal> and the
	symbol <literal>*code</literal> to call by value (i.e.  pushes their value on the stack)
	and then calls the C plpoin library routine.
      </para></listitem>
      <listitem><para>
	Get mapping between Fortran 95 and C namespace right (system dependent).
      </para>
      <para>
	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 95 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.
	During the build process, the properties of the build environment are
	detected and the correct compiler options are used.
      </para>
      <para>
	Once the name translation is established during installation, name
	translation is completely transparent to the user.
      </para></listitem>
      <listitem><para>
	Translation of character string format from Fortran 95 to C.
      </para>
      <para>
	Fortran 95 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 95 and one written in C.  Your Fortran 95 program calls the
	Fortran 95 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 <literal>long</literal>) 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 <literal>plmtex</literal> stubs for an
	example of this.
      </para>
      <para>
	Note that the portion of a Fortran 95 character string that exceeds 299
	characters will not be plotted by the text routines (<literal>plmtex</literal>
	and <literal>plptex</literal>).
      </para></listitem>
      <listitem><para>
	Multidimensional array arguments are changed from row-dominant to
	column-dominant ordering through use of a temporary array.
      </para>
      <para>
	In Fortran 95, arrays are always stored so that the first index increases most
	rapidly as one steps through memory.  This is called
	<quote>row-dominant</quote>
	storage.  In C, on the other hand, the first index increases
	<emphasis>least</emphasis>
	rapidly, i.e. <quote>column-dominant</quote> 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.
      </para></listitem>
    </itemizedlist>
  </para>
  <para>
    This all seems a little messy, but is very user friendly.  Fortran 95 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 95 programmer.
  </para>
  <para>
    For more information on calling PLplot from Fortran 95, please see the
    example Fortran 95 programs (<filename>/examples/f95/x??f.f</filename>)
    distributed
    with PLplot.
  </para>
</chapter>
