The two files template.c and template.f are skeletons of interface programs.
The functions used to build an interface are Fortran subroutines when the interface is written in Fortran and are coded as C macros (defined in stack-c.h ) when the interface is coded in C. The main functions are as follows:
CheckRhs(minrhs, maxrhs) CheckLhs(minlhs, maxlhs)Function
CheckRhs
is used to check that the Scilab function is called
with minrhs <= Rhs <= maxrhs
.
Function CheckLhs
is used to check that the expected return
values are in the range
minlhs <= Lhs <= maxlhs
. (Usually one has minlhs=1
since a Scilab function can be always be called with less lhs
arguments than expected).
GetRhsVar(k,ct,mk,nk,lk)Note that
k
(integer) and ct
(string) are inputs and
mk,nk
and lk
(integers) are outputs of GetRhsVar
.
This function defines the type (ct
) of input variable numbered
k
, i.e. the k
th input variable in the calling sequence of the
Scilab function. The pair mk,nk
gives the dimensions (number of rows
and columns) of variable numbered k
if it is a matrix.
If it is a chain mk*nk
is its length. lk
is the adress
of variable numbered k
in Scilab internal stack.
The type of variable number k
, ct
, should be set
to 'd', 'r', 'i' or 'c' which stands for double, float
(real), integer
or character respectively. The interface should call function
GetRhsVar
for each of the rhs variables of the Scilab function
with k=1, k=2,..., k=Rhs.
Note that if the Scilab argument doesn't match the requested type then
Scilab enters an error function and returns from the interface function.
CreateVar(k,ct,mk,nk,lk)Here
k,ct,mk,nk
are inputs of CreateVar
and lk
is an
output of CreateVar
. The parameters are as above. Variable numbered
k
is created in Scilab internal satck at adress lk. When
calling CreateVar, k must be greater than Rhs i.e.
k=Rhs+1, k=Rhs+2, ....
If due to memory lack, the argument can't be created, then a Scilab error
function is called and the interface function returns.
CreateVarFromPtr(k,ct,mk,nk,lk)Here
k,ct,mk,nk,lk
are all inputs of CreateVarFromPtr
and
lk
is pointer created by a call to a C function. This function is used
when a C object was created inside the interfaced function and a Scilab
object is to be created using a pointer to this C object
(see function intfce2c
in file examples/addinter-examples/Testc.c). The function FreePtr should be used to free the pointer.
Once the variables have been processed by GetRhsVar or created by CreateVar, they are given values by calling one or several numerical routine. The call to the numerical routine is done in such a way that each argument of the routine points to the corresponding Scilab variable (see example below). Character, integer, real, double type variables are in the cstk (resp. istk, sstk, stk) Scilab internal stack at the adresses lk's returned by GetRhsVar or CreateVar.
Then they are returned to Scilab as lhs variables (this is done by function PutLhsVar). The interface should define how the lhs (output) variables are numbered. This is done by the global variable LhsVar. For instance
LhsVar(1) = 5; LhsVar(2) = 3; LhsVar(3) = 1; LhsVar(4) = 2; PutLhsVar();means that the Scilab function has at most 4 output parameters which are variables numbered
k= 5, k=3, k=1, k=2
respectively.
The functions sciprint(amessage)
and Error(k)
are used
for managing messages and errors.
Other useful functions which can be used are the following.
ReadMatrix(aname,m,n,w)This function reads a matrix in Scilab internal stack.
aname
is
a character string, name of a Scilab matrix. Outputs are integers
m,n
and w
, the entries of the matrix ordered columnwise.
w is a copy of the Scilab variable called aname.
ReadString(aname,n,w)This function reads a string in Scilab internal stack.
n
is the
length of the string.
GetMatrixptr(aname,m,n,l)This function returns the dimensions
m, n
and the address
l
of Scilab variable aname
.
The Fortran functions have the same syntax and return logical values.