6.2.3 Functions used for building an interface

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" ,"z" or "c" which stands for double, float (real), integer, double complex 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 stack 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.

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. Character, integer, real, double and double complex type variables are respectively in the cstk, istk, sstk, stk, zstk Scilab internal stack at the adresses lk's returned by GetRhsVar or CreateVar.

Then they are returned to Scilab as lhs variables. 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;

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.

• GetMatrixptr("Aname", &m, &n, &lp);
  

  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 lp, the entries of the matrix are ordered columnwise.

• ReadString("Aname",&n,str)
  

  This function reads a string in Scilab internal stack. n is the length of the string.

The Fortran functions have the same syntax and return logical values.