1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- Created by GNU Texinfo 6.1, http://www.gnu.org/software/texinfo/ -->
<head>
<title>GNU Octave: Calling External Code from Oct-Files</title>
<meta name="description" content="GNU Octave: Calling External Code from Oct-Files">
<meta name="keywords" content="GNU Octave: Calling External Code from Oct-Files">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<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>
</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 a number of 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 int&, double*, F77_CHAR_ARG_DECL F77_CHAR_ARG_LEN_DECL);
}
DEFUN_DLD (fortrandemo, 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.numel ();
OCTAVE_LOCAL_BUFFER (char, ctmp, 128);
F77_XFCN (fortransub, FORTSUB,
(na, av, ctmp F77_CHAR_ARG_LEN (128)));
retval(1) = std::string (ctmp);
retval(0) = a;
}
}
return retval;
}
</pre><pre class="example">
</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><pre class="example">
</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>
|