6.2.1 Building an interface program

Examples of interface programs are given in the directory examples/addinter-examples.

The two files template.c and template.f are skeletons of interface programs.

• The file Examplc.c is a C interface for the function foubare2c which is defined in the file src/foubare2c.c. This interface can be tested with the Scilab script Examplc.sce.
• The file Examplf.f is a Fortran interface for the function foubare2f which is defined in the file src/foubare2f.f. This interface can be tested with the Scilab script Examplc.sce.

The interface programs use a set of C or Fortran routines which should be used to build the interface program. The simplest way to learn how to build an interface program is to customize the previous skeletons files and to look at the examples provided in this directory. An interface program defines a set of Scilab functions and the calls to the corresponding numerical programs. Note that a unique interface program can be used to interface an arbitrary (but less that 99) number of functions.

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 kth 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.