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

Online Help

All Products    Maple    MapleSim


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

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

external types

 

Calling Sequence

Parameters

Description

Examples

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.

last_letterdefine_external'last_letter',s::string,RETURN::char,LIB=mylib.dll:

last_letterwhatever

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.

times2define_external'times2','x'::REFinteger[4],LIB=libmy.so:

n4:

times2'n':

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.

n5:

times2'n':

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<num_elems; ++i )

         r += a[i];

         return( r );

     }

}

In Maple this can be used as follows.

sum_elemsdefine_external&apos;sum_elems&apos;&comma;JAVA&comma;CLASSPATH&equals;currentdir&comma;RETURN::float&lsqb;8&rsqb;&comma;&apos;a&apos;::ARRAYfloat&lsqb;8&rsqb;&comma;&apos;n&apos;::integer&lsqb;4&rsqb;&comma;LIB&equals;jexttest&colon;

AVector5&comma;i&rarr;i&comma;datatype&equals;float&lsqb;8&rsqb;&colon;

sum_elemsA&comma;5

15

(4)

See Also

COMPILE_OPTIONS

CustomWrapper

define_external

SharedLibrary

WRAPPER

 


Download Help Document

Was this information helpful?



Please add your Comment (Optional)
E-mail Address (Optional)
What is ? This question helps us to combat spam