define_external(..., argN::typeN, ...)
external types
Calling Sequence
Parameters
Description
Examples
argN
-
the Nth argument name
typeN
the Nth type description
Maple uses its own notation to describe external types. This provides a generic well-defined interface for calling compiled code in any language.
The parameters arg1 through argN describe the arguments of the function to be called. These should be specified in the order they appear in the documentation or source code for the external function.
The return value is also described by using a type descriptor, with the name RETURN as the argument identifier.
The data descriptors used to represent scalar formats usually contain a type name and size. The size represents the number of bytes needed to represent the given hardware type. The basic scalar types and their equivalents in C, Fortran, and Java are as follows.
MAPLE
C
FORTRAN
JAVA
integer[1]
char
BYTE
byte
integer[2]
short
INTEGER*2
integer[4]
int, long
INTEGER
int
integer[8]
long long, __int64, long
INTEGER*8
long
float[4]
float
REAL
float[8]
double
DOUBLE PRECISION
char[1]
CHARACTER
boolean[1]
LOGICAL*1
boolean
boolean[4]
LOGICAL
The C type long is usually 4 bytes on 32-bit machines, and 8 bytes on 64-bit machines.
In addition to the basic types listed above, Maple also recognizes some compound types that can be derived from these basic types. The following types are recognized by define_external.
ARRAY(datatype=typeN, ...)
type *A
type A( * )
type[] A
string[r]
char s[r]
CHARACTER*r
string
complex[4]
struct{ float r, i; }
COMPLEX
NA
complex[8]
struct{ double r, i; }
COMPLEX*8
REF(typeN)
typeN *r
Options to ARRAY are the same as those that can be passed to the Array constructor. The only significant difference is that indexing functions must be specified with indfn=, and are not allowed unless using custom wrapper external calling. The following options override any defaults normally assumed by the Array constructor.
datatype=...
Only the hardware datatypes accepted by the rtable
command are allowed. This field is required,
but the equation form of entry is not necessary.
order=...
Defaults to Fortran_order when calling a Fortran
library and C_order when calling a C or Java library.
storage=...
Defaults to full rectangular storage.
subtype=...
Optional type restriction, limiting the given rtable
to an Array, Matrix, Vector[row], or Vector[column]
indfn=(..., ...)
Specifies the rtable_indexfcn.
Other compound types including structures, unions, and procedures can be recognized when generating wrapper libraries.
The following table describes the external types and the Maple types that can be automatically converted. The first listed Maple type is the one to which a result of the corresponding external type is converted.
External Type
Allowed Maple Type(s)
boolean[n]
integer[n]
integer
float[n]
float, rational, integer, numeric
complex[n]
complex, numeric, float, rational, integer
char[n]
one-character string
string[n]
string, symbol, 0
ARRAY()
Array, Vector, Matrix
STRUCT()
list, table
UNION
table
PROC
procedure
The following C function returns the last letter of a string.
char last_letter( char *s )
{
return( s[strlen(s)-1] );
}
In Maple, this can be used as follows.
last_letter≔define_external⁡last_letter,s::string,RETURN::char,LIB=mylib.dll:
last_letter⁡whatever
r
The following C function doubles the input.
void times2( int *i )
if( !i ) return;
*i *= 2;
In Maple this can be used as follows.
times2≔define_external⁡times2,x::REF⁡integer4,LIB=libmy.so:
n≔4:
times2⁡n:
n
8
The uneval quotes are needed to prevent evaluation of the name, 'n' so the external function can get the name, rather than its assigned value. Without the quotes the value is still passed, but the variable 'n' is not updated.
n≔5:
5
The following Java function adds up all the elements of a Matrix.
public class jexttest
public static double sum_elems( double[] a, int num_elems )
int i;
double r = 0.0;
for( i=0; i<num_elems; ++i )
r += a[i];
return( r );
sum_elems≔define_external⁡sum_elems,JAVA,CLASSPATH=currentdir⁡,RETURN::float8,a::ARRAY⁡float8,n::integer4,LIB=jexttest:
A≔Vector⁡5,i↦i,datatype=float8:
sum_elems⁡A,5
15
See Also
COMPILE_OPTIONS
CustomWrapper
define_external
SharedLibrary
WRAPPER
Download Help Document