define_external(..., argN::typeN, ...) - Maple Programming Help

Home : Support : Online Help : Programming : Calling External Routines : define_external/types

define_external(..., argN::typeN, ...)

external types

 Calling Sequence define_external(..., argN::typeN, ...)

Parameters

 argN - the Nth argument name typeN - the Nth type description

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 short integer[4] int, long INTEGER int integer[8] long long, __int64, long INTEGER*8 long float[4] float REAL float float[8] double DOUBLE PRECISION double char[1] char CHARACTER char boolean[1] char LOGICAL*1 boolean boolean[4] int LOGICAL int

 • The C type long is usually 4 bytes on 32-bit machines (most Windows systems), 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.

 MAPLE C FORTRAN JAVA 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 NA REF(typeN) typeN *r NA NA

 • 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] boolean 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

Examples

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.

 > $\mathrm{last_letter}≔\mathrm{define_external}\left('\mathrm{last_letter}',s::\mathrm{string},\mathrm{RETURN}::\mathrm{char},\mathrm{LIB}="mylib.dll"\right):$
 > $\mathrm{last_letter}\left("whatever"\right)$
 ${"r"}$ (1)

The following C function doubles the input.

 void times2( int *i ) { if( !i ) return; *i *= 2; }

In Maple this can be used as follows.

 > $\mathrm{times2}≔\mathrm{define_external}\left('\mathrm{times2}','x'::\left(\mathrm{REF}\left(\mathrm{integer}[4]\right)\right),\mathrm{LIB}="libmy.so"\right):$
 > $n≔4:$
 > $\mathrm{times2}\left('n'\right):$
 > $n$
 ${8}$ (2)

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:$
 > $\mathrm{times2}\left('n'\right):$
 > $n$
 ${5}$ (3)

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

In Maple this can be used as follows.

 > $\mathrm{sum_elems}≔\mathrm{define_external}\left('\mathrm{sum_elems}',\mathrm{JAVA},\mathrm{CLASSPATH}=\mathrm{currentdir}\left(\right),\mathrm{RETURN}::\left(\mathrm{float}[8]\right),'a'::\left(\mathrm{ARRAY}\left(\mathrm{float}[8]\right)\right),'n'::\left(\mathrm{integer}[4]\right),\mathrm{LIB}="jexttest"\right):$
 > $A≔\mathrm{Vector}\left(5,i→i,\mathrm{datatype}=\mathrm{float}[8]\right):$
 > $\mathrm{sum_elems}\left(A,5\right)$
 ${15}$ (4)