<html lang="en">
<head>
<title>Calling External Code from Oct-Files - GNU Octave</title>
<meta http-equiv="Content-Type" content="text/html">
<meta name="description" content="GNU Octave">
<meta name="generator" content="makeinfo 4.13">
<link title="Top" rel="start" href="index.html#Top">
<link rel="up" href="Oct_002dFiles.html#Oct_002dFiles" title="Oct-Files">
<link rel="prev" href="Calling-Octave-Functions-from-Oct_002dFiles.html#Calling-Octave-Functions-from-Oct_002dFiles" title="Calling Octave Functions from Oct-Files">
<link rel="next" href="Allocating-Local-Memory-in-Oct_002dFiles.html#Allocating-Local-Memory-in-Oct_002dFiles" title="Allocating Local Memory in Oct-Files">
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
<meta http-equiv="Content-Style-Type" content="text/css">
<style type="text/css"><!--
pre.display { font-family:inherit }
pre.format { font-family:inherit }
pre.smalldisplay { font-family:inherit; font-size:smaller }
pre.smallformat { font-family:inherit; font-size:smaller }
pre.smallexample { font-size:smaller }
pre.smalllisp { font-size:smaller }
span.sc { font-variant:small-caps }
span.roman { font-family:serif; font-weight:normal; }
span.sansserif { font-family:sans-serif; font-weight:normal; }
--></style>
</head>
<body>
<div class="node">
<a name="Calling-External-Code-from-Oct-Files"></a>
<a name="Calling-External-Code-from-Oct_002dFiles"></a>
<p>
Next: <a rel="next" accesskey="n" href="Allocating-Local-Memory-in-Oct_002dFiles.html#Allocating-Local-Memory-in-Oct_002dFiles">Allocating Local Memory in Oct-Files</a>,
Previous: <a rel="previous" accesskey="p" href="Calling-Octave-Functions-from-Oct_002dFiles.html#Calling-Octave-Functions-from-Oct_002dFiles">Calling Octave Functions from Oct-Files</a>,
Up: <a rel="up" accesskey="u" href="Oct_002dFiles.html#Oct_002dFiles">Oct-Files</a>
<hr>
</div>
<h4 class="subsection">A.1.9 Calling External Code from Oct-Files</h4>
<p>Linking external C code to Octave is relatively simple, as the C
functions can easily be called directly from C++. One possible issue is
the declarations of the external C functions might need to be explicitly
defined as C functions to the compiler. If the declarations of the
external C functions are in the header <code>foo.h</code>, then the manner in
which to ensure that the C++ compiler treats these declarations as C
code is
<pre class="example"> #ifdef __cplusplus
extern "C"
{
#endif
#include "foo.h"
#ifdef __cplusplus
} /* end extern "C" */
#endif
</pre>
<p>Calling Fortran code however can pose some difficulties. This is due to
differences in the manner in compilers treat the linking of Fortran code
with C or C++ code. Octave supplies a number of macros that allow
consistent behavior across a number of compilers.
<p>The underlying Fortran code should use the <code>XSTOPX</code> function to
replace the Fortran <code>STOP</code> function. <code>XSTOPX</code> uses the Octave
exception handler to treat failing cases in the Fortran code
explicitly. Note that Octave supplies its own replacement <span class="sc">blas</span>
<code>XERBLA</code> function, which uses <code>XSTOPX</code>.
<p>If the underlying code calls <code>XSTOPX</code>, then the <code>F77_XFCN</code><!-- /@w -->
macro should be used to call the underlying Fortran function. The Fortran
exception state can then be checked with the global variable
<code>f77_exception_encountered</code>. If <code>XSTOPX</code> will not be called,
then the <code>F77_FCN</code><!-- /@w --> macro should be used instead to call the Fortran
code.
<p>There is no harm in using <code>F77_XFCN</code><!-- /@w --> in all cases, except that for
Fortran code that is short running and executes a large number of times,
there is potentially an overhead in doing so. However, if <code>F77_FCN</code><!-- /@w -->
is used with code that calls <code>XSTOP</code>, Octave can generate a
segmentation fault.
<p>An example of the inclusion of a Fortran function in an oct-file is
given in the following example, where the C++ wrapper is
<pre class="example"><pre class="verbatim"> #include <octave/oct.h>
#include <octave/f77-fcn.h>
extern "C"
{
F77_RET_T
F77_FUNC (fortsub, FORTSUB)
(const int&, double*, F77_CHAR_ARG_DECL
F77_CHAR_ARG_LEN_DECL);
}
DEFUN_DLD (fortdemo , args , , "Fortran Demo.")
{
octave_value_list retval;
int nargin = args.length();
if (nargin != 1)
print_usage ();
else
{
NDArray a = args(0).array_value ();
if (! error_state)
{
double *av = a.fortran_vec ();
octave_idx_type na = a.nelem ();
OCTAVE_LOCAL_BUFFER (char, ctmp, 128);
F77_XFCN (fortsub, FORTSUB, (na, av, ctmp
F77_CHAR_ARG_LEN (128)));
retval(1) = std::string (ctmp);
retval(0) = a;
}
}
return retval;
}
</pre>
</pre>
<p class="noindent">and the Fortran function is
<pre class="example"><pre class="verbatim"> subroutine fortsub (n, a, s)
implicit none
character*(*) s
real*8 a(*)
integer*4 i, n, ioerr
do i = 1, n
if (a(i) .eq. 0d0) then
call xstopx ('fortsub: divide by zero')
else
a(i) = 1d0 / a(i)
endif
enddo
write (unit = s, fmt = '(a,i3,a,a)', iostat = ioerr)
$ 'There are ', n,
$ ' values in the input vector', char(0)
if (ioerr .ne. 0) then
call xstopx ('fortsub: error writing string')
endif
return
end
</pre>
</pre>
<p>This example demonstrates most of the features needed to link to an
external Fortran function, including passing arrays and strings, as well
as exception handling. An example of the behavior of this function is
<pre class="example"> [b, s] = fortdemo (1:3)
⇒
b = 1.00000 0.50000 0.33333
s = There are 3 values in the input vector
[b, s] = fortdemo(0:3)
error: fortsub:divide by zero
error: exception encountered in Fortran subroutine fortsub_
error: fortdemo: error in Fortran
</pre>
</body></html>
