new

1 files changed, 429 insertions, 294 deletions

diff --git a/scilab_doc/intro/chap6.tex b/scilab_doc/intro/chap6.tex
index 3aea0de..a21f156 100755
--- a/scilab_doc/intro/chap6.tex
+++ b/scilab_doc/intro/chap6.tex
@@ -1,15 +1,4 @@
-% Copyright INRIA
-
-%\documentclass[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 with Scilab}
+\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
@@ -38,31 +27,30 @@ and then to interactively call
 the linked routine by {\tt call}\index{call@{\tt call}} primitive
 which transmits Scilab variables (matrices or strings) to the linked program
 and transforms back the output parameters into Scilab variables. 
+Note that all the parameters of the routine called by the {\tt call} 
+primitive must be pointers. In particular Fortran routines can be called
+using the {\tt call} primitive.
+
 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 following directories
-{\tt routines/examples/interface-tutorial} and {\tt routines/examples/interface-tour}. Examples of Matlab-like interfaces are given in the directory
-{\tt routines/examples/mexfiles}.
+the user following the examples given in the directories
+{\tt routines/examples/interface-*}. The simplest way to build an
+interface program is to copy/paste one of the examples given there and to
+adapt the code to your problem.
+
+Examples of Matlab-like mexfunction interfaces are given in the 
+directory {\tt routines/examples/mexfiles}.
 
-The interface program can also be generated by {\tt
+The interface program can also be generated by the tool {\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 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 
@@ -72,9 +60,9 @@ how to call a dynamically linked program.
 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']!).
+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
@@ -99,12 +87,10 @@ Link done
  n  =
  
     0.  
- 
--->c_link('daxpy')
+ -->c_link('daxpy')
  ans  =
  
   T  
-
 -->ulink(n)
  
 -->c_link('daxpy')
@@ -113,7 +99,8 @@ Link done
   F  
 \end{verbatim}
 
-For more details, enter {\tt help link}.
+For more details, enter {\tt help link}. The {\tt link} primitive can load
+a set of object files and/or a static library and/or a dynamic library.
 
 \subsection{Calling a dynamically linked program}
 
@@ -129,6 +116,11 @@ The calling sequence for {\tt daxpy} is as follows:
 \begin{verbatim}
       subroutine daxpy(n,a,x,incx,y,incy)
 \end{verbatim}
+The parameters of a Fortran program are pointers. The C code for the 
+same function would be :
+\begin{verbatim}
+void daxpy(int *n,double *a,double *x,int *incx,double *y,int *incy)
+\end{verbatim}
 To call {\tt daxpy} from Scilab we must use a syntax as follows: 
 \begin{verbatim}
 [y1,y2,y3,...]=call('daxpy', inputs description, ...
@@ -144,7 +136,8 @@ 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).
+({\tt t='i'  t='r'  t='d' t='c'} stands for integer, real,  double, char
+ respectively).
 
 \noindent
 {\tt outputs description} is a set of parameters
@@ -153,9 +146,9 @@ sequence of {\tt daxpy} and {\tt ti} is the type of {\tt xi} in {\tt daxpy}
 
 \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
+1 x 2 integer vector giving the number of rows and columns of the
+ith output variable {\tt yi}. The position, {\tt pi}, and the type, {\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 call}  divided into four groups.
@@ -163,12 +156,12 @@ 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'}.  
+and their data type.  The group of arguments at the right of {\tt 'out'}
+are the dimensions of the output variables, their positions in the calling
+sequence of {\tt daxpy}, and their data type.
+The possible data types are real, integer, double and character which
+are indicated, respectively, by the strings {\tt 'r'}, {\tt 'i'}, {\tt 'd'}
+and {\tt 'c'}.  
 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 
@@ -180,13 +173,11 @@ at position {\tt p1=5}. To simplify, we assume here that {\tt x} and
 \begin{verbatim}
 -->a=3;
  
--->x=[1,2,3,4];
- 
--->y=[1,1,1,1];
+-->x=[1,2,3,4];y=[1,1,1,1];
  
 -->incx=1;incy=1;
 
--->n=size(x,'*');
+-->n=length(x);  //n=4
 
 -->y=call('daxpy',...
         n,1,'i',...
@@ -201,7 +192,6 @@ at position {\tt p1=5}. To simplify, we assume here that {\tt x} and
  y  =
  
 !   4.    7.    10.    13. !
-
 \end{verbatim}
 (Since {\tt y} is both input and output parameter, we could also use
 the simplified syntax 
@@ -240,19 +230,44 @@ Link done
 
 The routines which are linked to Scilab can also access internal 
 Scilab variables: see the examples in given in the {\tt examples/links}
-directory.
+directory. 
+
+\subsection{Building a dynamic library}
+The simple link of an object file as illustrated above may not work on some
+platforms. In this case, it is neccesary to build a (possibly dynamic) library 
+containing a set of programs and to link the library with Scilab.
+Examples are given the directory {\tt SCIDIR/example/link-examples-so}
+which are built to run in both a Linux/Unix (.so or .sl library) or 
+Windows environment (.dll library). The library is constructed by a specific
+Scilab function {\verb!ilib_for_link!} (which make use of libtool for Unix/
+Linux libraries). 
+Enter \verb!-->exec ext1c.sce! at the Scilab prompt, in this directory to
+see the simplest C example. The script file {\tt ext1c.sce} contains a call
+to  {\verb!ilib_for_link!} with appropriate parameters (files to be compiled,
+others libraries required, etc). The library is built using the environment
+parameters known by Scilab (compiler, linker etc). In addition a Scilab script 
+with generic name {\tt loader.sce} is created in the current directory.
+This script contains contains the code necessary to link the library with
+Scilab. Typically, it is a call to the {\tt link} primitive, with an 
+appropriate entry point (usually the name of the linked function).
+Note that the script file performs two tasks: building of the library
+and link of the library with the running Scilab. The first task is 
+generally performed once while the second should be made in every Scilab 
+session which needs linking the library.
 
 \section{Interface programs}
 
 \subsection{Building an interface program}
-Examples of interface programs are given in the directory 
-{\tt examples/interface-tutorial} and {\tt examples/interface-tour}. 
-
-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. 
+Many examples of interface programs are given in the 
+directories/subdirectories {\tt SCIDIR/examples/interface-*}. 
+
+The interface programs use a set of C or Fortran routines which
+are given in {\tt SCIDIR/routines/stack-c.h} and known by Scilab
+when this file is included in the interface program.
+
+The simplest way to learn how to build an interface program is to 
+look at the examples provided in the directory {\tt interface-tutorial}.
+
 Note that a unique interface program can be used to interface an 
 arbitrary (but less that $99$) number of functions.
 
@@ -303,8 +318,14 @@ should be sent to the C function \verb!matmul! and the matrix
 \verb!C! should be created, filled, and sent back to Scilab.
 
 To create the Scilab function \verb!matmul!, we have to write 
-the following C gateway function called
-\verb!intmatmul!. See the file \newline
+a gateway function (an interface function).
+A gateway function is a C function which must include the header file
+{\tt stack-c.h}. Fortran gatways include the file {\tt stack.h}.
+These files are located in the SCIDIR/routines directory.
+
+The following C gateway function called
+\verb!intmatmul! is an example of interface for the matrix multiplication
+program {\tt matmul}. See the file \newline
 \verb!SCIDIR/examples/interface-tutorial/intmatmul.c!.
 
 \scriptsize
@@ -314,8 +335,8 @@ the following C gateway function called
 int intmatmul(fname) 
      char *fname;
 {
-  static int l1, m1, n1, l2, m2, n2, l3;
-  static int minlhs=1, maxlhs=1, minrhs=2, maxrhs=2;
+  int l1, m1, n1, l2, m2, n2, l3;
+  int minlhs=1, maxlhs=1, minrhs=2, maxrhs=2;
 
   /* Check number of inputs (Rhs=2) and outputs (Lhs=1) */
   CheckRhs(minrhs,maxrhs) ; CheckLhs(minlhs,maxlhs) ;
@@ -369,7 +390,7 @@ The function \verb!CheckRhs! just compares the C variable \verb!Rhs!
 \noindent
 The next step is to deal with the Scilab variables \verb!A!, \verb!B! 
 and \verb!C!. In a gateway function, all the Scilab variables
-are referred to as numbers. Here, the Scilab matrices 
+are referred to as integer numbers. Here, the Scilab matrices 
 \verb!A!, \verb!B! and \verb!C! are 
 respectively numbered \verb!1!, \verb!2! and \verb!3!. 
 Each input variable of the newly created Scilab function
@@ -588,8 +609,15 @@ execute the script \verb!loader.sce!.
 \subsection{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 {\tt  stack-c.h} ) 
-when the interface is coded in C. The main functions are as follows:
+when the interface is coded in C. 
+An interface (gateway) routine is a standard C function or Fortran 
+program which include the file {\tt SCIDIR/routines/stack-c.h} 
+(C coded gateway)  or  {\tt SCIDIR/routines/stack.h} (Fortran coded gateway).
+
+The C functions which can be used in an interface program are available
+as soon as {\tt SCIDIR/routines/stack-c.h} is included in the source code.
+
+The main functions are the following:
 
 \begin{itemize}
 \item{
@@ -706,19 +734,348 @@ The best way to build an interface is to copy one of the examples
 given there and to adapt the code to particular needs.
 
 
-\subsection{The {\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.
+\section{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}.
 
-The syntax of addinter is the following:
+\section{Mexfiles}
+The directories under \verb!SCIDIR/examples/mexfiles! contain 
+some examples of Matlab mexfiles which can be used as interfaces
+in the Scilab environment. The Scilab \verb!mexlib! library emulates
+the most commonly used Matlab \verb!mxfunctions! such as 
+\verb!mxGetM!, \verb!mxGetPr!, \verb!mxGetIr! etc. Not all the 
+\verb!mxfunctions! are available but standard mexfiles which make use
+of matrices (possibly sparse), structs, character strings 
+and n-dimensional arrays can be used without any modification 
+in the Scilab environment. If the source program is already compiled
+and the mexfile given as a dynamic library, it is possible to  link
+the library with Scilab (examples are provided for Linux (.glnx extension)
+or Windows (.dll extension)).
+
+\section{Complements} 
+\subsection{Examining the data, function {\tt GetData}}
+The functions {\tt GetRhsVar} and {\tt CreateVar}
+described above for building an interface program can be used for
+most programs involving matrices. Many other functions can be used 
+for handling Scilab more complex data such as lists. See the examples
+in the directories examples/interfaces.
+It is also possible to define new objects from scratch within an interface.
+Let us first describe how to scan the Scilab objects. This can be done by the
+function {\tt GetData}.
+Consider the following simple interface program:
+\begin{verbatim}
+#include "stack-c.h"
+void intscan() 
+{
+  int *header; double *data;
+  header = GetData(1);
+  printf("%i %i %i %i\n", header[0], header[1], header[2], header[3]);
+  data = (double *) &header[4];
+  printf("%f %f %f\n", data[0]);
+}
+\end{verbatim}
+This interface can be built by the following Scilab script, \verb!scan.sce!:
+\begin{verbatim}
+ilib_name  = 'libintscan';
+files = ['intscan.o'];
+libs  = [];
+table = ['scan', 'intscan'];
+ilib_build(ilib_name,table,files,libs);
+\end{verbatim}
+After entering \verb!-->exec scan.sce! at Scilab prompt, a file \verb!loader.sce! is made:
+\begin{verbatim}
+libintscan_path=get_file_path('loader.sce');
+functions=['scan';];
+addinter(libintscan_path+'/libintscan.so','libintscan',functions);
+\end{verbatim}
+Entering \verb!-->exec loader.sce! allows to call the new \verb!scan! function.
+Now we can see the output of \verb!scan(A)! for, e.g., \verb!A=[4,2,3]!.
+We see that the Scilab variable \verb!A! is represented internally by
+a set of 4 integers (1,1,3,0) (the ``header'')  followed by 3 
+doubles (4,2,3) (the ``data''). The header is made of the following:
+type (1 stands for ``numeric matrix''), number of rows (1 since \verb!A! 
+is a row vector), number of columns (3 since \verb!A! has three 
+columns), complex type (0 since \verb!A! is real). The data contains 
+the entries of \verb!A!. All entries are considered (and stored) as double.
+Cleary, the function can be used to examine how Scilab variables are stored
+internally. For instance if \verb!B=int32(A)! we see that \verb!B! is stored
+with the header (8,1,3,4) and the int data (2,3,4). All integer matrix have 
+the type 8, and int32 receive the flag 4.
+
+The following program shows how a matrix of strings is represented.
+\begin{verbatim}
+#include "stack-c.h"
+void intscan() 
+{
+  int *header; 
+  int k,length,start,number;
+  header = (int *) GetData(1);
+  /* header = [10,Mrows,Ncols,0]  ... */
+  sciprint("string-type= %i, nrows= %i, ncols=%i, (reserved=) %i \n", 
+           header[0],header[1],header[2],header[3]);
+  /* ..[1, 1+length(entry 1),., 1+ .. +length(entry M*N) ].. */
+  number=header[1]*header[2];
+  start=5+number; 
+  /*  codes entry 1,   ...,   codes entry M*N  */
+  for (k=5; k<5+number; k++) {
+    length=header[k]-header[k-1];
+    sciprint("string %i has length %i\n", k-4, length);
+    sciprint("Code: first char =%i last char = %i\n",header[start],
+             header[start+length-1]);   
+    start=start+length;
+  }
+}
+\end{verbatim}
+We see here that string matrices are internally represented by integers. 
+When a string matrix is passed to an interface and the
+string matrix is processed by \verb!GetRhsVar(n,'c',&M,&N,&l)!
+then the strings are transformed into C chars.
+They can be obtained by the following piece of interface:
+\begin{verbatim}
+#include "stack-c.h"
+void intscan() 
+{
+  int M,N,l;  char *str;
+  GetRhsVar(1, "c", &M, &N, &l);
+  str = (char *) cstk(l);
+}
+\end{verbatim}
 
-{\tt addinter([`interface.o', 'userfiles.o'],'entrypt',['scifcts'])}
+\subsection{Creating new data types, function {\tt CreateData}}
 
-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.
+Consider now the interface program:
+\begin{verbatim}
+#include "stack-c.h"
+void intmy133() 
+{
+  int *header;
+  CreateData(1, 5*sizeof(int));
+  header = GetData(1);
+  header[0]=133; header[1]=1; header[2]=3; header[3]=0;
+  header[4]=35;
+  LhsVar(1)=1;
+}
+\end{verbatim}
+This interface can be built by the following Scilab script, \verb!my133.sce!:
+\begin{verbatim}
+ilib_name  = 'lib133';
+files = ['intmy133.o'];
+libs  = [];
+table = ['my133', 'intmy133'];
+ilib_build(ilib_name,table,files,libs);
+\end{verbatim}
+After entering \verb!-->exec my133.sce! at Scilab prompt, 
+a file \verb!loader.sce! is made, in the current directory and the new scilab
+function \verb!my133! is available after entering \verb!-->exec loader.sce!.
+Let us call this function. We get:
+\begin{verbatim}
+-->X=my133()
+ X  =
+ 
+Undefined display for this data type
+-->type(X)
+ ans  =
+ 
+    133.  
+\end{verbatim}
+A new variable has been created. Scilab knows its type \verb!133! which is 
+the first integer in the header, but Scilab is unable to display this variable.
+We can attach a generic name to the type 133, by doing the following:
+\begin{verbatim}
+-->typename('mytype', 133)
+\end{verbatim}
+The list of current names and types is obtained by the command 
+\verb![names,types]=typname()! . The command \verb!typeof(X)! now returns
+\verb!mytype!.
+Now we can overload a function to display \verb!X!.
+\begin{verbatim}
+-->function %mytype_p(X)
+-->disp('Cannot display this variable!')
+-->endfunction
+ 
+-->X
+ X  =
+ 
+Cannot display this variable!   
+\end{verbatim}
+Indeed, at this stage we have created a new type of variable, \verb!133! with
+name {\tt mytype}. To really display the variable, we need to write a new
+interface function.
+Let us consider the following:
+\begin{verbatim}
+#include "stack-c.h"
+void intdisp133() 
+{
+  int *header;
+  header = GetData(1);
+  header[0]=8; 
+  LhsVar(1)=1;
+}
+\end{verbatim}
+This function does nothing, except changing \verb!header[0]! from 133 to
+8.
+We can build a library with the two functions \verb!my133! and \verb!disp133!
+with the scilab script:
+\begin{verbatim}
+ilib_name  = 'lib133';
+files = ['intmy133.o', 'intdisp133.o'];
+libs  = [];
+table = ['my133', 'intmy133';
+         'disp133' ,'intdisp133'];
+ilib_build(ilib_name,table,files,libs);
+\end{verbatim}
 
+We can redefined the display function for variables tagged \verb!"mytype"!
+by \verb!typename!.
+\begin{verbatim}
+-->function %mytype_p(X)
+-->disp(disp133(X))
+-->endfunction
+ 
+-->X
+ X  =
+ 
+35
+\end{verbatim}
+When \verb!X! is typed at the scilab prompt, the function \verb!%mytype!
+is searched to display \verb!X!, since \verb!X! is a variable of type 133
+and such variables have the generic name "mytype", set by the command
+\verb!typename('mytype',133)!. The function \verb!disp133! transforms the
+variable X into a standard 1 x 1 integer matrix containing the constant 35.
+(Note that only the type needs to be set).
+
+\subsection{Values or references}
+By default, the arguments given to the interface are passed ``by value''.
+This means that, in the interface program, one is working with a copy
+of the Scilab data. Consider for instance the following gateway function:
+\begin{verbatim}
+#include "stack-c.h"
+void inttstfct() 
+{ int m1,n1,l1;
+  GetRhsVar(1, "d", &m1, &n1, &l1);
+  stk(l1)[0] = 1;
+  LhsVar(1) = 1;
+}
+\end{verbatim}
+for the Scilab function {\tt X=tstfct(A)}. We assume that the variable \verb!A!
+passed to \verb!tstfct! is a standard real matrix.
+Note that we could use the following gateway which performs the same job.
+\begin{verbatim}
+#include "stack-c.h"
+void inttstfct() 
+{ int *header; double *data;
+  header = (int *) GetData(1);
+  data = (double *) &header[4];  
+  data[0] = 1;
+  LhsVar(1) = 1;
+}
+\end{verbatim}
+This function is installed into Scilab by executing the script
+\begin{verbatim}
+ilib_name  = 'libinttstfct';
+files = ['inttstfct.o'];
+libs  = [];
+table = ['tstfct', 'inttstfct'];
+ilib_build(ilib_name,table,files,libs);
+\end{verbatim}
+and executing the newly created script \verb!loader.sce!.
+
+Assume also that \verb!A! is the 2 x 2 matrix \verb!A=zeros(2,2)!, 
+and consider the Scilab command \verb!-->B=tstfct(A)!. In the interface
+program, before its assignment, \verb!stk(l1)[0]! is equal to 0, i.e. the first
+entry of \verb!A!, {\tt A(1,1)}. 
+The output {\tt B} will be, as expected, the Scilab matrix \verb![1 0;0 0]!.
+But the Scilab variable {\tt A} will not be modified. This behavior is similar
+with the usual Scilab functions: the input parameters of the function are
+not modified when the  function is called.
+It is however possible to pass the parameters by reference. This can be useful
+if the interfaced program do not alter the input data (the data can be used
+in read-only mode).
+Let us enter the command \verb!-->funptr tstfct!. We get:
+\begin{verbatim}
+-->funptr tstfct
+ ans  =
+ 
+    50101.  
+\end{verbatim}
+which means: the function \verb!tstfct! has number \verb!01! in interface
+number \verb!501!.
+It is possible to convert the gateway function into a gateway in which the 
+variables are passed by reference. This is done as follows 
+by the function \verb!intppty!.
+\begin{verbatim}
+-->intppty(501) // adding gateway 501 to the list.
+ 
+-->intppty()   
+ ans  =
+ 
+!   6.    13.    16.    19.    21.    23.    41.    42.    501. !
+\end{verbatim}
+Note that if several Scilab functions are built together in the same
+inerface they will all receive input parameters as reference.
+The behavior of \verb!tstfct! is changed. Its argument is modified when
+\verb!tstfct! is called:
+\begin{verbatim}
+-->A
+ A  =
+ 
+!   0.    0. !
+!   0.    0. !
+-->tstfct(A)
+ ans  =
+ 
+!   1.    0. !
+!   0.    0. !
+-->A
+ A  =
+ 
+!   1.    0. !
+!   0.    0. !
+\end{verbatim}
+Finally, we note that the function {\tt GetRawData} gives the 
+internal representation of the reference variable and {\tt GetData}
+gives the internal representation of the value variable pointed to
+by the reference.
 \section{Intersci}
 The directory \verb!SCIDIR/examples/intersci-examples-so! contains
 several examples for using \verb!intersci! which is a tool for
@@ -774,7 +1131,6 @@ The file \verb!ex01fi.c! is the C gateway function needed for interfacing
 \scriptsize
 \begin{verbatim}
 #include "stack-c.h"
-
 int intsext1c(fname)
    char *fname;
 {
@@ -831,228 +1187,7 @@ To use \verb!intersci! one has to construct a \verb!.desc! file.
 The keywords which describe the Scilab function and the function
 to be called can be found in the examples given.
 
-\section{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{Mexfiles}
-The directories under \verb!SCIDIR/examples/mexfiles! contain 
-some examples of Matlab mexfiles which can be used as interfaces
-in the Scilab environment. The Scilab \verb!mexlib! library emulates
-the most commonly used Matlab \verb!mxfunctions! such as 
-\verb!mxGetM!, \verb!mxGetPr!, \verb!mxGetIr! etc. Not all the 
-\verb!mxfunctions! are available but standard mexfiles which make use
-of matrices (possibly sparse), character strings and n-dimensional arrays 
-can be used without any modification in the Scilab environment.
- 
-\section{Maple to Scilab Interface}
-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=call('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=call('fmat',x,1,'d',par,2,'d','out',[2,2],3,'d')
-\end{verbatim}
-}
 %\end{document}