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
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
|
<!DOCTYPE html>
<html>
<!-- Created by GNU Texinfo 7.1.1, https://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 10.3.0))</title>
<meta name="description" content="Calling External Code from Oct-Files (GNU Octave (version 10.3.0))">
<meta name="keywords" content="Calling External Code from Oct-Files (GNU Octave (version 10.3.0))">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta name="viewport" content="width=device-width,initial-scale=1">
<link href="index.html" rel="start" title="Top">
<link href="Concept-Index.html" rel="index" title="Concept Index">
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="Oct_002dFiles.html" rel="up" title="Oct-Files">
<link href="Allocating-Local-Memory-in-Oct_002dFiles.html" rel="next" title="Allocating Local Memory in Oct-Files">
<link href="Calling-Octave-Functions-from-Oct_002dFiles.html" rel="prev" title="Calling Octave Functions from Oct-Files">
<style type="text/css">
<!--
a.copiable-link {visibility: hidden; text-decoration: none; line-height: 0em}
div.example {margin-left: 3.2em}
span:hover a.copiable-link {visibility: visible}
-->
</style>
<link rel="stylesheet" type="text/css" href="octave.css">
</head>
<body lang="en">
<div class="subsection-level-extent" id="Calling-External-Code-from-Oct_002dFiles">
<div class="nav-panel">
<p>
Next: <a href="Allocating-Local-Memory-in-Oct_002dFiles.html" accesskey="n" rel="next">Allocating Local Memory in Oct-Files</a>, Previous: <a href="Calling-Octave-Functions-from-Oct_002dFiles.html" accesskey="p" rel="prev">Calling Octave Functions from Oct-Files</a>, Up: <a href="Oct_002dFiles.html" 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" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<h4 class="subsection" id="Calling-External-Code-from-Oct_002dFiles-1"><span>A.1.9 Calling External Code from Oct-Files<a class="copiable-link" href="#Calling-External-Code-from-Oct_002dFiles-1"> ¶</a></span></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 class="file">foo.h</samp>, then the tactic to ensure that the C++ compiler
treats these declarations as C code is
</p>
<div class="example">
<div class="group"><pre class="example-preformatted">#ifdef __cplusplus
extern "C"
{
#endif
#include "foo.h"
#ifdef __cplusplus
} /* end extern "C" */
#endif
</pre></div></div>
<p>When calling functions that are implemented in Fortran code, some peculiarities
have to be taken into account. Symbol names in Fortran are case-insensitive,
and depending on the used Fortran compiler, function names are either exported
with all lowercase or with all uppercase characters. Additionally, some
compilers append none, one or two underscores "<code class="code">_</code>" at the end of
exported function names. This is called "name-mangling".
</p>
<p>Octave supplies macros that allow writing code that automatically handles the
name-mangling for a number of different Fortran compilers. These macros are
<code class="env">F77_FUNC</code><!-- /@w --> and <code class="env">F77_FUNC_</code><!-- /@w -->. The former should be used for
Fortran functions that do not contain any underscores in their name. The
latter should be used for Fortran functions with underscores in their names.
Both macros take two arguments: The first is the Fortran function name in all
lowercase characters. The second is the same Fortran function name in all
uppercase characters.
</p>
<p>Additionally to the name-mangling, different compilers are using different
calling conventions for some types. Octave defines the following preprocessor
macros to allow writing code that can be used with different Fortran calling
conventions.
</p>
<p>Note that we don’t attempt to handle Fortran functions, we always use
subroutine wrappers for them and pass the return value as an extra argument.
</p>
<p>Use the following macros to pass character strings from C to Fortran:
</p>
<div class="example">
<div class="group"><pre class="example-preformatted"> F77_CHAR_ARG(x)
F77_CONST_CHAR_ARG(x)
F77_CXX_STRING_ARG(x)
F77_CHAR_ARG_LEN(l)
F77_CHAR_ARG_DECL
F77_CONST_CHAR_ARG_DECL
F77_CHAR_ARG_LEN_DECL
</pre></div></div>
<p>Use the following macros to write C-language functions that accept
Fortran-style character strings:
</p>
<div class="example">
<div class="group"><pre class="example-preformatted"> F77_CHAR_ARG_DEF(s, len)
F77_CONST_CHAR_ARG_DEF(s, len)
F77_CHAR_ARG_LEN_DEF(len)
F77_CHAR_ARG_USE(s)
F77_CHAR_ARG_LEN_USE(s, len)
</pre></div></div>
<p>Use the following macros for Fortran types in C++ code:
</p>
<dl class="table">
<dt><code class="code">F77_INT4</code></dt>
<dd><p>Equivalent to Fortran <code class="code">INTEGER*4</code> type
</p>
</dd>
<dt><code class="code">F77_DBLE</code></dt>
<dd><p>Equivalent to Fortran <code class="code">DOUBLE PRECISION</code> type
</p>
</dd>
<dt><code class="code">F77_REAL</code></dt>
<dd><p>Equivalent to Fortran <code class="code">REAL</code> type
</p>
</dd>
<dt><code class="code">F77_CMPLX</code></dt>
<dd><p>Equivalent to Fortran <code class="code">COMPLEX</code> type
</p>
</dd>
<dt><code class="code">F77_DBLE_CMPLX</code></dt>
<dd><p>Equivalent to Fortran <code class="code">DOUBLE COMPLEX</code> type
</p>
</dd>
<dt><code class="code">F77_LOGICAL</code></dt>
<dd><p>Equivalent to Fortran <code class="code">LOGICAL</code> type
</p>
</dd>
<dt><code class="code">F77_RET_T</code></dt>
<dd><p>Return type of a C++ function that acts like a Fortran subroutine.
</p></dd>
</dl>
<p>Use the following macros to return from C-language functions that are supposed
to act like Fortran subroutines. <code class="env">F77_NORETURN</code><!-- /@w --> is intended to be used
as the last statement of such a function that has been tagged with a
<code class="code">"noreturn"</code> attribute.
</p>
<div class="example">
<div class="group"><pre class="example-preformatted"> F77_RETURN(retval)
F77_NORETURN(retval)
</pre></div></div>
<p>The underlying Fortran code should use the <code class="code">XSTOPX</code> function to replace
the Fortran <code class="code">STOP</code> function. <code class="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 class="sc">BLAS</small> <code class="code">XERBLA</code> function, which
uses <code class="code">XSTOPX</code>.
</p>
<p>The following example shows the inclusion of a Fortran function in an oct-file,
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, FORTRANSUB)
(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.rwdata ();
octave_idx_type na = a.numel ();
OCTAVE_LOCAL_BUFFER (char, ctmp, 128);
F77_FUNC (fortransub, FORTRANSUB)
(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">
<div class="group"><pre class="example-preformatted">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></div>
</div>
<hr>
<div class="nav-panel">
<p>
Next: <a href="Allocating-Local-Memory-in-Oct_002dFiles.html">Allocating Local Memory in Oct-Files</a>, Previous: <a href="Calling-Octave-Functions-from-Oct_002dFiles.html">Calling Octave Functions from Oct-Files</a>, Up: <a href="Oct_002dFiles.html">Oct-Files</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html" title="Index" rel="index">Index</a>]</p>
</div>
</body>
</html>
|
