<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- Created by GNU Texinfo 6.5, http://www.gnu.org/software/texinfo/ -->
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>Calling External Code from Oct-Files (GNU Octave (version 5.1.0))</title>
<meta name="description" content="Calling External Code from Oct-Files (GNU Octave (version 5.1.0))">
<meta name="keywords" content="Calling External Code from Oct-Files (GNU Octave (version 5.1.0))">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<link href="index.html#Top" rel="start" title="Top">
<link href="Concept-Index.html#Concept-Index" rel="index" title="Concept Index">
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="Oct_002dFiles.html#Oct_002dFiles" rel="up" title="Oct-Files">
<link href="Allocating-Local-Memory-in-Oct_002dFiles.html#Allocating-Local-Memory-in-Oct_002dFiles" rel="next" title="Allocating Local Memory in Oct-Files">
<link href="Calling-Octave-Functions-from-Oct_002dFiles.html#Calling-Octave-Functions-from-Oct_002dFiles" rel="prev" title="Calling Octave Functions from Oct-Files">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.indentedblock {margin-right: 0em}
blockquote.smallindentedblock {margin-right: 0em; font-size: smaller}
blockquote.smallquotation {font-size: smaller}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
div.smalldisplay {margin-left: 3.2em}
div.smallexample {margin-left: 3.2em}
div.smalllisp {margin-left: 3.2em}
kbd {font-style: oblique}
pre.display {font-family: inherit}
pre.format {font-family: inherit}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: inherit; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: inherit; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.nolinebreak {white-space: nowrap}
span.roman {font-family: initial; font-weight: normal}
span.sansserif {font-family: sans-serif; font-weight: normal}
ul.no-bullet {list-style: none}
-->
</style>
<link rel="stylesheet" type="text/css" href="octave.css">
</head>
<body lang="en">
<a name="Calling-External-Code-from-Oct_002dFiles"></a>
<div class="header">
<p>
Next: <a href="Allocating-Local-Memory-in-Oct_002dFiles.html#Allocating-Local-Memory-in-Oct_002dFiles" accesskey="n" rel="next">Allocating Local Memory in Oct-Files</a>, Previous: <a href="Calling-Octave-Functions-from-Oct_002dFiles.html#Calling-Octave-Functions-from-Oct_002dFiles" accesskey="p" rel="prev">Calling Octave Functions from Oct-Files</a>, Up: <a href="Oct_002dFiles.html#Oct_002dFiles" accesskey="u" rel="up">Oct-Files</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<a name="Calling-External-Code-from-Oct_002dFiles-1"></a>
<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 that the
declarations of the external C functions may need to be explicitly defined as C
functions to the compiler. If the declarations of the external C functions are
in the header <samp>foo.h</samp>, then the tactic to ensure that the C++ compiler
treats these declarations as C code is
</p>
<div class="example">
<pre class="example">#ifdef __cplusplus
extern "C"
{
#endif
#include "foo.h"
#ifdef __cplusplus
} /* end extern "C" */
#endif
</pre></div>
<p>Calling Fortran code, however, can pose more difficulties. This is due to
differences in the manner in which compilers treat the linking of Fortran code
with C or C++ code. Octave supplies several macros that allow consistent
behavior across a number of compilers.
</p>
<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 <small>BLAS</small> <code>XERBLA</code> function, which
uses <code>XSTOPX</code>.
</p>
<p>If the code calls <code>XSTOPX</code>, then the <code><span class="nolinebreak">F77_XFCN</span></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><span class="nolinebreak">F77_FCN</span></code><!-- /@w --> macro should be
used instead to call the Fortran code.
</p>
<p>There is no great harm in using <code><span class="nolinebreak">F77_XFCN</span></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><span class="nolinebreak">F77_FCN</span></code><!-- /@w -->
is used with code that calls <code>XSTOP</code>, Octave can generate a segmentation
fault.
</p>
<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
</p>
<div class="example">
<pre class="verbatim">#include <octave/oct.h>
#include <octave/f77-fcn.h>
extern "C"
{
F77_RET_T
F77_FUNC (fortransub, FORTSUB)
(const F77_INT&, F77_DBLE*, F77_CHAR_ARG_DECL F77_CHAR_ARG_LEN_DECL);
}
DEFUN_DLD (fortrandemo, args, , "Fortran Demo")
{
if (args.length () != 1)
print_usage ();
NDArray a = args(0).array_value ();
double *av = a.fortran_vec ();
octave_idx_type na = a.numel ();
OCTAVE_LOCAL_BUFFER (char, ctmp, 128);
F77_XFCN (fortransub, FORTSUB,
(na, av, ctmp F77_CHAR_ARG_LEN (128)));
return ovl (a, std::string (ctmp));
}
</pre></div>
<p>and the Fortran function is
</p>
<div class="example">
<pre class="verbatim"> subroutine fortransub (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 ('fortransub: 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 ('fortransub: error writing string')
endif
return
end
</pre></div>
<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. Both the Fortran and C++ files need to be compiled in order for the
example to work.
</p>
<div class="example">
<pre class="example">mkoctfile fortrandemo.cc fortransub.f
[b, s] = fortrandemo (1:3)
⇒
b = 1.00000 0.50000 0.33333
s = There are 3 values in the input vector
[b, s] = fortrandemo (0:3)
error: fortrandemo: fortransub: divide by zero
</pre></div>
<hr>
<div class="header">
<p>
Next: <a href="Allocating-Local-Memory-in-Oct_002dFiles.html#Allocating-Local-Memory-in-Oct_002dFiles" accesskey="n" rel="next">Allocating Local Memory in Oct-Files</a>, Previous: <a href="Calling-Octave-Functions-from-Oct_002dFiles.html#Calling-Octave-Functions-from-Oct_002dFiles" accesskey="p" rel="prev">Calling Octave Functions from Oct-Files</a>, Up: <a href="Oct_002dFiles.html#Oct_002dFiles" accesskey="u" rel="up">Oct-Files</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p>
</div>
</body>
</html>
