<?xml version="1.0" encoding="ISO-8859-1" standalone="no"?>
<!DOCTYPE MAN SYSTEM "../../manrev.dtd">
<MAN>
  <LANGUAGE>eng</LANGUAGE>
  <TITLE>link</TITLE>
  <TYPE>Scilab Function</TYPE>
  <DATE>Septembre 2005</DATE>
  <SHORT_DESCRIPTION name="link"> incremental linker </SHORT_DESCRIPTION>
  <CALLING_SEQUENCE>
    <CALLING_SEQUENCE_ITEM>x=link(files [, sub-names,flag]);  </CALLING_SEQUENCE_ITEM>
    <CALLING_SEQUENCE_ITEM>link(x , sub-names [, flag]);     </CALLING_SEQUENCE_ITEM>

    <CALLING_SEQUENCE_ITEM>ulink(x)  </CALLING_SEQUENCE_ITEM>
    <CALLING_SEQUENCE_ITEM>lst=link('show')  </CALLING_SEQUENCE_ITEM>
  </CALLING_SEQUENCE>
  
  <PARAM>
    <PARAM_INDENT>
      <PARAM_ITEM>
	<PARAM_NAME>files</PARAM_NAME>
	<PARAM_DESCRIPTION>
	  <SP>: a character string or a vector of character strings, the files
	    names used to define the new entry point (compiled routines, user
	    libraries, system libraries,..)</SP>
	</PARAM_DESCRIPTION>
      </PARAM_ITEM>

      <PARAM_ITEM>
	<PARAM_NAME>sub-names</PARAM_NAME>
	<PARAM_DESCRIPTION>
	  <SP>: a character string or a vector of character strings . Name of
	    the entry points in <VERB>files</VERB> to be linked.</SP> 
	</PARAM_DESCRIPTION>
      </PARAM_ITEM>
      <PARAM_ITEM>
	<PARAM_NAME>x</PARAM_NAME>
	<PARAM_DESCRIPTION>
	  <SP>: an integer which gives the id of a shared library linked into
	    Scilab with a previous call to <VERB>link</VERB>.</SP> 
	</PARAM_DESCRIPTION>
      </PARAM_ITEM>
      <PARAM_ITEM>
	<PARAM_NAME>flag</PARAM_NAME>
	<PARAM_DESCRIPTION>
	  <SP>: character string <VERB>'f'</VERB> or <VERB>'c'</VERB> for
	    Fortran (default) or C code.</SP> 
	</PARAM_DESCRIPTION>
      </PARAM_ITEM>
    </PARAM_INDENT>
  </PARAM>
  
  <DESCRIPTION>
  <P><VERB>link</VERB> is a incremental link facility based on the dld
      library: this command allows to add new compiled 
      Fortran or C routines to Scilab executable code.
      Linked routines can be called interactively by the function <VERB>fort</VERB>.
      Linked routines can also be used as &quot;external&quot; for e.g. 
      non linear problem solvers (<VERB>ode</VERB>, <VERB>optim</VERB>, <VERB>intg</VERB>, 
      <VERB>dassl</VERB>...). 
    </P>

    <P>a call to <VERB>link</VERB> returns an integer which gives the
	  id of the shared  library which is loaded into Scilab. This number
	  can then be used as the first argument of the link function in order
	  to link additional  function from the linked shared library. The
	  shared library is  removed with the <VERB>ulink</VERB> command.</P>
    <P>A routine  can be unlinked with
      <VERB>ulink</VERB>.  If the linked function has been
      modified between two links, it is required to <VERB>ulink</VERB> the previous instance
      before the new link.</P>

    <P><VERB>link('show')</VERB> returns the current linked routines.</P>

    <P> To be able to link routines in a system independent way, it is convenient
      to use the <VERB>ilib_for_link</VERB> utility function instead of <VERB>link</VERB>.</P>

    <P>(Experienced) users may also <VERB>link</VERB> a new Scilab interface routine 
      to add a set of new functions. See <LINK>intersci</LINK> documentation
      for interface generation and <LINK>ilib_build</LINK> and
      <LINK>addinter</LINK> functions.  </P>
  </DESCRIPTION>
  
  <EXAMPLE><![CDATA[
    //Example of the use of ilib_for_link with  a simple C code
    f1=['#include <math.h>'
    'void fooc(c,a,b,m,n)'
    'double a[],*b,c[];'
    'int *m,*n;'
    '{'
    '   int i;'
    '   for ( i =0 ; i < (*m)*(*n) ; i++) '
    '     c[i] = sin(a[i]) + *b; '
    '}'];

    mputl(f1,'fooc.c')

    //creating the shared library: a Makefile and a loader are 
    //generated, the code is compiled and a shared library built.
    ilib_for_link('fooc','fooc.o',[],"c") 

    // display the loader.sce file which calls link
    mprintf('%s\n',mgetl('loader.sce')) 
    // load the shared library 
    exec loader.sce 

    link('show') 
    // call the new linked entry point
    a=linspace(0,%pi,10);b=5;
    y1=call('fooc',a,2,'d',b,3,'d',size(a,1),4,'i',size(a,2),5,'i','out',size(a),1,'d')
    // check
    y1-(sin(a)+b)
    
    ]]></EXAMPLE>
  
  <SEE_ALSO>
    <SEE_ALSO_ITEM>
      <LINK>call</LINK>
    </SEE_ALSO_ITEM>
    <SEE_ALSO_ITEM>
      <LINK>external</LINK>
    </SEE_ALSO_ITEM>
    <SEE_ALSO_ITEM>
      <LINK>c_link</LINK>
    </SEE_ALSO_ITEM>
    <SEE_ALSO_ITEM>
      <LINK>addinter</LINK>
    </SEE_ALSO_ITEM>
    <SEE_ALSO_ITEM>
      <LINK>ilib_for_link</LINK>
    </SEE_ALSO_ITEM>
    <SEE_ALSO_ITEM>
      <LINK>ilib_build</LINK>
    </SEE_ALSO_ITEM>

  </SEE_ALSO>
  
</MAN>
