6.4 The routines/default directory

The 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 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 Ex-fort.f contains a example of a subroutine (bidon2) which can be interactively called by the Scilab fort command. Thus, it is possible to call a C or Fortran routine by modifying the Ex-fort.f file, re-making Scilab and then using the fort function. The link operation now made outside Scilab by the make all command which creates a full new executable code for Scilab (SCIDIR/bin/scilex).

Let us consider again the example of the daxpy function. We want to call it from Scilab by the following function

function y=scilabdaxpy(a,x,incx,y,incy)
y=fort('daxpy1',a,x,incx,y,incy)

which performs the following:

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

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

Note that the fort function just sends the Scilab variables a,x,incx,y,incy to the interface program Ex-fort.f. These variables are associated with the numbers 1,2,3,4,5,6, respectively in the interface program Ex-fort.f. For our scilabdaxpy function, we perform the following steps:

• Add the name daxpy1 to the appropriate list of functions in the file Flist in the routines/default directory:

  interf_list= ... daxpy1
  

• Edit the file routines/default/Ex-fort.f and insert the following code:

   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
  

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

The statement n=msize(2,mx,nx) retrieves the dimensions mx, nx of variable # 2 i.e. x and 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 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:

 buf='error message'
 call error(9999)
 return

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

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

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

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