% Copyright INRIA

%\documentstyle[11pt]{article}
%\textwidth=6in
%\textheight=8.5in 
%\oddsidemargin=.30in%.25in
%\evensidemargin=.30in%.25in
%\topmargin=-.25in
%\parskip.3cm
%\begin{document}

\chapter{Interfacing C or Fortran programs}

Scilab can be easily interfaced with Fortran or C programs. 
This is useful to have faster code or to use specific numerical
code for, e.g., the simulation or optimization of
user defined systems, or specific Lapack or {\tt netlib} modules. 
In fact, interfacing numerical code appears necessary in most
nontrivial applications. For
interfacing C or Fortran programs, it is of course necessary to link
these programs with Scilab. This can be done by a dynamic
(incremental) link or by creating a new executable code for Scilab.
For executing a C or Fortran program linked with Scilab, its
input parameters must be given specific values transferred from Scilab
and its output
parameters must be transformed into Scilab variables.
It is also possible that a linked program is automatically executed
by a high-level primitive: for instance Scilab {\tt ode} function
can integrate the differential equation $\dot{x} = f(t,x)$ with a
rhs function $f$ defined as a C or Fortran program which is
dynamically linked to Scilab (see \ref{refexternals}).


\bigskip
\index{Fortran}
\index{interfacing fortran}
\index{C}


The simplest way to call external programs is to use the  
{\tt link}\index{link@{\tt link}} primitive
(which dynamically links the user's program with Scilab)
and then to interactively call
the linked routine by {\tt fort}\index{fort@{\tt fort}} primitive
which transmits Scilab variables (matrices or strings) to the linked program
and transforms back the output parameters into Scilab variables. 
Note that ode/dae solvers and non linear optimization primitives
can be directly used with C or Fortran user-defined programs
dynamically linked(see \ref{dynamiclink}). . 

An other way to add C or Fortran code to Scilab is by 
building an interface program. The interface program can be written by
the user following the examples given in the {\tt routines/examples}
directory. This interface program is dynamically linked to Scilab
by the {\tt addinter} command.

The interface program can also be generated by {\tt
intersci}. {\tt Intersci} builds the interface
program from a {\tt .desc} file which describes both the C or 
Fortran program(s) to be used and the name and parameters of
the corresponding Scilab function(s). 

Finally  it is possible to add a permanent new primitive to Scilab
by building an interface program as above and making a new executable
code for Scilab. This is done by updating the {\tt fundef}
file. In this case, the interface program
made by {\tt intersci} should be given a specific name (e.g. 
the default name {\tt matus2}) and a number. The file 
{\tt default/fundef} should also be updated as done by {\tt intersci}.
A new executable code is generated by typing ``make all''
in the main Scilab directory.

\section{Using dynamic link}
Several simple examples of dynamic link are  given in the directory
{\tt examples/link-examples}. In this section, we briefly describe 
how to call a dynamically linked program. 
\subsection{Dynamic link}
\label{dynamiclink}
The command {\tt link('path/pgm.o','pgm',flag)}
links the compiled program {\tt pgm} to Scilab.
Here {\tt pgm.o} is an object file located in the {\tt path}
directory and {\tt pgm} is an entry point (program name) in the file {\tt pgm.o}
(An object file can have several entry points: to link them, use a vector of
character strings such as \verb!['pgm1','pgm2']!).

{\tt flag} should be set to {\tt 'C'} for a C-coded program
and to {\tt 'F'} for a Fortran subroutine. ({\tt 'F'} is
the default flag and can be omitted).

If the link operation is OK, scilab returns an integer {\tt n} associated
with this linked program. To undo the link enter {\tt ulink(n)}.

The command \verb!c_link('pgm')! returns true if {\tt pgm} is
currently linked to Scilab and false if not.

\noindent
Here is a example, with the Fortran BLAS {\tt daxpy} subroutine 
used in Scilab:
\begin{verbatim}

-->n=link(SCI+'/routines/calelm/daxpy.o','daxpy')
linking files /usr/local/lib/scilab-2.4/routines/calelm/daxpy.o
to create a shared executable.
Linking daxpy (in fact daxpy_)
Link done
 n  =
 
    0.  
 
-->c_link('daxpy')
 ans  =
 
  T  

-->ulink(n)
 
-->c_link('daxpy')
 ans  =
 
  F  
\end{verbatim}

For more details, enter {\tt help link}.

\subsection{Calling a dynamically linked program}

The {\tt fort} function can be used to call a dynamically linked
program. Consider for example the {\tt daxpy} Fortran routine. It performs 
the simple vector operation {\tt y=y+a*x} or, to be more specific,
{\tt y(1)=y(1)+a*x(1), y(1+incy)=y(1+incy)+a*x(1+incx),...
y(1+n*incy)=y(1+n*incy)+a*x(1+n*incx)} 
where {\tt y} and {\tt x} are two real vectors.
The calling sequence for {\tt daxpy} is as follows:
\begin{verbatim}
      subroutine daxpy(n,a,x,incx,y,incy)
\end{verbatim}
To call {\tt daxpy} from Scilab we must use a syntax as follows: 
\begin{verbatim}
[y1,y2,y3,...]=fort('daxpy', inputs description, 'out', outputs description)
\end{verbatim}
\noindent
Here {\tt inputs description} is a set of parameters
 
{\tt x1,p1,t1}, {\tt x2,p2,t2}, {\tt x3,p3,t3} ... 

\noindent
where {\tt xi} is the Scilab variable (real vector or matrix) sent to 
{\tt daxpy},
{\tt pi} is the position number of this variable in the calling
sequence of {\tt daxpy} and {\tt ti} is the type of {\tt xi} in {\tt daxpy}
({\tt t='i'  t='r'  t='d'} stands for integer, real or double).

\noindent
{\tt outputs description} is a set of parameters
 
{\tt [r1,c1],p1,t1}, {\tt [r2,c2],p2,t2}, {\tt [r3,c3],p3,t3},..

\noindent
which describes each output variable. {\tt [ri,ci]} is the
2 x 1 integer vector giving the number of rows and columns of the
ith output variable {\tt yi}. {\tt pi} and {\tt ti} are as for
input variables (they can be omitted if a variable is both input and
output). 

We see that the arguments of {\tt fort}  divided into four groups.
The first argument {\tt 'daxpy'} is the name of the called subroutine.
The argument {\tt 'out'} divides the remaining arguments into two 
groups.  The group of arguments between {\tt 'daxpy'} and {\tt 'out'}
is the list of input arguments, their positions in the call to {\tt daxpy},
and their data type.  The group of arguments to the right of {\tt 'out'}
are the dimensions of the output variables, their positions in the call
to {\tt daxpy}, and their data type.
The possible data types are real, integer, and double precision which
are indicated, respectively, by the strings {\tt 'r'}, {\tt 'i'}, and
{\tt 'd'}.  
Here we calculate {\tt y=y+a*x} by a call to {\tt daxpy} (assuming
that the {\tt link} command has been done).
We have six input variables 
{\tt x1=n, x2=a, x3=x, x4=incx, x5=y, x6=incy}.
Variables {\tt x1, x4} and {\tt x6} are integers and variables
{\tt x2, x3, x5} are double. There is one output variable {\tt y1=y}
at position {\tt p1=5}. To simplify, we assume here that {\tt x} and
{\tt y} have the same length and we take {\tt incx=incy=1}.
\begin{verbatim}
-->a=3;
 
-->x=[1,2,3,4];
 
-->y=[1,1,1,1];
 
-->incx=1;incy=1;

-->n=size(x,'*');

-->y=fort('daxpy',...
        n,1,'i',...
        a,2,'d',...
        x,3,'d',...
        incx,4,'i',...
        y,5,'d',...
        incy,6,'i',...
'out',...
        [1,n],5,'d');

 y  =
 
!   4.    7.    10.    13. !

\end{verbatim}
(Since {\tt y} is both input and output parameter, we could also use
the simplified syntax 
{\tt fort(...,'out',5)} instead of {\tt fort(...,'out'[1,n],5,'d')}). 

The same example with the C function {\tt daxpy} (from CBLAS):
\begin{verbatim}
int daxpy(int *n, double *da, double *dx, int *incx, double *dy, int *incy)
...
\end{verbatim}

\begin{verbatim}
-->link('daxpy.o','daxpy','C')
linking files daxpy.o  to create a shared executable
Linking daxpy (in fact daxpy)
Link done
 ans  =
 
    1.  

-->y=fort('daxpy',...
        n,1,'i',...
        a,2,'d',...
        x,3,'d',...
        incx,4,'i',...
        y,5,'d',...
        incy,6,'i',...
'out',...
        [1,n],5,'d');
 
-->y
 y  =
 
!   4.    7.    10.    13. !
\end{verbatim}

The routines which are linked to Scilab can also access internal 
Scilab variables: see the examples in given in the {\tt examples/links}
directory.

\section{Interface programs}

\subsection{Building an interface program}
Examples of interface programs are given in the directory 
{\tt examples/addinter-examples}. 

\noindent
The two files {\tt template.c} and {\tt template.f} are skeletons of 
interface programs.
\begin{itemize}
\item The file {\tt Examplc.c} is a C interface for the function {\tt foubare2c} 
which is defined in the file {\tt src/foubare2c.c}. This interface can
be tested with the Scilab script {\tt Examplc.sce}.
\item The file {\tt Examplf.f} is a Fortran interface for the function
{\tt foubare2f} which is defined in the file {\tt src/foubare2f.f}. 
This interface can be tested with the Scilab script {\tt Examplc.sce}.
\end{itemize}
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.


\noindent
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 {\tt  stack-c.h} ) 
when the interface is coded in C. The main functions are as follows:

\begin{itemize}
\item{
\begin{verbatim}
CheckRhs(minrhs, maxrhs)
CheckLhs(minlhs, maxlhs)
\end{verbatim}
Function \verb!CheckRhs! is used to check that the Scilab function is called
with \\
{\verb! minrhs <= Rhs <= maxrhs!}. 
Function \verb!CheckLhs! is used to check that the expected return
values are in the range 
{\verb! minlhs <= Lhs <= maxlhs!}. (Usually one has {\tt minlhs=1}
since a Scilab function can be always be called with less lhs
arguments than expected).
}
\item{
\begin{verbatim}
GetRhsVar(k,ct,mk,nk,lk)
\end{verbatim}
Note that \verb!k! (integer) and \verb!ct! (string) are inputs and 
\verb!mk,nk! and \verb!lk! (integers) are outputs of \verb!GetRhsVar!.
This function defines the type (\verb!ct!) of input variable numbered
\verb!k!, i.e. the \verb!k!th input variable in the calling sequence of the 
Scilab function. The pair \verb!mk,nk! gives the dimensions (number of rows
and columns)  of variable numbered \verb!k! if it is a matrix. 
If it is a chain \verb!mk*nk! is its length. \verb!lk! is the adress
of variable numbered \verb!k! in Scilab internal stack.
The type of variable number \verb!k!, \verb!ct!, should be set 
to {\tt 'd', 'r', 'i'} or {\tt 'c'} which stands for double, float
(real), integer
or character respectively. The interface should call function
\verb!GetRhsVar! for each of the rhs variables of the Scilab function
with {\tt 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.
}
\item{
\begin{verbatim}
CreateVar(k,ct,mk,nk,lk)
\end{verbatim}
Here \verb!k,ct,mk,nk! are inputs of \verb!CreateVar! and \verb!lk! is an
output of \verb!CreateVar!. The parameters are as above. Variable numbered
\verb!k! is created in Scilab internal satck at adress {\tt lk}. When
calling {\tt CreateVar}, {\tt k} must be greater than {\tt Rhs} i.e.
{\tt 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.
}
\item{
\begin{verbatim}
CreateVarFromPtr(k,ct,mk,nk,lk)
\end{verbatim}
Here \verb!k,ct,mk,nk,lk! are all inputs of \verb!CreateVarFromPtr! and
\verb!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 {\tt intfce2c} 
in file { \tt examples/addinter-examples/Testc.c}). The function {\tt
FreePtr} should be used to free the pointer.
}
\end{itemize}

Once the  variables have been processed by {\tt GetRhsVar} or created
by {\tt 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 {\tt cstk} (resp. {\tt istk, sstk, stk}) Scilab internal stack
at the adresses {\tt lk}'s returned by {\tt GetRhsVar} or {\tt CreateVar}. 

Then they are returned to Scilab as lhs variables
(this is done by function {\tt PutLhsVar}).
The interface should define how the lhs (output) variables are
numbered. This is done by the global variable {\tt LhsVar}.
For instance
\begin{verbatim}
  LhsVar(1) = 5;
  LhsVar(2) = 3;
  LhsVar(3) = 1;
  LhsVar(4) = 2;
  PutLhsVar();
\end{verbatim}
means that the Scilab function has at most 4 output parameters
which are variables numbered \verb!k= 5, k=3, k=1, k=2! respectively.

The functions \verb!sciprint(amessage)! and \verb!Error(k)! are used
for managing messages and errors.

Other useful functions which can be used are the following.
\begin{itemize}
\item{
\begin{verbatim}
ReadMatrix(aname,m,n,w)
\end{verbatim}
This function reads a matrix in Scilab internal stack. \verb!aname! is
a character string, name of a Scilab matrix. Outputs are integers
\verb!m,n! and \verb!w!, the entries of the matrix ordered {\em columnwise}.
{\tt w} is a copy of the Scilab variable called {\tt aname}}.
\item{
\begin{verbatim}
ReadString(aname,n,w)
\end{verbatim}
This function reads a string in Scilab internal stack. \verb!n! is the
length of the string.
}
\item{
\begin{verbatim}
GetMatrixptr(aname,m,n,l)
\end{verbatim}
This function returns the dimensions \verb!m, n! and the address
\verb!l! of Scilab variable \verb!aname!.
}
\end{itemize}


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

\subsection{Example}

The following interface is taken from the examples in the 
{\tt examples/addinter-examples} directory.
The function to be interfaced has the following calling sequence:

\begin{verbatim}
int foubare2c (char *ch, int *a, int *ia, float *b, int *ib, 
               double *c, int *mc, int *nc, double *d, double *w, 
               int *err));
\end{verbatim}
The associated Scilab function is:
\begin{verbatim}
function [y1,y2,y3,y4,y5]=foobar(x1,x2,x3,x4)
\end{verbatim}
where {\tt x1} is a character string, and {\tt x2, x3, x4} are
matrices which, in the called C function, {\tt foubare2c} are
respectively integer, real and double arrays.

\medskip
\noindent
The interface program is the following:
\scriptsize
\begin{verbatim}
int intsfoubare(fname) 
     char *fname;
{
  int i1, i2;
  static int ierr;
  static int l1, m1, n1, m2, n2, l2, m3, n3, l3, m4, n4, l4, l5, l6;
  static int minlhs=1, minrhs=4, maxlhs=5, maxrhs=4;

  Nbvars = 0;
  
  CheckRhs(minrhs,maxrhs) ;
  CheckLhs(minlhs,maxlhs) ;

  GetRhsVar(1, "c", &m1, &n1, &l1);
  GetRhsVar(2, "i", &m2, &n2, &l2);
  GetRhsVar(3, "r", &m3, &n3, &l3);
  GetRhsVar(4, "d", &m4, &n4, &l4);
  
  CreateVar(5, "d", &m4, &n4, &l5);
  CreateVar(6, "d", &m4, &n4, &l6);

  i1 = n2 * m2;
  i2 = n3 * m3;
  
  foubare2c(cstk(l1), istk(l2), &i1, sstk(l3), &i2, stk(l4), 
	     &m4, &n4, stk(l5),stk(l6), &ierr);
  
  if (ierr > 0) 
    {
      sciprint("Internal Error");
      Error(999);
      return 0;
    }
  
  LhsVar(1) = 5;
  LhsVar(2) = 4;
  LhsVar(3) = 3;
  LhsVar(4) = 2;
  LhsVar(5) = 1;
  PutLhsVar();
  return 0;
}

static TabF Tab[]={ 
  {intsfoubare, "foobar"} 
} ; 

int C2F(foobar)()
{
  Rhs = Max(0, Rhs);
  (*(Tab[Fin-1].f))(Tab[Fin-1].name);
  return 0;
} 
\end{verbatim}
\normalsize

Note that the last part of the interface program should contain in the
table {\tt  TabF} the pair = (name of the interface program, name of
the associated Scilab function). If several functions are 
interfaced in the interface a pair of names should be given for each function.
The entrypoint {\tt foobar}
is used by the dynamic link command {\tt addinter}.

\subsection{{\tt addinter} command}
Once the interface program is written, it must be compiled to produce 
an object file. It is then linked to Scilab by the addinter command.

The syntax of addinter is the following:

{\tt addinter([`interface.o', 'userfiles.o'],'entrypt',['scifcts'])}

Here {\tt interface.o} is the object file of the interface, 
{\tt userfiles.o} is the set of user's routines to be linked, 
{\tt entrypt} is the entry point of the interface routine and 
{'scifcts'} is the set of Scilab functions to be interfaced.

In the previous example {\tt addinter} can be called as follows:
\begin{verbatim}
addinter(['Examplc.o','foubare2c.o'],'foobar','foubare');
\end{verbatim}

\section{Intersci}

\newcommand{\ISCI}{Intersci}
\newcommand{\SCI}{Scilab}
\newcommand{\T}[1]{{\tt #1}}
\newcommand{\M}[1]{$<${\em #1}$>$}
\newcommand{\ie}{\mbox{i.e.}}

\ISCI\ is a program for building an interface file between \SCI\ and Fortran
subroutines or C functions. This interface describes both the routine
called and the associated \SCI\ function.  The interface is automatically 
generated from a description file with {\tt .desc} suffix.

%%%%%%%%%%%%%%%%%%%%%
\subsection{Using \ISCI}
%%%%%%%%%%%%%%%%%%%%%
In the following, we will only consider Fortran subroutine interfacing. The
process is nearly the same for C functions (see \ref{C}).

\smallskip

To use \ISCI\ execute the command:\\
\T{intersci }\M{interface name}\T{\ }\\
where \M{interface name}\T{.desc} is the file describing the interface.

The {\tt intersci} script file is located in the directory SCIDIR/bin.

Then the interface file \M{interface name}\T{.f} is created. A Scilab
script file {\tt .sce} is also created. This file, with appropriate
changes, can be used to link the interface with Scilab.

\smallskip

The file \M{interface name}\T{.desc} is a sequence of descriptions of 
pairs formed by the \SCI\ function and the corresponding Fortran subroutine
(see table \ref{t-pair}).

\begin{table}
\begin{center}
\begin{tabular}{|l|}
\hline
\M{\SCI\ function name} \M{function arguments}\\
\M{\SCI\ variable} \M{\SCI\ type} \M{possible arguments}\\
\quad$\vdots$\qquad\qquad$\vdots$\qquad\qquad$\vdots$\qquad\qquad$\vdots$
  \qquad\qquad$\vdots$\\
\M{Fortran subroutine name} \M{subroutine arguments}\\
\M{Fortran argument} \M{Fortran type}\\
\quad$\vdots$\qquad\qquad$\vdots$\qquad\qquad$\vdots$\qquad\qquad$\vdots$\\
out \M{type} \M{formal output names}\\
\M{formal output name} \M{variable}\\
\quad$\vdots$\qquad\qquad$\vdots$\qquad\qquad$\vdots$\qquad\qquad$\vdots$\\
*******************************\\
\hline
\end{tabular}
\end{center}
\caption{Description of a pair of \SCI\ function and Fortran subroutine}
\label{t-pair}
\end{table}

Each description is made of three parts: 
\begin{itemize}
\item
description of \SCI\ function and its arguments
\item
description of Fortran subroutine and its arguments
\item
description of the output of \SCI\ function.
\end{itemize}

\paragraph{Description of \SCI\ function}
%%%%%%%%%%%
\label{scilab}

The first line of the description is composed by the name of the \SCI\
function followed by its input arguments.

The next lines describe \SCI\ variables: the input arguments and the
outputs of the \SCI\ function, together with the arguments of the Fortran
subprogram with type \T{work} (for which memory must be allocated).
It is an error not to describe such arguments.

The description of a \SCI\ variable begins by its name, then its type followed
by possible informations depending on the type.

Types of \SCI\ variables are:
\begin{description}
  \item[any] any type: only used for an input argument of \SCI\ function.
  \item[column] column vector: must be followed by its dimension.
  \item[list] list: must be followed by the name of the list,
\M{list name}. This name must correspond to a file \M{list name}\T{.list}
which describes the structure of the list (see \ref{list}).
  \item[matrix] matrix: must be followed by its two dimensions.
  \item[polynom] polynomial: must be followed by its dimension (size) and the
name of the unknown.
  \item[row] row vector: must be followed by its dimension.
  \item[scalar] scalar.
  \item[string] character string: must be followed by its dimension
(length).
  \item[vector] row or column vector: must be followed by its dimension.
  \item[work] working array: must be followed by its dimension. It must not
correspond to an input argument or to the output of the \SCI\ function.
\end{description}

\smallskip

A blank line and only one ends this description.

\paragraph{Optional input arguments}

Optional arguments are defined as follows:
\begin{itemize}
\item{
\verb! [c val] !. This means that \verb!c! is an optional argument with
default value \verb!val!.  \verb!val! can be a scalar: e.g. \verb![c 10]!, 
an array: e.g. \verb! [c (4)/1,2,3,4/]! or a chain: e.g. \verb![c pipo]! 
}
\item{
\verb!{b xx}!. This means that \verb!b! is an optional argument.
If not found, one looks for \verb!xx! in current existing Scialb variables.
}
\end{itemize}

\paragraph{Description of Fortran subroutine}
%%%%%%%%%%%
\label{Fortran}

The first line of the description is composed by the name of the 
Fortran subroutine followed by its arguments.

The next lines describe Fortran variables: the arguments of the Fortran
subroutine. 

The description of a Fortran variable is made of its name and its type.
Most Fortran variables correspond to \SCI\ variables (except for
dimensions, see \ref{dimensions}) and must have the same name as the
corresponding \SCI\ variable.

\smallskip

Types of Fortran variables are:
\begin{description}
  \item[char] character array.
  \item[double] double precision variable.
  \item[int] integer variable.
  \item[real] real variable.
\end{description}

Other types types also exist, that are called ``external'' types see \ref{external}.

\smallskip

A blank line and only one ends this description.

\paragraph{Description of the output of \SCI\ function}
%%%%%%%%%%%
\label{output}

The first line of this description must begin by the word \T{out} followed
by the type of \SCI\ output.

\smallskip

Types of output are:
\begin{description}
  \item[empty] the \SCI\ function returns nothing.
  \item[list] a \SCI\ list: must be followed by the names of \SCI\ variables
which form the list.
  \item[sequence] a \SCI\ sequence: must be followed by the names of \SCI\
variables elements of the sequence. This is the usual case.
\end{description}

This first line must be followed by other lines corresponding to output type
conversion. This is the case when an output variable is also an input variable
with different \SCI\ type: for instance an input column vector becomes an
output row vector. The line which describes this conversion begins by the name
of \SCI\ output variable followed by the name of the corresponding \SCI\ input
variable. See \ref{ex3} as an example.
\medskip

A line beginning with a star ``\T{*}'' ends the description of a pair of
\SCI\ function and Fortran subroutine. This line is compulsory even if it is
the end of the file. Do not forget to end the file by a carriage return.

\paragraph{Dimensions of non scalar variables}
%%%%%%%%%%%
\label{dimensions}

When defining non scalar \SCI\ variables (vectors, matrices, polynomials and
character strings) dimensions must be given. There are a few ways to do that:

\begin{itemize}
  \item It is possible to give the dimension as an integer (see \ref{ex1}).
  \item The dimension can be the dimension of an input argument of \SCI\
function. This dimension is then denoted by a formal name (see \ref{ex2}). 
  \item The dimension can be defined as an output of the Fortran subroutine.
This means that the memory for the corresponding variable is allocated by the
Fortran subroutine. The corresponding Fortran variable must necessary have an
external type (see \ref{external} and \ref{ex3}).
\end{itemize}

\ISCI\ is not able to treat the case where the dimension is an algebraic
expression of other dimensions. A \SCI\ variable corresponding to this value
must defined.

\paragraph{Fortran variables with external type}
%%%%%%%%%%%
\label{external}

External types are used when the dimension of the Fortran variable is
unknown when calling the Fortran subroutine and when its memory size is
allocated in this subroutine. This dimension must be an output of the Fortran
subroutine. In fact, this will typically happen when we want to interface a C
function in which memory is dynamically allocated.

\smallskip

Existing external types:
\begin{description}
 \item[cchar] character string allocated by a C function to be copied into the
corresponding \SCI\ variable.
 \item[ccharf] the same as \T{cchar} but the C character string is freed after
the copy.
 \item[cdouble] C double array allocated by a C function to be copied into the
corresponding \SCI\ variable.
 \item[cdoublef] the same as \T{cdouble} but the C double array is freed after
the copy.
 \item[cint] C integer array allocated by a C function to be copied into the
corresponding \SCI\ variable.
 \item[cintf] the same as \T{cint} but the C integer array is freed after
the copy.
\end{description}

\medskip

In fact, the name of an external type corresponds to the name of a C function.
This C function has three arguments: the dimension of the variable, an input
pointer and an output pointer.

For instance, below is the code for external type \T{cintf}:
\begin{verbatim}
#include "../machine.h"   

/* ip is a pointer to a Fortran variable coming from SCILAB
which is itself a pointer to an array of n integers typically
coming from a C function
   cintf converts this integer array into a double array in op 
   moreover, pointer ip is freed */

void C2F(cintf)(n,ip,op)
int *n;
int *ip[];
double *op;
{
  int i;
  for (i = 0; i < *n; i++)
    op[i]=(double)(*ip)[i];
  free((char *)(*ip));
}
\end{verbatim}

For the meaning of \verb|#include "../machine.h"| and \T{C2F} see \ref{C}.

\smallskip

Then, the user can create its own external types by creating its own C
functions with the same arguments. \ISCI\ will generate the call of the
function. 

\paragraph{Using lists as input \SCI\ variables}
%%%%%%%%%%%
\label{list}

An input argument of the \SCI\ function can be a \SCI\ list.
If \M{list name} is the name of this variable, a file called 
\M{list name}\T{.list}
must describe the structure of the list. This file permits to associate
a \SCI\ variable to each element of the list by defining
its name and its \SCI\ type. The variables are described in order into the
file as described by table \ref{t-list}.

Then, such a variable element of the list, in the file \M{interface
name}\T{.desc}  is referred to as its name followed by the name of 
the corresponding list in parenthesis. For
instance, \T{la1(g)} denotes the variable named \T{la1} element of the list
named \T{g}.

\begin{table}
\begin{center}
\begin{tabular}{|l|}
\hline
\M{comment on the variable element of the list}\\
\M{name of the variable element of list} \M{type} \M{possible arguments}\\
*******************************\\
\hline
\end{tabular}
\end{center}
\caption{Description of a variable element of a list}
\label{t-list}
\end{table}

An example is shown in \ref{ex4}.

\subsubsection{C functions interfacing}
%%%%%%%%%%%
\label{C}

The C function must be considered as a procedure \ie\
its type must be \T{void} or the returned value must not be used.

The arguments of the C function must be considered as Fortran arguments \ie\
they must be only pointers.

Moreover, the name of the C function must be recognized by
Fortran. For that, the include file \T{machine.h} located in the
directory \M{\SCI\ directory}\T{/routines} should be included in 
C functions and the macro \T{C2F} should be used.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection{Writing compatible code}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\label{compat}

\paragraph{ Messages and Error Messages}

To write messages in the  \SCI\ main window, user  must call the
{\tt out} Fortran routine or {\tt cout} C procedure with the
character string of the desired message as input argument.

To return an error flag of  an interfaced routine user must call the
{\tt erro} Fortran routine or {\tt cerro} C procedure with the
character string of the desired message as input argument. This call
will produce the edition of the message in the \SCI\ main window and
the error exit of \SCI\ associated function.

{ Input and output}
%%%%%%%%%%%


To open files in Fortran, it is highly recommended to  use the 
\SCI routine {\tt   clunit}. If the interfaced routine uses the 
Fortran {\tt open}
instruction, logical units must in any case be greater than 40.
\begin{verbatim}
      call clunit( lunit, file, mode)
\end{verbatim}
with:
\begin{itemize}
\item {\tt file} the file name {\tt character string}
\item {\tt mode} a two integer vector defining the opening mode
 {\tt mode(2)} defines the record length for a direct access file if
 positive. 
{\tt mode(1)} is an integer formed with three digits {\tt f}, {\tt a }
and {\tt s}
\begin{itemize}
\item {\tt f} defines if file is formatted ({\tt 0}) or not ({\tt 1})
\item {\tt a} defines if file has sequential ({\tt 0}) or direct
  access ({\tt 1})
\item {\tt s} defines if file status must be new ({\tt 0}), old ({\tt
    1}), scratch ({\tt 2}) or unknown ({\tt 3})
\end{itemize}
\end{itemize}

Files opened by a call to {\tt   clunit} must be close by 
\begin{verbatim}
      call clunit( -lunit, file, mode)
\end{verbatim}
In this case the {\tt file} and  {\tt mode} arguments are not
referenced.

%%%%%%%%%%%%%%%%%%
\subsubsection{Examples}
%%%%%%%%%%%%%%%%%%

\paragraph{Example 1}
%%%%%%%%%%%
\label{ex1}

The \SCI\ function is \T{a=calc(str)}. Its input is a string and its
output is a scalar.

The corresponding Fortran subroutine is \T{subroutine
fcalc(str,a)}. Its arguments
are a string {\tt str} (used as input) and an integer {\tt a} (used as output).

We reserve a fixed dimension of 10 for the string.

The description file is the following:
\begin{verbatim}
calc    str
str     string  10
a       scalar

fcalc   str     a
str     char
a       integer

out     a
***********************
\end{verbatim}

\paragraph{Example 2}
%%%%%%%%%%%
\label{ex2}

The name of the \SCI\ function is \T{c=som(a,b)}. Its two inputs are
row vectors and its  output is a column vector.

The corresponding Fortran subroutine is \T{subroutine
fsom(a,n,b,m,c)}. Its arguments
are a real array with dimension n (used as input), another 
real array with  dimension m (used as input) and a real array (used as output).
These dimensions \T{m} and \T{n} are determined at the calling of the \SCI\
function and do not need to appear as \SCI\ variables.

\ISCI\ will do the job to make the necessary conversions to transform the
double precision (default in \SCI) row vector \T{a} into a real array and to
transform the real array \T{c} into a double precision row vector.

The description file is the following:
\begin{verbatim}
som     a       b
a       row     m
b       row     n
c       column  n

fsom    a       n       b       m       c
a       real
n       integer
b       real
m       integer
c       real

out     sequence        c
***********************
\end{verbatim}

\paragraph{Example 3}
%%%%%%%%%%%
\label{ex3}

The \SCI\ function is \T{[o,b]=ext(a)}. Its input is a matrix and its
outputs are a matrix and a column vector.

The corresponding Fortran subroutine is \T{fext(a,m,n,b,p)} and its arguments
are an integer array (used as input and output), its dimensions m,n (used as
input) and another integer array and its dimension p (used as outputs).

The dimension \T{p} of the output \T{b} is computed by the Fortran subroutine
and the memory for this variable is also allocated by the Fortran subroutine
(perhaps by to a call to another C function). So the type of the variable is
external and we choose \T{cintf}.

Moreover, the output \T{a} of the \SCI\ function is the same as the input
but its type changes from a $m \times n$ matrix to a $n \times m$ matrix. This
conversion is made my introducing the \SCI\ variable \T{o}

The description file is the following:
\begin{verbatim}
ext     a
a       matrix  m       n
b       column  p
o       matrix  n       m

fext    a       m       n       b       p
a       integer
m       integer
n       integer
b       cintf
p       integer

out     sequence        o       b
o       a
***************************
\end{verbatim}

\paragraph{Example 4}
%%%%%%%%%%%
\label{ex4}

The name of the \SCI\ function is \T{contr}. Its input is a list representing
a linear system given by its state representation and a tolerance. Its return
is a scalar (for instance the dimension of the controllable subspace).

The name of the corresponding Fortran subroutine is \T{contr} and its
arguments are the dimension of the state of the system (used as input), the
number of inputs of the system (used as input), 
the state matrix of the system (used as input),
the input matrix of the system (used as input),
an integer giving the dimension of the controllable subspace (used as output),
and the tolerance (used as input).

The description file is the following:
\begin{verbatim}
contr   sys     tol
tol     scalar
sys     list    lss
icontr  scalar

contr   nstate(sys)     nin(sys)     a(sys)  b(sys)  icontr  tol
a(sys)  double
b(sys)  double
tol     double
nstate(sys)     integer
nin(sys)        integer
icontr  integer

out     sequence        icontr
******************************
\end{verbatim}

The type of the list is \T{lss} and a file describing the list \T{lss.list} is
needed. It is shown below:

\begin{verbatim}
1 type
type    string  3
******************************
2 state matrix
a       matrix  nstate  nstate
******************************
3 input matrix
b       matrix  nstate  nin
******************************
4 output matrix
c       matrix  nout    nstate
******************************
5 direct tranfer matrix
d       matrix  nout    nin
******************************
6 initial state
x0      column  nstate
******************************
7 time domain
t       any
******************************
\end{verbatim}

The number of the elements is not compulsory in the comment describing the
elements of the list but is useful.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%\tableofcontents

%\listoftables

\subsubsection{Adding a new primitive}

It is possible to add a set a new built-in functions to Scilab
by a permanent link the interface program. 
For that, it is necessary to update the files {\tt default/fundef}
and {\tt   routines/callinter.h}.

When {\tt intersci} is invoked as follows:\\

\T{intersci }\M{interface name}\T{\ }\M{interface number}\\

{\tt intersci} then builds a {\tt .fundef} file which is used to
update the {\tt default/fundef} file.

To add a new interface the user needs also
to update the {\tt   routines/callinter.h} file with a particular 
value of {\tt fun} Fortran variable corresponding to the new interface
number.

Two unused empty interface routines called by default ({\tt matusr.f} 
and {\tt matus2.f}) are predefined and may be replaced by 
the interface program. Their interface numbers {\tt 14} and {\tt 24}
respectively. They can be used as default interface programs.
The executable code of Scilab is then made by typing ``make all''
or ``make bin/scilex'' in Scilab directory.

\section{The {\tt routines/default} directory}

The {\tt SCIDIR/routines/default} directory contains a set of C and Fortran
routines which can be customized by the user. When customizing a
routine in this directory a new executable code for Scilab is made
by typing {\tt make all} in the main Scilab directory. 
It is possible to add new primitives by modifying the default files
given in this directory. The file {\tt Ex-fort.f} contains a example
of a subroutine ({\tt bidon2}) which can be interactively called
by the Scilab {\tt fort} command. Thus, it is possible 
to call a C or Fortran routine by modifying the {\tt Ex-fort.f}
file, re-making Scilab and then using the {\tt fort} function.
The {\tt link} operation now made outside Scilab by the {\tt make all}
command which creates a full new executable code for Scilab 
({\tt SCIDIR/bin/scilex}).

Let us consider again the example of the {\tt daxpy} function.
We want to call it from Scilab by the following function 
\begin{verbatim}
function y=scilabdaxpy(a,x,incx,y,incy)
y=fort('daxpy1',a,x,incx,y,incy)
\end{verbatim}
which performs the following: 

\verb!y(1:incy:n*incy)=y(1:incy:n*incy)+a*x(1:incx:n*incx)!

\noindent
The {\tt fort} 
function looks for the called program (here {\tt daxpy1}) in the
interface file {\tt default/Ex-fort.f}: for that, it is necessary
that the name {\tt daxpy1} appear
in the file {\tt default/Flist}. (We do not use the {\tt link} command
here).

Note that the {\tt fort} function just sends the Scilab variables
{\tt a,x,incx,y,incy} to the interface program {\tt Ex-fort.f}.
These variables are associated with the numbers {\tt 1,2,3,4,5,6}, 
respectively in the interface program {\tt Ex-fort.f}.
\noindent
For our {\tt scilabdaxpy} function, we perform the following steps:
\begin{itemize}
\item Add the name {\tt daxpy1} to the appropriate list of functions 
in the file {\tt Flist} in the {\tt routines/default} directory:
\begin{verbatim}
interf_list= ... daxpy1
\end{verbatim}
\item Edit the file {\tt routines/default/Ex-fort.f} and
insert the following code:
\begin{verbatim}
 subroutine daxpy1()
 include '../stack.h'

 n=msize(2,mx,nx)

 call alloc(1,1,1,1,'d')
 call alloc(2,n,mx,nx,'d')
 call alloc(3,1,1,1,'i')
 call alloc(4,n,mx,nx,'d')
 call alloc(5,1,1,1,'i')

 call daxpy(n,stk(ladr(1)),stk(ladr(2)),stk(ladr(3)),
+             stk(ladr(4)),stk(ladr(5)))
 call back(4)
 return
 end
\end{verbatim}
\end{itemize}

The interface is done using the functions {\tt msize}, {\tt alloc} and
{\tt back}. When the command {\tt fort('daxpy1',a,x,incx,y,incy)}
is issued, each variable {\tt a,x,incx,y,incy} is automatically
assigned a number in {\tt Ex-fort}, in increasing order.
Here {\tt a} is assigned number 1, {\tt x} is assigned number 2, etc. 
Variable \# {\tt n} is located in Scilab internal stack {\tt stk} at 
adress {\tt ladr(n)}. For instance, {\tt x}, (the third variable in {\tt daxpy}
calling sequence), is associated with the pointer {\tt ladr(2)} in 
{\tt stk} since {\tt x} is variable \# {\tt 2}. 



The statement {\tt n=msize(2,mx,nx)} retrieves the dimensions
{\tt mx, nx} of variable \# 2 i.e. {\tt x} and {\verb!n=mx*mx!} i.e. 
n=number of rows $\times$ number of columns.

 This function allows to
know the dimensions of all the variables passed to {\tt fort}.
At this stage, the user can test that the dimensions of the variables
are correct; the corresponding error message can be done as follows:
\begin{verbatim}
 buf='error message'
 call error(9999)
 return
\end{verbatim}

The function {\tt alloc} defines the type of a variable (integer,
real, double), sets its
dimensions and allocate memory for it. 
For instance {\tt call alloc(4,mx*nx,mx,nx,'d')} is used to define
the fourth variable ({\tt y}) as a matrix with {\tt mx} rows and {\tt nx}
columns of type ``double''.
The last parameter of {\tt alloc} should be {\tt 'i'} for integer, 
{\tt 'r'} for real or {\tt 'd'} for double.


 When {\tt alloc} is called with a number {\tt n} 
(as first parameter) which does not correspond to a input of {\tt fort},
a valid new adress (pointer) {\tt ladr(n)} is automatically set.
For instance the statement {\tt call alloc(6,12,4,3,'i')} will 
return in {\tt ladr(6)}  a pointer for a 6th matrix variable (not in the 
parameters of {\tt fort}) with dimensions
{\tt 3} $\times$ {\tt 4} and integer type.

Note that the default type for variables is {\tt 'd'} i.e. double.
For such variables, the call to {\tt alloc} can be omitted: in our example,
only the statements {\tt call alloc(3,...,'i')} 
and {\tt call alloc(5,...,'i')} which convert {\tt incx} and 
{\tt incy} to integers are necessary. However, the call to 
{\tt alloc} is always necessary for defining a variable which does not 
appear in the {\tt fort} parameters.

After the call to {\tt daxpy}, the function {\tt back(i)} returns 
variable number {\tt i} to Scilab. This variable has the dimensions
set by the previous call to {\tt alloc} and is converted into a Scilab
matrix.

\subsection{Argument functions}
Some built-in nonlinear solvers, such as {\tt ode} or {\tt optim}, require a 
specific function as argument. For instance in the Scilab command
{\tt ode(x0,t0,t,fydot)}, {\tt fydot} is the specific argument function
for the {\tt ode} primitive.
This function can be a either Scilab function or an external
function written in C or Fortran.
In both cases, the argument function must obey a specific
syntax. In the following we will consider, as running example, using 
the {\tt ode} primitive with a rhs function written in Fortran. The
same steps should be followed for all primitives which require
a function as argument.

If the argument function is written in C or Fortran, there
are two ways to call it:
\begin{itemize}
\item -Use dynamic link
\begin{verbatim}
-->link('myfydot.o','myfydot')  //or -->link('myfydot.o','myfydot','C')
-->ode(x0,t0,t,'myfydot')
\end{verbatim}
\item -Use the {\tt Ex-ode.f} interface in the {\tt routines/default}
directory (and {\tt make all} in Scilab directory).
The call to the {\tt ode} function is as above:
\begin{verbatim}
-->ode(x0,t0,t,'myfydot')
\end{verbatim}
\end{itemize}
In this latter case, to add a new function, two files should be updated:
\begin{itemize}
\item The {\tt Flist} file: Flist is list of entry points. Just add the 
name of your function at in the appropriate list of functions.
\begin{verbatim}
ode_list= ... myfydot
\end{verbatim}
\item The {\tt Ex-ode.f} (or {\tt Ex-ode-more.f}) file: this file contains the 
source code for argument functions. Add your function here.
\end{itemize}

Many exemples are provided in the {\tt default} directory.
More complex examples are also given. For instance it is shown 
how to use Scilab variables as optional parameters of {\tt fydot}.

\section{Maple to Scilab Interface}
\index{Maple}
To combine symbolic computation of the computer algebra system Maple with the 
numerical facilities
of Scilab, Maple objects can be transformed into Scilab functions. To assure 
efficient numerical evaluation this is done through numerical evaluation in 
Fortran. The whole process is done by a Maple procedure called 
\verb/maple2scilab/.
\section{Maple2scilab}
\index{maple2scilab@{\tt maple2scilab}}
The procedure \verb!maple2scilab! converts a Maple object, 
either a scalar function or a matrix into a Fortran subroutine 
and writes the associated Scilab function. The code of \verb!maple2scilab!
is in the directory \verb!SCIDIR/maple!.

The calling sequence of \verb!maple2scilab! is as follows:\\
\verb!maple2scilab(function-name,object,args)!
\begin{itemize}
\item
The first argument, \verb!function-name! is a name indicating the 
function-name in Scilab.
\item
The second argument \verb!object! is the Maple name of the expression 
to be transferred to Scilab.
\item
The third argument is a list of arguments containing the formal parameters of
the Maple-object \verb!object!.
\end{itemize}
When \verb!maple2scilab! is invoked in Maple, two files are generated,
one which contains the Fortran code and another which contains the 
associated Scilab function. Aside their existence, the user has not to
know about their contents.

The Fortran routine which is generated has the following calling sequence:\\
{\tt <Scilab-name>(x1,x2,\ldots,xn,matrix)} \\
and this subroutine computes matrix(i,j) as a function of
the arguments {\tt x1,x2,\ldots,xn}.
Each argument can be a Maple scalar or array which should be
in the argument list. 
The Fortran subroutine is put into a file named {\tt <Scilab-name>.f}, the
Scilab-function into a file named {\tt <Scilab-name>.sci}.
For numerical evaluation in Scilab the user has to compile the Fortran 
subroutine, to link it with Scilab (e.g. Menu-bar option '\verb!link!')
and to load the associated function (Menu-bar option '\verb!getf!').
Information about \verb!link! operation is given in Scilab's manual: 
Fortran routines can be incorporated into Scilab by dynamic
link or through the \verb!Ex-fort.f! file in the \verb!default! directory.
 Of course, this two-step procedure can be automatized using a shell-script 
(or using \verb!unix! in Scilab).
Maple2scilab uses the ``Macrofort'' library which is in the share 
library of Maple.
\subsection{Simple Scalar Example}
\paragraph{Maple-Session}
\begin{verbatim}
> read(`maple2scilab.maple`):
> f:=b+a*sin(x);

                               f := b + a sin(x)

> maple2scilab('f_m',f,[x,a,b]);
\end{verbatim}
Here the Maple variable \verb!f! is a scalar expression but it could be also
a Maple vector or matrix.
\verb/ 'f_m'/ will be the name of \verb!f! in Scilab 
(note that the Scilab name is restricted to contain at most 6 characters).
The procedure \verb/maple2scilab/ creates two files: \verb/f_m.f/ 
and  \verb/f_m.sci/ in the directory where Maple is started.
To specify another directory just define in Maple the path : 
\verb/rpath:=`//\verb/work//` ; then all files are written in 
the sub-directory \verb/work/.
The file \verb!f_m.f! contains the source code of a stand alone Fortran
routine which is dynamically linked to Scilab by the function \verb!f_m! in
defined in the file \verb!f_m.sci!.

\paragraph{Scilab Session}
\begin{verbatim}
-->unix('make f_m.o');
 
-->link('f_m.o','f_m');

linking  _f_m_ defined in f_m.o  
 
-->getf('f_m.sci','c')
 
-->f_m(%pi,1,2)
 ans       =
 
    2.  
\end{verbatim}

\subsection{Matrix Example}
This is an example of transferring a Maple matrix into Scilab.
\paragraph{Maple Session}
\begin{verbatim}
> with(linalg):read(`maple2scilab.maple`):

> x:=vector(2):par:=vector(2):

> mat:=matrix(2,2,[x[1]^2+par[1],x[1]*x[2],par[2],x[2]]);

                            [     2                     ]
                            [ x[1]  + par[1]  x[1] x[2] ]
                    mat :=  [                           ]
                            [     par[2]         x[2]   ]

> maple2scilab('mat',mat,[x,par]);

\end{verbatim}

\paragraph{Scilab Session}
\begin{verbatim}
-->unix('make mat.o');

-->link('mat.o','mat') 

linking  _mat_ defined in mat.o  
 
-->getf('mat.sci','c')

-->par=[50;60];x=[1;2];
 
-->mat(x,par)
 ans       =
 
!   51.    2. !
!   60.    2. !
 
\end{verbatim}

{\small
\paragraph{Generated code}
Below is the code (Fortran subroutines and Scilab functions) which is 
automatically generated by {\tt maple2scilab} in the two preceding  examples.
\paragraph{Fortran routines}
\begin{verbatim}
c      
c     SUBROUTINE f_m
c      
      subroutine f_m(x,a,b,fmat)
      doubleprecision x,a,b
      implicit doubleprecision (t)
      doubleprecision fmat(1,1)
         fmat(1,1) = b+a*sin(x)
      end
\end{verbatim}
\begin{verbatim}
c      
c     SUBROUTINE mat
c      
      subroutine mat(x,par,fmat)
      doubleprecision x,par(2)
      implicit doubleprecision (t)
      doubleprecision fmat(2,2)
         t2 = x(1)**2
         fmat(2,2) = x(2)
         fmat(2,1) = par(2)
         fmat(1,2) = x(1)*x(2)
         fmat(1,1) = t2+par(1)
      end
\end{verbatim}
\paragraph{Scilab functions}
\begin{verbatim}
function [var]=f_m(x,a,b)
var=fort('f_m',x,1,'d',a,2,'d',b,3,'d','out',[1,1],4,'d')
\end{verbatim}
\begin{verbatim}
function [var]=fmat(x,par)
var=fort('fmat',x,1,'d',par,2,'d','out',[2,2],3,'d')
\end{verbatim}
}
%\end{document}