add more help pages related to CAPI - check parameters - optional parameters
Yann COLLETTE [Thu, 30 Apr 2009 16:24:50 +0000 (18:24 +0200)]
23 files changed:
scilab/modules/core/examples/capi/check_properties/builder.sce [new file with mode: 0644]
scilab/modules/core/examples/capi/check_properties/check_properties.c [new file with mode: 0644]
scilab/modules/core/examples/capi/check_properties/check_properties.sce [new file with mode: 0644]
scilab/modules/core/examples/capi/optional_parameters/builder.sce [new file with mode: 0644]
scilab/modules/core/examples/capi/optional_parameters/optional_parameters.c [new file with mode: 0644]
scilab/modules/core/examples/capi/optional_parameters/optional_parameters.sce [new file with mode: 0644]
scilab/modules/core/help/en_US/capi/CheckColumn.xml [new file with mode: 0644]
scilab/modules/core/help/en_US/capi/CheckDimProp.xml [new file with mode: 0644]
scilab/modules/core/help/en_US/capi/CheckDims.xml [new file with mode: 0644]
scilab/modules/core/help/en_US/capi/CheckLength.xml [new file with mode: 0644]
scilab/modules/core/help/en_US/capi/CheckRow.xml [new file with mode: 0644]
scilab/modules/core/help/en_US/capi/CheckSameDims.xml [new file with mode: 0644]
scilab/modules/core/help/en_US/capi/CheckScalar.xml [new file with mode: 0644]
scilab/modules/core/help/en_US/capi/CheckSquare.xml [new file with mode: 0644]
scilab/modules/core/help/en_US/capi/CheckVector.xml [new file with mode: 0644]
scilab/modules/core/help/en_US/capi/FindOpt.xml [new file with mode: 0644]
scilab/modules/core/help/en_US/capi/FirstOpt.xml [new file with mode: 0644]
scilab/modules/core/help/en_US/capi/HowToCheckParameters.xml [new file with mode: 0644]
scilab/modules/core/help/en_US/capi/HowToDealWithOptionalParameters.xml [new file with mode: 0644]
scilab/modules/core/help/en_US/capi/IsOpt.xml [new file with mode: 0644]
scilab/modules/core/help/en_US/capi/NumOpt.xml [new file with mode: 0644]
scilab/modules/core/help/en_US/capi/OverLoad.xml [new file with mode: 0644]
scilab/modules/core/help/en_US/capi/get_optionals.xml [new file with mode: 0644]

diff --git a/scilab/modules/core/examples/capi/check_properties/builder.sce b/scilab/modules/core/examples/capi/check_properties/builder.sce
new file mode 100644 (file)
index 0000000..ce9350e
--- /dev/null
@@ -0,0 +1,24 @@
+// This is the builder.sce 
+// must be run from this directory 
+
+lines(0);
+
+ilib_name  = 'lib_check_properties';
+
+files = ['check_properties.c'];
+
+libs  = [];
+
+table =['check_properties_1', 'sci_check_properties_1'; ...
+        'chprop2',            'sci_check_properties_2'];
+
+// We must be careful when we choose a scilab function name in case of overloading.
+// We Scilab name function must be 8 char max.
+
+ldflags = "";
+cflags  = "";
+fflags  = "";
+
+// do not modify below 
+// ----------------------------------------------
+ilib_build(ilib_name,table,files,libs,'Makelib',ldflags,cflags,fflags);
diff --git a/scilab/modules/core/examples/capi/check_properties/check_properties.c b/scilab/modules/core/examples/capi/check_properties/check_properties.c
new file mode 100644 (file)
index 0000000..40ea32d
--- /dev/null
@@ -0,0 +1,92 @@
+#include <stack-c.h>
+#include <sciprint.h>
+
+int sci_check_properties_1(char * fname)
+{
+  int m1, n1, l1;
+  int m2, n2, l2;
+  int m3, n3, l3;
+  int m4, n4, l4;
+  int m5, n5, l5;
+
+  CheckRhs(5,5);
+  CheckLhs(0,1) ;
+
+  ////////////////////////////
+  // Getting first argument //
+  ////////////////////////////
+
+  GetRhsVar(1, "d", &m1, &n1, &l1);
+
+  CheckVector(1,m1,n1);   // Check that first argument is a vector
+  CheckLength(1,m1*n1,4); // Check vector length
+  
+  /////////////////////////////
+  // Getting second argument //
+  /////////////////////////////
+
+  GetRhsVar(2, "d", &m2, &n2, &l2);
+
+  CheckRow(2,m2,n2); // Checks that second argument is a row vector
+                     // CheckColumn can also be used
+
+  CheckDimProp(1,2, m1 * n1 != n2); // Check compatibility beetween arg 1 and arg 2. We want m1*n1 == n2 
+
+  ////////////////////////////
+  // Getting third argument //
+  ////////////////////////////
+
+  GetRhsVar(3, "d", &m3, &n3, &l3);
+
+  CheckSameDims(1,3,m1,n1,m3,n3); // Checks that arg 1 and arg3 have same dimensions
+
+  /////////////////////////////
+  // Getting fourth argument //
+  /////////////////////////////
+
+  GetRhsVar(4,"d",&m4,&n4,&l4);
+  
+  CheckScalar(4,m4,n4); // arg 4 must be scalar
+
+  /////////////////////////////
+  // Getting fourth argument //
+  /////////////////////////////
+
+  GetRhsVar(5,"d",&m5,&n5,&l5);
+  
+  CheckSquare(5,m5,n5);   // square matrix
+  CheckDims(5,m5,m5,5,5); // check dimensions
+
+  LhsVar(1)=0;
+
+  return 0;
+}
+
+// We must be careful on the scilab name function (8 chars max).
+
+int sci_check_properties_2(char * fname)
+{
+  int m1,n1,l1;
+
+  CheckRhs(1,1);
+  CheckLhs(0,1) ;
+
+  switch(VarType(1)) 
+    {
+    case 1: 
+      GetRhsVar(1, "d", &m1, &n1, &l1);
+      sciprint("1 is a scalar matrix\n");
+      break;
+    case 10:
+      GetRhsVar(1, "c", &m1, &n1, &l1);
+      sciprint("1 is a string\n");
+      break;
+    case 5:
+      sciprint("1 is a sparse trying to overload\n");
+      OverLoad(1);
+    }
+
+  LhsVar(1) = 0;
+
+  return 0;
+}
diff --git a/scilab/modules/core/examples/capi/check_properties/check_properties.sce b/scilab/modules/core/examples/capi/check_properties/check_properties.sce
new file mode 100644 (file)
index 0000000..fd4f492
--- /dev/null
@@ -0,0 +1,45 @@
+// checks arguments compatibility 
+
+check_properties_1([1;2;3;4],[3,4,5,6],[6;7;8;9],90,rand(5,5))
+
+// first argument can have different types 
+
+chprop2([1,2,2]);
+chprop2('foo');
+
+// overload case 
+
+deff('[]=%sp_chprop2(sp)','disp(''sparse overloaded'')');
+chprop2(sparse([1,2,3]));
+
+// tests which give an error message with check_properties_1
+
+try
+  check_properties_1([1;2;3;4]',[3,4,5,6],[6;7;8;9],90,rand(5,5))
+catch
+  disp(lasterror());
+end
+
+try
+  check_properties_1([1;2;3;4],[3,4,5,6]',[6;7;8;9],90,rand(5,5))
+catch
+  disp(lasterror());
+end
+
+try
+  check_properties_1([1;2;3;4],[3,4,5,6],[6;7;8;9]',90,rand(5,5))
+catch
+  disp(lasterror());
+end
+
+try
+  check_properties_1([1;2;3;4],[3,4,5,6],[6;7;8;9],[],rand(5,5))
+catch
+  disp(lasterror());
+end
+
+try
+  check_properties_1([1;2;3;4],[3,4,5,6],[6;7;8;9],90,rand(4,4))
+catch
+  disp(lasterror());
+end
diff --git a/scilab/modules/core/examples/capi/optional_parameters/builder.sce b/scilab/modules/core/examples/capi/optional_parameters/builder.sce
new file mode 100644 (file)
index 0000000..8dd1414
--- /dev/null
@@ -0,0 +1,20 @@
+// This is the builder.sce 
+// must be run from this directory 
+
+lines(0);
+
+ilib_name  = 'lib_optional_parameters';
+
+files = ['optional_parameters.c'];
+
+libs  = [];
+
+table =['optional_parameters', 'sci_optional_parameters'];
+
+ldflags = "";
+cflags  = "";
+fflags  = "";
+
+// do not modify below 
+// ----------------------------------------------
+ilib_build(ilib_name,table,files,libs,'Makelib',ldflags,cflags,fflags);
diff --git a/scilab/modules/core/examples/capi/optional_parameters/optional_parameters.c b/scilab/modules/core/examples/capi/optional_parameters/optional_parameters.c
new file mode 100644 (file)
index 0000000..0737835
--- /dev/null
@@ -0,0 +1,85 @@
+#include <stack-c.h>
+
+int ex2c(double * a, int * ma, int * na,
+        double * b, int * mb, int * nb) 
+{
+  int i;
+
+  for(i=0;i<(*ma)*(*na);i++) a[i] = 2*a[i];
+  for(i=0;i<(*mb)*(*nb);i++) b[i] = 3*b[i];
+
+  return(0);
+}
+
+int sci_optional_parameters(char * fname)
+{ 
+  int m1,n1,l1;
+
+  // optional names must be stored in alphabetical order in opts
+  static rhs_opts opts[]= {{-1,"v1","d",0,0,0},
+                          {-1,"v2","d",0,0,0},
+                          {-1,NULL,NULL,0,0}};
+
+  int minrhs = 1, maxrhs = 1;
+  int minlhs = 1, maxlhs = 3;
+  int nopt, iopos, res;
+  char buffer_name[csiz]; // csiz used for character coding
+
+  nopt = NumOpt();
+
+  CheckRhs(minrhs,maxrhs+nopt);
+  CheckLhs(minlhs,maxlhs);
+
+  // first non optional argument
+  GetRhsVar( 1, "c", &m1, &n1, &l1);
+  
+  if (get_optionals(fname,opts)==0) return 0;
+
+  // default values if optional arguments are not given:  v1=[99] and v2=[3]
+
+  sciprint("number of optional parameters = %d\n", NumOpt());
+  sciprint("first optional parameters = %d\n", FirstOpt());
+  sciprint("FindOpt(v1) = %d\n", FindOpt("v1", opts));
+  sciprint("FindOpt(v2) = %d\n", FindOpt("v2", opts));
+
+  if (IsOpt(1,buffer_name))
+    sciprint("parameter 1 is optional: %s\n", buffer_name);
+  if (IsOpt(2,buffer_name))
+    sciprint("parameter 2 is optional: %s\n", buffer_name);
+  if (IsOpt(3,buffer_name))
+    sciprint("parameter 3 is optional: %s\n", buffer_name);
+
+  iopos = Rhs;
+
+  if (opts[0].position==-1)
+    {
+      iopos++;
+      opts[0].position = iopos;
+      opts[0].m = 1; opts[0].n = 1; 
+      opts[0].type = "d";
+      CreateVar(opts[0].position, opts[0].type, &opts[0].m, &opts[0].n, &opts[0].l);
+      *stk(opts[0].l) = 99.0;
+    }
+
+  if (opts[1].position==-1) 
+    {
+      iopos++ ; 
+      opts[1].position = iopos;
+      opts[1].m = 1; opts[1].n = 1;
+      opts[1].type = "d";
+      CreateVar(opts[1].position, opts[1].type, &opts[1].m, &opts[1].n, &opts[1].l);
+      *stk(opts[1].l) = 3;
+    }
+
+  ex2c(stk(opts[0].l),&opts[0].m,&opts[0].n,
+       stk(opts[1].l),&opts[1].m,&opts[1].n);
+
+  // return the first argument (unchanged ) then v1 and v2
+
+  LhsVar(1) = 1;
+  LhsVar(2) = opts[0].position;
+  LhsVar(3) = opts[1].position;
+
+  return 0;
+}
+
diff --git a/scilab/modules/core/examples/capi/optional_parameters/optional_parameters.sce b/scilab/modules/core/examples/capi/optional_parameters/optional_parameters.sce
new file mode 100644 (file)
index 0000000..c9510b4
--- /dev/null
@@ -0,0 +1,17 @@
+// Example with optional argument specified with the 'arg=value syntax'
+// [a,b,c] = ex12c(x1, [v1 = arg1, v2 = arg2]), arg1 default value 99
+//                                             arg2 default value 3
+// only v1 and v2 are recognized as optional argument names 
+// the return value are a = x1, b = 2*v2, c = 3*v2 
+
+[a,b,c] = optional_parameters('test');
+disp('a = ' + a + ' b = ' + string(b) + ' c = ' + string(c));
+
+[a,b,c] = optional_parameters('test',v1=[10,20]);
+disp('a = ' + a + ' b = ' + string(b) + ' c = ' + string(c));
+
+[a,b,c] = optional_parameters('test',v1=[10,20],v2=8);
+disp('a = ' + a + ' b = ' + string(b) + ' c = ' + string(c));
+
+[a,b,c] = optional_parameters('test',v2=8,v1=[10]);
+disp('a = ' + a + ' b = ' + string(b) + ' c = ' + string(c));
diff --git a/scilab/modules/core/help/en_US/capi/CheckColumn.xml b/scilab/modules/core/help/en_US/capi/CheckColumn.xml
new file mode 100644 (file)
index 0000000..689ee28
--- /dev/null
@@ -0,0 +1,106 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<refentry version="5.0-subset Scilab" xml:id="CheckColumn" xml:lang="en"
+          xmlns="http://docbook.org/ns/docbook"
+          xmlns:xlink="http://www.w3.org/1999/xlink"
+          xmlns:svg="http://www.w3.org/2000/svg"
+          xmlns:mml="http://www.w3.org/1998/Math/MathML"
+          xmlns:html="http://www.w3.org/1999/xhtml"
+          xmlns:db="http://docbook.org/ns/docbook">
+  <refnamediv>
+    <refname>CheckColumn</refname>
+
+    <refpurpose>C interface function which checks if a parameter send to the C
+    function is a column vector or not</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <title>Calling Sequence</title>
+
+    <synopsis>CheckColumn(StackPos,m_var,n_var)</synopsis>
+  </refsynopsisdiv>
+
+  <refsection>
+    <title>Parameters</title>
+
+    <variablelist>
+      <varlistentry>
+        <term>StackPos</term>
+
+        <listitem>
+          <para>the position on the stack of the variable for which we want to
+          perform the check (input parameter)</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>m_var</term>
+
+        <listitem>
+          <para>the number of lines of the parameter at position StackPos on
+          the stack</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>n_var</term>
+
+        <listitem>
+          <para>the number of columns of the parameter at position StackPos on
+          the stack</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+  </refsection>
+
+  <refsection>
+    <title>Description</title>
+
+    <para>C interface function which checks if a parameter send to the C
+    function is a column vector or not. You must include stack-c.h to benefit
+    from this function.</para>
+  </refsection>
+
+  <refsection>
+    <title>Examples</title>
+
+    <para>In this example, the C interface function takes one input parameters
+    and prints the integer corresponding to the type of the variable sent as
+    parameter in the Scilab console. If the test fails, we return from the C
+    interface and an adequate error message is printed in the Scilab
+    console.</para>
+
+    <programlisting role="example"> 
+#include &lt;stack-c.h&gt;
+
+int sci_check_properties(char * fname)
+{
+  int m1, n1, l1;
+
+  CheckRhs(1,1);
+
+  GetRhsVar(1, "d", &amp;m1, &amp;n1, &amp;l1);
+
+  CheckColumn(1,m1,n1); // Check that first argument is a column vector
+
+  return 0;
+}
+ </programlisting>
+  </refsection>
+
+  <refsection>
+    <title>See Also</title>
+
+    <simplelist type="inline">
+      <member><link linkend="CheckDims">CheckDims</link></member>
+      <member><link linkend="CheckRow">CheckRow</link></member>
+      <member><link linkend="CheckScalar">CheckScalar</link></member>
+      <member><link linkend="CheckVector">CheckVector</link></member>
+      <member><link linkend="OverLoad">CheckOverLoad</link></member>
+      <member><link linkend="CheckDimProp">CheckDimProp</link></member>
+      <member><link linkend="CheckLength">CheckLength</link></member>
+      <member><link linkend="CheckSameDims">CheckSameDims</link></member>
+      <member><link linkend="CheckSquare">CheckSquare</link></member>
+      <member><link linkend="How to check parameters">HowToCheckParameters</link></member>
+    </simplelist>
+  </refsection>
+</refentry>
diff --git a/scilab/modules/core/help/en_US/capi/CheckDimProp.xml b/scilab/modules/core/help/en_US/capi/CheckDimProp.xml
new file mode 100644 (file)
index 0000000..4762c64
--- /dev/null
@@ -0,0 +1,104 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<refentry version="5.0-subset Scilab" xml:id="CheckDimProp" xml:lang="en"
+          xmlns="http://docbook.org/ns/docbook"
+          xmlns:xlink="http://www.w3.org/1999/xlink"
+          xmlns:svg="http://www.w3.org/2000/svg"
+          xmlns:mml="http://www.w3.org/1998/Math/MathML"
+          xmlns:html="http://www.w3.org/1999/xhtml"
+          xmlns:db="http://docbook.org/ns/docbook">
+  <refnamediv>
+    <refname>CheckDimProp</refname>
+
+    <refpurpose>C interface function which checks the comatibility between 2
+    arguments send to the C function</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <title>Calling Sequence</title>
+
+    <synopsis>CheckColumn(StackPos_var1,StackPos_var2,expression)</synopsis>
+  </refsynopsisdiv>
+
+  <refsection>
+    <title>Parameters</title>
+
+    <variablelist>
+      <varlistentry>
+        <term>StackPos_var1</term>
+
+        <listitem>
+          <para>the position on the stack of the first variable for which we
+          want to perform the check (input parameter)</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>StackPos_var2</term>
+
+        <listitem>
+          <para>the position on the stack of the second variable for which we
+          want to perform the check (input parameter)</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>expression</term>
+
+        <listitem>
+          <para>a boolean expression which represent the size check we want to
+          perform</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+  </refsection>
+
+  <refsection>
+    <title>Description</title>
+
+    <para>C interface function which checks the comatibility between 2
+    arguments send to the C function. You must include stack-c.h to benefit
+    from this function. If the test fails, we return from the C interface and
+    an adequate error message is printed in the Scilab console.</para>
+  </refsection>
+
+  <refsection>
+    <title>Examples</title>
+
+    <programlisting role="example"> 
+#include &lt;stack-c.h&gt;
+
+int sci_check_properties(char * fname)
+{
+  int m1, n1, l1;
+  int m2, n2, l2;
+
+  CheckRhs(2,2);
+
+  GetRhsVar(1, "d", &amp;m1, &amp;n1, &amp;l1);
+  GetRhsVar(2, "d", &amp;m2, &amp;n2, &amp;l2);
+
+  // Check compatibility beetween arg 1 and arg 2. We want m1*n1 == n2 
+  CheckDimProp(1,2, m1 * n1 != n2); 
+
+  return 0;
+}
+ </programlisting>
+  </refsection>
+
+  <refsection>
+    <title>See Also</title>
+
+    <simplelist type="inline">
+      <member><link linkend="CheckColumn">CheckColumn</link></member>
+      <member><link linkend="CheckDims">CheckDims</link></member>
+      <member><link linkend="CheckRow">CheckRow</link></member>
+      <member><link linkend="CheckScalar">CheckScalar</link></member>
+      <member><link linkend="CheckVector">CheckVector</link></member>
+      <member><link linkend="OverLoad">CheckOverLoad</link></member>
+      <member><link linkend="CheckLength">CheckLength</link></member>
+      <member><link linkend="CheckSameDims">CheckSameDims</link></member>
+      <member><link linkend="CheckSquare">CheckSquare</link></member>
+      <member><link linkend="How to check parameters">HowToCheckParameters</link></member>
+    </simplelist>
+  </refsection>
+</refentry>
diff --git a/scilab/modules/core/help/en_US/capi/CheckDims.xml b/scilab/modules/core/help/en_US/capi/CheckDims.xml
new file mode 100644 (file)
index 0000000..6505d63
--- /dev/null
@@ -0,0 +1,118 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<refentry version="5.0-subset Scilab" xml:id="CheckColumn" xml:lang="en"
+          xmlns="http://docbook.org/ns/docbook"
+          xmlns:xlink="http://www.w3.org/1999/xlink"
+          xmlns:svg="http://www.w3.org/2000/svg"
+          xmlns:mml="http://www.w3.org/1998/Math/MathML"
+          xmlns:html="http://www.w3.org/1999/xhtml"
+          xmlns:db="http://docbook.org/ns/docbook">
+  <refnamediv>
+    <refname>CheckDims</refname>
+
+    <refpurpose>C interface function which checks if a parameter send to the C
+    function has the required dimensions</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <title>Calling Sequence</title>
+
+    <synopsis>CheckDims(StackPos,m_var,n_var,m_required,n_required)</synopsis>
+  </refsynopsisdiv>
+
+  <refsection>
+    <title>Parameters</title>
+
+    <variablelist>
+      <varlistentry>
+        <term>StackPos</term>
+
+        <listitem>
+          <para>the position on the stack of the variable for which we want to
+          know the type (input parameter)</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>m_var</term>
+
+        <listitem>
+          <para>the number of lines of the parameter at position StackPos on
+          the stack (input parameter)</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>n_var</term>
+
+        <listitem>
+          <para>the number of columns of the parameter at position StackPos on
+          the stack (input parameter)</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>m_required</term>
+
+        <listitem>
+          <para>the required number of lines (input parameter)</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>n_required</term>
+
+        <listitem>
+          <para>the required number of columns (input parameter)</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+  </refsection>
+
+  <refsection>
+    <title>Description</title>
+
+    <para>C interface function which checks if a parameter send to the C
+    function has the required dimensions. You must include stack-c.h to
+    benefit from this function. If the test fails, we return from the C
+    interface and an adequate error message is printed in the Scilab
+    console.</para>
+  </refsection>
+
+  <refsection>
+    <title>Examples</title>
+
+    <programlisting role="example"> 
+#include &lt;stack-c.h&gt;
+
+int sci_check_properties(char * fname)
+{
+  int m1, n1, l1;
+
+  CheckRhs(1,1);
+
+  GetRhsVar(1, "d", &amp;m1, &amp;n1, &amp;l1);
+
+  CheckDims(1,m1,n1,1,4); // Check that argument is a 1x4 matrix
+
+  return 0;
+}
+ </programlisting>
+  </refsection>
+
+  <refsection>
+    <title>See Also</title>
+
+    <simplelist type="inline">
+      <member><link linkend="CheckColumn">CheckColumn</link></member>
+      <member><link linkend="CheckRow">CheckRow</link></member>
+      <member><link linkend="CheckScalar">CheckScalar</link></member>
+      <member><link linkend="CheckVector">CheckVector</link></member>
+      <member><link linkend="OverLoad">CheckOverLoad</link></member>
+      <member><link linkend="CheckDimProp">CheckDimProp</link></member>
+      <member><link linkend="CheckLength">CheckLength</link></member>
+      <member><link linkend="CheckSameDims">CheckSameDims</link></member>
+      <member><link linkend="CheckSquare">CheckSquare</link></member>
+      <member><link linkend="How to check parameters">HowToCheckParameters</link></member>
+    </simplelist>
+  </refsection>
+</refentry>
diff --git a/scilab/modules/core/help/en_US/capi/CheckLength.xml b/scilab/modules/core/help/en_US/capi/CheckLength.xml
new file mode 100644 (file)
index 0000000..962db4d
--- /dev/null
@@ -0,0 +1,100 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<refentry version="5.0-subset Scilab" xml:id="CheckLength" xml:lang="en"
+          xmlns="http://docbook.org/ns/docbook"
+          xmlns:xlink="http://www.w3.org/1999/xlink"
+          xmlns:svg="http://www.w3.org/2000/svg"
+          xmlns:mml="http://www.w3.org/1998/Math/MathML"
+          xmlns:html="http://www.w3.org/1999/xhtml"
+          xmlns:db="http://docbook.org/ns/docbook">
+  <refnamediv>
+    <refname>CheckLength</refname>
+
+    <refpurpose>C interface function which checks the length of a vector send
+    as a parameter to the C function</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <title>Calling Sequence</title>
+
+    <synopsis>CheckLength(StackPos,m_var,m_required)</synopsis>
+  </refsynopsisdiv>
+
+  <refsection>
+    <title>Parameters</title>
+
+    <variablelist>
+      <varlistentry>
+        <term>StackPos</term>
+
+        <listitem>
+          <para>the position on the stack of the variable for we want to check
+          (input parameter)</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>m_var</term>
+
+        <listitem>
+          <para>the number of lines of the parameter at position StackPos on
+          the stack (input parameter)</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>m_required</term>
+
+        <listitem>
+          <para>the required number of lines (input parameter)</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+  </refsection>
+
+  <refsection>
+    <title>Description</title>
+
+    <para>C interface function which checks the length of a vector send as a
+    parameter to the C function. You must include stack-c.h to benefit from
+    this function. If the test fails, we return from the C interface and an
+    adequate error message is printed in the Scilab console.</para>
+  </refsection>
+
+  <refsection>
+    <title>Examples</title>
+
+    <programlisting role="example"> 
+#include &lt;stack-c.h&gt;
+
+int sci_check_properties(char * fname)
+{
+  int m1, n1, l1;
+
+  CheckRhs(1,1);
+
+  GetRhsVar(1, "d", &amp;m1, &amp;n1, &amp;l1);
+
+  CheckLength(1,m1*n1,4); // Check that vector has 4 elements
+
+  return 0;
+}
+ </programlisting>
+  </refsection>
+
+  <refsection>
+    <title>See Also</title>
+
+    <simplelist type="inline">
+      <member><link linkend="CheckColumn">CheckColumn</link></member>
+      <member><link linkend="CheckDims">CheckDims</link></member>
+      <member><link linkend="CheckRow">CheckRow</link></member>
+      <member><link linkend="CheckScalar">CheckScalar</link></member>
+      <member><link linkend="CheckVector">CheckVector</link></member>
+      <member><link linkend="OverLoad">CheckOverLoad</link></member>
+      <member><link linkend="CheckDimProp">CheckDimProp</link></member>
+      <member><link linkend="CheckSameDims">CheckSameDims</link></member>
+      <member><link linkend="CheckSquare">CheckSquare</link></member>
+      <member><link linkend="How to check parameters">HowToCheckParameters</link></member>
+    </simplelist>
+  </refsection>
+</refentry>
diff --git a/scilab/modules/core/help/en_US/capi/CheckRow.xml b/scilab/modules/core/help/en_US/capi/CheckRow.xml
new file mode 100644 (file)
index 0000000..6b74873
--- /dev/null
@@ -0,0 +1,101 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<refentry version="5.0-subset Scilab" xml:id="CheckRow" xml:lang="en"
+          xmlns="http://docbook.org/ns/docbook"
+          xmlns:xlink="http://www.w3.org/1999/xlink"
+          xmlns:svg="http://www.w3.org/2000/svg"
+          xmlns:mml="http://www.w3.org/1998/Math/MathML"
+          xmlns:html="http://www.w3.org/1999/xhtml"
+          xmlns:db="http://docbook.org/ns/docbook">
+  <refnamediv>
+    <refname>CheckRow</refname>
+
+    <refpurpose>C interface function which checks if a parameter send to the C
+    function is a row vector or not</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <title>Calling Sequence</title>
+
+    <synopsis>CheckRow(StackPos,m_var,n_var)</synopsis>
+  </refsynopsisdiv>
+
+  <refsection>
+    <title>Parameters</title>
+
+    <variablelist>
+      <varlistentry>
+        <term>StackPos</term>
+
+        <listitem>
+          <para>the position on the stack of the variable for which we want to
+          know the type (input parameter)</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>m_var</term>
+
+        <listitem>
+          <para>the number of lines of the parameter at position StackPos on
+          the stack</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>n_var</term>
+
+        <listitem>
+          <para>the number of columns of the parameter at position StackPos on
+          the stack</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+  </refsection>
+
+  <refsection>
+    <title>Description</title>
+
+    <para>C interface function which checks if a parameter send to the C
+    function is a row vector or not. You must include stack-c.h to benefit
+    from this function. If the test fails, we return from the C interface and
+    an adequate error message is printed in the Scilab console.</para>
+  </refsection>
+
+  <refsection>
+    <title>Examples</title>
+
+    <programlisting role="example"> 
+#include &lt;stack-c.h&gt;
+
+int sci_check_properties(char * fname)
+{
+  int m1, n1, l1;
+
+  CheckRhs(1,1);
+
+  GetRhsVar(1, "d", &amp;m1, &amp;n1, &amp;l1);
+
+  CheckRow(1,m1,n1); // Check that first argument is a row vector
+
+  return 0;
+}
+ </programlisting>
+  </refsection>
+
+  <refsection>
+    <title>See Also</title>
+
+    <simplelist type="inline">
+      <member><link linkend="CheckColumn">CheckColumn</link></member>
+      <member><link linkend="CheckDims">CheckDims</link></member>
+      <member><link linkend="CheckScalar">CheckScalar</link></member>
+      <member><link linkend="CheckVector">CheckVector</link></member>
+      <member><link linkend="OverLoad">CheckOverLoad</link></member>
+      <member><link linkend="CheckDimProp">CheckDimProp</link></member>
+      <member><link linkend="CheckLength">CheckLength</link></member>
+      <member><link linkend="CheckSameDims">CheckSameDims</link></member>
+      <member><link linkend="CheckSquare">CheckSquare</link></member>
+      <member><link linkend="How to check parameters">HowToCheckParameters</link></member>
+    </simplelist>
+  </refsection>
+</refentry>
diff --git a/scilab/modules/core/help/en_US/capi/CheckSameDims.xml b/scilab/modules/core/help/en_US/capi/CheckSameDims.xml
new file mode 100644 (file)
index 0000000..a031120
--- /dev/null
@@ -0,0 +1,134 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<refentry version="5.0-subset Scilab" xml:id="CheckSameDims" xml:lang="en"
+          xmlns="http://docbook.org/ns/docbook"
+          xmlns:xlink="http://www.w3.org/1999/xlink"
+          xmlns:svg="http://www.w3.org/2000/svg"
+          xmlns:mml="http://www.w3.org/1998/Math/MathML"
+          xmlns:html="http://www.w3.org/1999/xhtml"
+          xmlns:db="http://docbook.org/ns/docbook">
+  <refnamediv>
+    <refname>CheckSameDims</refname>
+
+    <refpurpose>C interface function which checks if two parameters send to
+    the C function have the same size</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <title>Calling Sequence</title>
+
+    <synopsis>CheckSameDims(StackPos_var1,StackPos_var2,m_var1,n_var1,m_var2,n_var2)</synopsis>
+  </refsynopsisdiv>
+
+  <refsection>
+    <title>Parameters</title>
+
+    <variablelist>
+      <varlistentry>
+        <term>StackPos_var1</term>
+
+        <listitem>
+          <para>the position on the stack of the first variable for which we
+          want to perform the check (input parameter)</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>StackPos_var2</term>
+
+        <listitem>
+          <para>the position on the stack of the second variable for which we
+          want to perform the check (input parameter)</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>m_var1</term>
+
+        <listitem>
+          <para>the number of lines of the parameter at position StackPos_var1
+          on the stack</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>n_var1</term>
+
+        <listitem>
+          <para>the number of columns of the parameter at position
+          StackPos_var1 on the stack</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>m_var2</term>
+
+        <listitem>
+          <para>the number of lines of the parameter at position StackPos_var2
+          on the stack</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>n_var2</term>
+
+        <listitem>
+          <para>the number of columns of the parameter at position
+          StackPos_var2 on the stack</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+  </refsection>
+
+  <refsection>
+    <title>Description</title>
+
+    <para>C interface function which checks if two parameters send to the C
+    function have the same size. You must include stack-c.h to benefit from
+    this function. If the test fails, we return from the C interface and an
+    adequate error message is printed in the Scilab console.</para>
+  </refsection>
+
+  <refsection>
+    <title>Examples</title>
+
+    <para>In this example, the C interface function takes one input parameters
+    and prints the integer corresponding to the type of the variable sent as
+    parameter in the Scilab console.</para>
+
+    <programlisting role="example"> 
+#include &lt;stack-c.h&gt;
+
+int sci_check_properties(char * fname)
+{
+  int m1, n1, l1;
+  int m2, n2, l2;
+
+  CheckRhs(2,2);
+
+  GetRhsVar(1, "d", &amp;m1, &amp;n1, &amp;l1);
+  GetRhsVar(2, "d", &amp;m2, &amp;n2, &amp;l2);
+
+  CheckSameDims(1,2,m1,n1,m2,n2); // Check that both vectors have the same size
+
+  return 0;
+}
+ </programlisting>
+  </refsection>
+
+  <refsection>
+    <title>See Also</title>
+
+    <simplelist type="inline">
+      <member><link linkend="CheckColumn">CheckColumn</link></member>
+      <member><link linkend="CheckDims">CheckDims</link></member>
+      <member><link linkend="CheckRow">CheckRow</link></member>
+      <member><link linkend="CheckScalar">CheckScalar</link></member>
+      <member><link linkend="CheckVector">CheckVector</link></member>
+      <member><link linkend="OverLoad">CheckOverLoad</link></member>
+      <member><link linkend="CheckDimProp">CheckDimProp</link></member>
+      <member><link linkend="CheckLength">CheckLength</link></member>
+      <member><link linkend="CheckSquare">CheckSquare</link></member>
+      <member><link linkend="How to check parameters">HowToCheckParameters</link></member>
+    </simplelist>
+  </refsection>
+</refentry>
diff --git a/scilab/modules/core/help/en_US/capi/CheckScalar.xml b/scilab/modules/core/help/en_US/capi/CheckScalar.xml
new file mode 100644 (file)
index 0000000..b6b5f8b
--- /dev/null
@@ -0,0 +1,106 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<refentry version="5.0-subset Scilab" xml:id="CheckScalar" xml:lang="en"
+          xmlns="http://docbook.org/ns/docbook"
+          xmlns:xlink="http://www.w3.org/1999/xlink"
+          xmlns:svg="http://www.w3.org/2000/svg"
+          xmlns:mml="http://www.w3.org/1998/Math/MathML"
+          xmlns:html="http://www.w3.org/1999/xhtml"
+          xmlns:db="http://docbook.org/ns/docbook">
+  <refnamediv>
+    <refname>CheckScalar</refname>
+
+    <refpurpose>C interface function which checks if a parameter send to the C
+    function is a scalar or not</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <title>Calling Sequence</title>
+
+    <synopsis>CheckScalar(StackPos,m_var,n_var)</synopsis>
+  </refsynopsisdiv>
+
+  <refsection>
+    <title>Parameters</title>
+
+    <variablelist>
+      <varlistentry>
+        <term>StackPos</term>
+
+        <listitem>
+          <para>the position on the stack of the variable for which we want to
+          perform the check (input parameter)</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>m_var</term>
+
+        <listitem>
+          <para>the number of lines of the parameter at position StackPos on
+          the stack</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>n_var</term>
+
+        <listitem>
+          <para>the number of columns of the parameter at position StackPos on
+          the stack</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+  </refsection>
+
+  <refsection>
+    <title>Description</title>
+
+    <para>C interface function which checks if a parameter send to the C
+    function is a scalar or not. You must include stack-c.h to benefit from
+    this function.</para>
+  </refsection>
+
+  <refsection>
+    <title>Examples</title>
+
+    <para>In this example, the C interface function takes one input parameters
+    and prints the integer corresponding to the type of the variable sent as
+    parameter in the Scilab console. If the test fails, we return from the C
+    interface and an adequate error message is printed in the Scilab
+    console.</para>
+
+    <programlisting role="example"> 
+#include &lt;stack-c.h&gt;
+
+int sci_check_properties(char * fname)
+{
+  int m1, n1, l1;
+
+  CheckRhs(1,1);
+
+  GetRhsVar(1, "d", &amp;m1, &amp;n1, &amp;l1);
+
+  CheckScalar(1,m1,n1); // Check that first argument is a scalar
+
+  return 0;
+}
+ </programlisting>
+  </refsection>
+
+  <refsection>
+    <title>See Also</title>
+
+    <simplelist type="inline">
+      <member><link linkend="CheckColumn">CheckColumn</link></member>
+      <member><link linkend="CheckDims">CheckDims</link></member>
+      <member><link linkend="CheckRow">CheckRow</link></member>
+      <member><link linkend="CheckVector">CheckVector</link></member>
+      <member><link linkend="OverLoad">CheckOverLoad</link></member>
+      <member><link linkend="CheckDimProp">CheckDimProp</link></member>
+      <member><link linkend="CheckLength">CheckLength</link></member>
+      <member><link linkend="CheckSameDims">CheckSameDims</link></member>
+      <member><link linkend="CheckSquare">CheckSquare</link></member>
+      <member><link linkend="How to check parameters">HowToCheckParameters</link></member>
+    </simplelist>
+  </refsection>
+</refentry>
diff --git a/scilab/modules/core/help/en_US/capi/CheckSquare.xml b/scilab/modules/core/help/en_US/capi/CheckSquare.xml
new file mode 100644 (file)
index 0000000..744b279
--- /dev/null
@@ -0,0 +1,101 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<refentry version="5.0-subset Scilab" xml:id="CheckSquare" xml:lang="en"
+          xmlns="http://docbook.org/ns/docbook"
+          xmlns:xlink="http://www.w3.org/1999/xlink"
+          xmlns:svg="http://www.w3.org/2000/svg"
+          xmlns:mml="http://www.w3.org/1998/Math/MathML"
+          xmlns:html="http://www.w3.org/1999/xhtml"
+          xmlns:db="http://docbook.org/ns/docbook">
+  <refnamediv>
+    <refname>CheckSquare</refname>
+
+    <refpurpose>C interface function which checks if a parameter send to the C
+    function is a square matrix or not</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <title>Calling Sequence</title>
+
+    <synopsis>CheckSquare(StackPos,m_var,n_var)</synopsis>
+  </refsynopsisdiv>
+
+  <refsection>
+    <title>Parameters</title>
+
+    <variablelist>
+      <varlistentry>
+        <term>StackPos</term>
+
+        <listitem>
+          <para>the position on the stack of the variable for which we want to
+          perform the check (input parameter)</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>m_var</term>
+
+        <listitem>
+          <para>the number of lines of the parameter at position StackPos on
+          the stack</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>n_var</term>
+
+        <listitem>
+          <para>the number of columns of the parameter at position StackPos on
+          the stack</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+  </refsection>
+
+  <refsection>
+    <title>Description</title>
+
+    <para>C interface function which checks if a parameter send to the C
+    function is a square matrix or not. You must include stack-c.h to benefit
+    from this function. If the test fails, we return from the C interface and
+    an adequate error message is printed in the Scilab console.</para>
+  </refsection>
+
+  <refsection>
+    <title>Examples</title>
+
+    <programlisting role="example"> 
+#include &lt;stack-c.h&gt;
+
+int sci_check_properties(char * fname)
+{
+  int m1, n1, l1;
+
+  CheckRhs(1,1);
+
+  GetRhsVar(1, "d", &amp;m1, &amp;n1, &amp;l1);
+
+  CheckSquare(1,m1,n1); // Check that first argument is a square matrix
+
+  return 0;
+}
+ </programlisting>
+  </refsection>
+
+  <refsection>
+    <title>See Also</title>
+
+    <simplelist type="inline">
+      <member><link linkend="CheckColumn">CheckColumn</link></member>
+      <member><link linkend="CheckDims">CheckDims</link></member>
+      <member><link linkend="CheckRow">CheckRow</link></member>
+      <member><link linkend="CheckScalar">CheckScalar</link></member>
+      <member><link linkend="CheckVector">CheckVector</link></member>
+      <member><link linkend="OverLoad">CheckOverLoad</link></member>
+      <member><link linkend="CheckDimProp">CheckDimProp</link></member>
+      <member><link linkend="CheckLength">CheckLength</link></member>
+      <member><link linkend="CheckSameDims">CheckSameDims</link></member>
+      <member><link linkend="How to check parameters">HowToCheckParameters</link></member>
+    </simplelist>
+  </refsection>
+</refentry>
diff --git a/scilab/modules/core/help/en_US/capi/CheckVector.xml b/scilab/modules/core/help/en_US/capi/CheckVector.xml
new file mode 100644 (file)
index 0000000..7e7c068
--- /dev/null
@@ -0,0 +1,102 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<refentry version="5.0-subset Scilab" xml:id="CheckVector" xml:lang="en"
+          xmlns="http://docbook.org/ns/docbook"
+          xmlns:xlink="http://www.w3.org/1999/xlink"
+          xmlns:svg="http://www.w3.org/2000/svg"
+          xmlns:mml="http://www.w3.org/1998/Math/MathML"
+          xmlns:html="http://www.w3.org/1999/xhtml"
+          xmlns:db="http://docbook.org/ns/docbook">
+  <refnamediv>
+    <refname>CheckVector</refname>
+
+    <refpurpose>C interface function which checks if a parameter send to the C
+    function is a vector (column or row) or not</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <title>Calling Sequence</title>
+
+    <synopsis>CheckVector(StackPos,m_var,n_var)</synopsis>
+  </refsynopsisdiv>
+
+  <refsection>
+    <title>Parameters</title>
+
+    <variablelist>
+      <varlistentry>
+        <term>StackPos</term>
+
+        <listitem>
+          <para>the position on the stack of the variable for which we want to
+          perform the check (input parameter)</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>m_var</term>
+
+        <listitem>
+          <para>the number of lines of the parameter at position StackPos on
+          the stack</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>n_var</term>
+
+        <listitem>
+          <para>the number of columns of the parameter at position StackPos on
+          the stack</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+  </refsection>
+
+  <refsection>
+    <title>Description</title>
+
+    <para>C interface function which checks if a parameter send to the C
+    function is a vector (column or row) or not. You must include stack-c.h to
+    benefit from this function. If the test fails, we return from the C
+    interface and an adequate error message is printed in the Scilab
+    console.</para>
+  </refsection>
+
+  <refsection>
+    <title>Examples</title>
+
+    <programlisting role="example"> 
+#include &lt;stack-c.h&gt;
+
+int sci_check_properties(char * fname)
+{
+  int m1, n1, l1;
+
+  CheckRhs(1,1);
+
+  GetRhsVar(1, "d", &amp;m1, &amp;n1, &amp;l1);
+
+  CheckVector(1,m1,n1); // Check that first argument is a vector (column or row)
+
+  return 0;
+}
+ </programlisting>
+  </refsection>
+
+  <refsection>
+    <title>See Also</title>
+
+    <simplelist type="inline">
+      <member><link linkend="CheckColumn">CheckColumn</link></member>
+      <member><link linkend="CheckDims">CheckDims</link></member>
+      <member><link linkend="CheckRow">CheckRow</link></member>
+      <member><link linkend="CheckScalar">CheckScalar</link></member>
+      <member><link linkend="OverLoad">CheckOverLoad</link></member>
+      <member><link linkend="CheckDimProp">CheckDimProp</link></member>
+      <member><link linkend="CheckLength">CheckLength</link></member>
+      <member><link linkend="CheckSameDims">CheckSameDims</link></member>
+      <member><link linkend="CheckSquare">CheckSquare</link></member>
+      <member><link linkend="How to check parameters">HowToCheckParameters</link></member>
+    </simplelist>
+  </refsection>
+</refentry>
diff --git a/scilab/modules/core/help/en_US/capi/FindOpt.xml b/scilab/modules/core/help/en_US/capi/FindOpt.xml
new file mode 100644 (file)
index 0000000..87e2554
--- /dev/null
@@ -0,0 +1,146 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<refentry version="5.0-subset Scilab" xml:id="FindOpt" xml:lang="en"
+          xmlns="http://docbook.org/ns/docbook"
+          xmlns:xlink="http://www.w3.org/1999/xlink"
+          xmlns:svg="http://www.w3.org/2000/svg"
+          xmlns:mml="http://www.w3.org/1998/Math/MathML"
+          xmlns:html="http://www.w3.org/1999/xhtml"
+          xmlns:db="http://docbook.org/ns/docbook">
+  <refnamediv>
+    <refname>FindOpt</refname>
+
+    <refpurpose>C interface function find the position of an optional argument
+    given its name</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <title>Calling Sequence</title>
+
+    <synopsis>Pos FindOpt(varname, opts)</synopsis>
+  </refsynopsisdiv>
+
+  <refsection>
+    <title>Parameters</title>
+
+    <variablelist>
+      <varlistentry>
+        <term>varname</term>
+
+        <listitem>
+          <para>the name of the optional parameter</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>opts</term>
+
+        <listitem>
+          <para>a C list of optional parameters</para>
+
+          <programlisting> 
+typedef struct rhs_opts__ {
+  int position ; // stack position : -1 if not present
+  char *name; // the name of the variable
+  char *type; // a Scilab type (like "d") representing the type of the variable
+  int m,n; // the size of the variable
+  unsigned long int l; // a pointer to the Scilab stack
+} rhs_opts;
+ </programlisting>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>Pos</term>
+
+        <listitem>
+          <para>the rank of the optional parameter if it has been found in the
+          parameters sent to the C function, 0 otherwise.</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+  </refsection>
+
+  <refsection>
+    <title>Description</title>
+
+    <para>C interface function find the position of an optional argument given
+    its name. You must include stack-c.h to benefit from this function.</para>
+  </refsection>
+
+  <refsection>
+    <title>Examples</title>
+
+    <para>A more complete example is available in the directory
+    example/optional_parameters.</para>
+
+    <programlisting role="example"> 
+#include &lt;stack-c.h&gt;
+
+int sci_optional_parameters(char * fname)
+{ 
+  int m1,n1,l1;
+
+  // optional names must be stored in alphabetical order in opts
+  static rhs_opts opts[]= {{-1,"v1","d",0,0,0},
+                           {-1,"v2","d",0,0,0},
+                           {-1,NULL,NULL,0,0}};
+
+  int minrhs = 1, maxrhs = 1;
+  int minlhs = 1, maxlhs = 3;
+  int nopt, iopos, res;
+  char buffer_name[csiz]; // csiz used for character coding
+
+  nopt = NumOpt();
+
+  CheckRhs(minrhs,maxrhs+nopt);
+  CheckLhs(minlhs,maxlhs);
+
+  // first non optional argument
+  GetRhsVar( 1, "c", &amp;m1, &amp;n1, &amp;l1);
+  
+  if (get_optionals(fname,opts)==0) return 0;
+
+  sciprint("number of optional parameters = %d\n", NumOpt());
+  sciprint("first optional parameters = %d\n", FirstOpt());
+  sciprint("FindOpt(v1) = %d\n", FindOpt("v1", opts));
+  sciprint("FindOpt(v2) = %d\n", FindOpt("v2", opts));
+
+  if (IsOpt(1,buffer_name))
+    sciprint("parameter 1 is optional: %s\n", buffer_name);
+  if (IsOpt(2,buffer_name))
+    sciprint("parameter 2 is optional: %s\n", buffer_name);
+  if (IsOpt(3,buffer_name))
+    sciprint("parameter 3 is optional: %s\n", buffer_name);
+
+  return 0;
+}
+ </programlisting>
+  </refsection>
+
+  <refsection>
+    <title>See Also</title>
+
+    <simplelist type="inline">
+      <member><link linkend="CheckDims">CheckDims</link></member>
+
+      <member><link linkend="CheckRow">CheckRow</link></member>
+
+      <member><link linkend="CheckScalar">CheckScalar</link></member>
+
+      <member><link linkend="CheckVector">CheckVector</link></member>
+
+      <member><link linkend="OverLoad">CheckOverLoad</link></member>
+
+      <member><link linkend="CheckDimProp">CheckDimProp</link></member>
+
+      <member><link linkend="CheckLength">CheckLength</link></member>
+
+      <member><link linkend="CheckSameDims">CheckSameDims</link></member>
+
+      <member><link linkend="CheckSquare">CheckSquare</link></member>
+
+      <member><link
+      linkend="How to check parameters">HowToCheckParameters</link></member>
+    </simplelist>
+  </refsection>
+</refentry>
diff --git a/scilab/modules/core/help/en_US/capi/FirstOpt.xml b/scilab/modules/core/help/en_US/capi/FirstOpt.xml
new file mode 100644 (file)
index 0000000..59a0ec7
--- /dev/null
@@ -0,0 +1,121 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<refentry version="5.0-subset Scilab" xml:id="FirstOpt" xml:lang="en"
+          xmlns="http://docbook.org/ns/docbook"
+          xmlns:xlink="http://www.w3.org/1999/xlink"
+          xmlns:svg="http://www.w3.org/2000/svg"
+          xmlns:mml="http://www.w3.org/1998/Math/MathML"
+          xmlns:html="http://www.w3.org/1999/xhtml"
+          xmlns:db="http://docbook.org/ns/docbook">
+  <refnamediv>
+    <refname>FirstOpt</refname>
+
+    <refpurpose>C interface function which returns the position of the first
+    optional parameter</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <title>Calling Sequence</title>
+
+    <synopsis>Pos FirstOpt()</synopsis>
+  </refsynopsisdiv>
+
+  <refsection>
+    <title>Parameters</title>
+
+    <variablelist>
+      <varlistentry>
+        <term>Pos</term>
+
+        <listitem>
+          <para>the position of the first optional parameter, Rhs + 1 if no
+          optional parameters have been given to the function</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+  </refsection>
+
+  <refsection>
+    <title>Description</title>
+
+    <para>C interface function which returns the position of the first
+    optional parameter. You must include stack-c.h to benefit from this
+    function.</para>
+  </refsection>
+
+  <refsection>
+    <title>Examples</title>
+
+    <para>A more complete example is available in the directory
+    example/optional_parameters.</para>
+
+    <programlisting role="example"> 
+#include &lt;stack-c.h&gt;
+
+int sci_optional_parameters(char * fname)
+{ 
+  int m1,n1,l1;
+
+  // optional names must be stored in alphabetical order in opts
+  static rhs_opts opts[]= {{-1,"v1","d",0,0,0},
+                           {-1,"v2","d",0,0,0},
+                           {-1,NULL,NULL,0,0}};
+
+  int minrhs = 1, maxrhs = 1;
+  int minlhs = 1, maxlhs = 3;
+  int nopt, iopos, res;
+  char buffer_name[csiz]; // csiz used for character coding
+
+  nopt = NumOpt();
+
+  CheckRhs(minrhs,maxrhs+nopt);
+  CheckLhs(minlhs,maxlhs);
+
+  // first non optional argument
+  GetRhsVar( 1, "c", &amp;m1, &amp;n1, &amp;l1);
+  
+  if (get_optionals(fname,opts)==0) return 0;
+
+  sciprint("number of optional parameters = %d\n", NumOpt());
+  sciprint("first optional parameters = %d\n", FirstOpt());
+  sciprint("FindOpt(v1) = %d\n", FindOpt("v1", opts));
+  sciprint("FindOpt(v2) = %d\n", FindOpt("v2", opts));
+
+  if (IsOpt(1,buffer_name))
+    sciprint("parameter 1 is optional: %s\n", buffer_name);
+  if (IsOpt(2,buffer_name))
+    sciprint("parameter 2 is optional: %s\n", buffer_name);
+  if (IsOpt(3,buffer_name))
+    sciprint("parameter 3 is optional: %s\n", buffer_name);
+
+  return 0;
+}
+ </programlisting>
+  </refsection>
+
+  <refsection>
+    <title>See Also</title>
+
+    <simplelist type="inline">
+      <member><link linkend="CheckDims">CheckDims</link></member>
+
+      <member><link linkend="CheckRow">CheckRow</link></member>
+
+      <member><link linkend="CheckScalar">CheckScalar</link></member>
+
+      <member><link linkend="CheckVector">CheckVector</link></member>
+
+      <member><link linkend="OverLoad">CheckOverLoad</link></member>
+
+      <member><link linkend="CheckDimProp">CheckDimProp</link></member>
+
+      <member><link linkend="CheckLength">CheckLength</link></member>
+
+      <member><link linkend="CheckSameDims">CheckSameDims</link></member>
+
+      <member><link linkend="CheckSquare">CheckSquare</link></member>
+
+      <member><link
+      linkend="How to check parameters">HowToCheckParameters</link></member>
+    </simplelist>
+  </refsection>
+</refentry>
diff --git a/scilab/modules/core/help/en_US/capi/HowToCheckParameters.xml b/scilab/modules/core/help/en_US/capi/HowToCheckParameters.xml
new file mode 100644 (file)
index 0000000..740f85b
--- /dev/null
@@ -0,0 +1,319 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<refentry version="5.0-subset Scilab" xml:id="HowToCheckParameters"
+          xmlns="http://docbook.org/ns/docbook"
+          xmlns:xlink="http://www.w3.org/1999/xlink"
+          xmlns:xi="http://www.w3.org/2001/XInclude"
+          xmlns:svg="http://www.w3.org/2000/svg"
+          xmlns:mml="http://www.w3.org/1998/Math/MathML"
+          xmlns:html="http://www.w3.org/1999/xhtml"
+          xmlns:db="http://docbook.org/ns/docbook">
+  <refnamediv>
+    <refname>How to check parameters</refname>
+
+    <refpurpose>how to check parameter send to an interface using the C
+    API</refpurpose>
+  </refnamediv>
+
+  <refsection>
+    <title>Description</title>
+
+    <para>The goal is to get a set of parameters via a C interface and then to
+    perform some checks in the C function.</para>
+
+    <para>This example is available in the directory
+    CAPI/examples/check_properties.</para>
+  </refsection>
+
+  <refsection>
+    <title>The C function</title>
+
+    <programlisting role="example"> 
+#include &lt;stack-c.h&gt;
+#include &lt;sciprint.h&gt;
+
+int sci_check_properties_1(char * fname)
+{
+  int m1, n1, l1;
+  int m2, n2, l2;
+  int m3, n3, l3;
+  int m4, n4, l4;
+  int m5, n5, l5;
+
+  CheckRhs(5,5);
+  CheckLhs(0,1) ;
+
+  ////////////////////////////
+  // Getting first argument //
+  ////////////////////////////
+
+  GetRhsVar(1, "d", &amp;m1, &amp;n1, &amp;l1);
+
+  CheckVector(1,m1,n1);   // Check that first argument is a vector
+  CheckLength(1,m1*n1,4); // Check vector length
+  
+  /////////////////////////////
+  // Getting second argument //
+  /////////////////////////////
+
+  GetRhsVar(2, "d", &amp;m2, &amp;n2, &amp;l2);
+
+  CheckRow(2,m2,n2); // Checks that second argument is a row vector
+                     // CheckColumn can also be used
+
+  CheckDimProp(1,2, m1 * n1 != n2); // Check compatibility beetween arg 1 and arg 2. We want m1*n1 == n2 
+
+  ////////////////////////////
+  // Getting third argument //
+  ////////////////////////////
+
+  GetRhsVar(3, "d", &amp;m3, &amp;n3, &amp;l3);
+
+  CheckSameDims(1,3,m1,n1,m3,n3); // Checks that arg 1 and arg3 have same dimensions
+
+  /////////////////////////////
+  // Getting fourth argument //
+  /////////////////////////////
+
+  GetRhsVar(4,"d",&amp;m4,&amp;n4,&amp;l4);
+  
+  CheckScalar(4,m4,n4); // arg 4 must be scalar
+
+  /////////////////////////////
+  // Getting fourth argument //
+  /////////////////////////////
+
+  GetRhsVar(5,"d",&amp;m5,&amp;n5,&amp;l5);
+  
+  CheckSquare(5,m5,n5);   // square matrix
+  CheckDims(5,m5,m5,5,5); // check dimensions
+
+  LhsVar(1)=0;
+
+  return 0;
+}
+
+// We must be careful on the scilab name function (8 chars max).
+
+int sci_check_properties_2(char * fname)
+{
+  int m1,n1,l1;
+
+  CheckRhs(1,1);
+  CheckLhs(0,1) ;
+
+  switch(VarType(1)) 
+    {
+    case 1: 
+      GetRhsVar(1, "d", &amp;m1, &amp;n1, &amp;l1);
+      sciprint("1 is a scalar matrix\n");
+      break;
+    case 10:
+      GetRhsVar(1, "c", &amp;m1, &amp;n1, &amp;l1);
+      sciprint("1 is a string\n");
+      break;
+    case 5:
+      sciprint("1 is a sparse trying to overload\n");
+      OverLoad(1);
+    }
+
+  LhsVar(1) = 0;
+
+  return 0;
+}
+  </programlisting>
+
+    <para>This file must be saved as "check_properties.c".</para>
+
+    <para>The main thing to highlight is that, to build a C interface
+    function, we need to include the header stack-c.h. In this header, we find
+    the prototypes and macros of the main C interface functions. We also need
+    to include sciprint.h because we use the sciprint function.</para>
+
+    <para>To be able to build and link such a C function to scilab, we need to
+    write a Scilab script which will compile this C function and then create a
+    loader script which will link the C function to a Scilab function.</para>
+  </refsection>
+
+  <refsection>
+    <title>The builder script</title>
+
+    <programlisting role="example"> 
+// This is the builder.sce 
+// must be run from this directory 
+
+lines(0);
+
+ilib_name  = 'lib_check_properties';
+
+files = ['check_properties.c'];
+
+libs  = [];
+
+table =['check_properties_1', 'sci_check_properties_1'; ...
+        'chprop2',            'sci_check_properties_2'];
+
+// We must be careful when we choose a scilab function name in case of overloading.
+// We Scilab name function must be 8 char max.
+
+ldflags = "";
+cflags  = "";
+fflags  = "";
+
+// do not modify below 
+// ----------------------------------------------
+ilib_build(ilib_name,table,files,libs,'Makelib',ldflags,cflags,fflags);
+  </programlisting>
+
+    <para>This file must be saved as "builder.sce".</para>
+
+    <para>This script will tell Scilab which files must be compiled (here,
+    it's check_properties.c), what will be the name of the shared library
+    (here, it's lib_check_properties) and which C symbol will be linked to a
+    Scilab function (here, we will link the sci_check_properties_1 C symbol to
+    the Scilab function "check_properties_1").</para>
+
+    <para>For the other C function, we must be careful on the name of the
+    Scilab function we will choose. Because this function will be overloading,
+    the current overloading process of Scilab works only on Scilab primitives
+    (Scilab function wrote in C) which have a name which is maximum 8 char
+    wide.</para>
+
+    <para>For this function, we will link the sci_check_properties_2 C symbol
+    to the Scilab function "chprop2").</para>
+
+    <para>To build this function, we just need to to:</para>
+
+    <programlisting> 
+exec builder.sce;
+ </programlisting>
+
+    <para>Now we are able to test our new C function. First, let's load this
+    new function in scilab:</para>
+
+    <programlisting> 
+exec loader.sce; 
+ </programlisting>
+
+    <para>The script loader.sce is normally automatically built by
+    builder.sce.</para>
+  </refsection>
+
+  <refsection>
+    <title>Testing our new function</title>
+
+    <para>We now write a simple example to test our new functions.</para>
+
+    <programlisting role="example"> 
+// checks arguments compatibility 
+
+check_properties_1([1;2;3;4],[3,4,5,6],[6;7;8;9],90,rand(5,5))
+
+// first argument can have different types 
+
+chprop2([1,2,2]);
+chprop2('foo');
+
+// overload case 
+
+deff('[]=%sp_chprop2(sp)','disp(''sparse overloaded'')');
+chprop2(sparse([1,2,3]));
+
+// tests which give an error message with check_properties_1
+
+try
+  check_properties_1([1;2;3;4]',[3,4,5,6],[6;7;8;9],90,rand(5,5))
+catch
+  disp(lasterror());
+end
+
+try
+  check_properties_1([1;2;3;4],[3,4,5,6]',[6;7;8;9],90,rand(5,5))
+catch
+  disp(lasterror());
+end
+
+try
+  check_properties_1([1;2;3;4],[3,4,5,6],[6;7;8;9]',90,rand(5,5))
+catch
+  disp(lasterror());
+end
+
+try
+  check_properties_1([1;2;3;4],[3,4,5,6],[6;7;8;9],[],rand(5,5))
+catch
+  disp(lasterror());
+end
+
+try
+  check_properties_1([1;2;3;4],[3,4,5,6],[6;7;8;9],90,rand(4,4))
+catch
+  disp(lasterror());
+end
+ </programlisting>
+
+    <para>The script must be saved as "check_properties.sce".</para>
+
+    <para>Let's run our scripts and see what is the result:</para>
+
+    <programlisting> 
+--&gt;exec builder.sce;
+   Génère un fichier gateway
+   Génère un fichier loader
+   Génère un Makefile : Makelib
+   Exécute le makefile
+   Compilation de check_properties.c
+   Construction de la bibliothèque partagée (soyez patient)
+--&gt;exec loader.sce;
+Bibliothèque partagée chargée.
+Link done.
+--&gt;exec check_properties.sce;
+1 is a scalar matrix
+1 is a string
+1 is a sparse trying to overload
+ sparse overloaded   
+ check_properties_1 : Les paramètres first et third a des dimensions incompatibles (1x4) # (4x1)   
+ check_properties_1: second paramètre devrait être un vecteur ligne   
+ check_properties_1 : Les paramètres first et third a des dimensions incompatibles (4x1) # (1x4)   
+ check_properties_1: fourth paramètre devrait être un scalaire   
+ check_properties_1 : Argument numéro 5 n'a pas les bonnes dimensions (4,4),  (5,5) attendues.    
+ </programlisting>
+  </refsection>
+
+  <refsection>
+    <title>See Also</title>
+
+    <simplelist type="inline">
+      <member><link linkend="GetRhsVar">GetRhsVar</link></member>
+
+      <member><link linkend="CheckColumn">CheckColumn</link></member>
+
+      <member><link linkend="CheckDims">CheckDims</link></member>
+
+      <member><link linkend="CheckRow">CheckRow</link></member>
+
+      <member><link linkend="CheckScalar">CheckScalar</link></member>
+
+      <member><link linkend="CheckVector">CheckVector</link></member>
+
+      <member><link linkend="CheckDimProp">CheckDimProp</link></member>
+
+      <member><link linkend="CheckLength">CheckLength</link></member>
+
+      <member><link linkend="CheckSameDims">CheckSameDims</link></member>
+
+      <member><link linkend="CheckSquare">CheckSquare</link></member>
+
+      <member><link linkend="OverLoad">OverLoad</link></member>
+
+      <member><link linkend="ilib_build">ilib_build</link></member>
+    </simplelist>
+  </refsection>
+</refentry>
diff --git a/scilab/modules/core/help/en_US/capi/HowToDealWithOptionalParameters.xml b/scilab/modules/core/help/en_US/capi/HowToDealWithOptionalParameters.xml
new file mode 100644 (file)
index 0000000..d4d8358
--- /dev/null
@@ -0,0 +1,285 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<refentry version="5.0-subset Scilab" xml:id="HowToDealWithOptionalParameters"
+          xmlns="http://docbook.org/ns/docbook"
+          xmlns:xlink="http://www.w3.org/1999/xlink"
+          xmlns:xi="http://www.w3.org/2001/XInclude"
+          xmlns:svg="http://www.w3.org/2000/svg"
+          xmlns:mml="http://www.w3.org/1998/Math/MathML"
+          xmlns:html="http://www.w3.org/1999/xhtml"
+          xmlns:db="http://docbook.org/ns/docbook">
+  <refnamediv>
+    <refname>How to deal with optional parameters</refname>
+
+    <refpurpose>how to deal with optional parameters send to an interface
+    using the C API</refpurpose>
+  </refnamediv>
+
+  <refsection>
+    <title>Description</title>
+
+    <para>The goal is to get a set of optional parameters via a C interface
+    and then to perform some checks in the C function (number of optional
+    parameters, does an optional parameters exists, etc.).</para>
+
+    <para>This example is available in the directory
+    CAPI/examples/optional_parameters</para>
+  </refsection>
+
+  <refsection>
+    <title>The C function</title>
+
+    <programlisting role="example"> 
+#include &lt;stack-c.h&gt;
+
+int ex2c(double * a, int * ma, int * na,
+         double * b, int * mb, int * nb) 
+{
+  int i;
+
+  for(i=0;i&lt;(*ma)*(*na);i++) a[i] = 2*a[i];
+  for(i=0;i&lt;(*mb)*(*nb);i++) b[i] = 3*b[i];
+
+  return(0);
+}
+
+int sci_optional_parameters(char * fname)
+{ 
+  int m1,n1,l1;
+
+  // optional names must be stored in alphabetical order in opts
+  static rhs_opts opts[]= {{-1,"v1","d",0,0,0},
+                           {-1,"v2","d",0,0,0},
+                           {-1,NULL,NULL,0,0}};
+
+  int minrhs = 1, maxrhs = 1;
+  int minlhs = 1, maxlhs = 3;
+  int nopt, iopos, res;
+  char buffer_name[csiz]; // csiz used for character coding
+
+  nopt = NumOpt();
+
+  CheckRhs(minrhs,maxrhs+nopt);
+  CheckLhs(minlhs,maxlhs);
+
+  // first non optional argument
+  GetRhsVar( 1, "c", &amp;m1, &amp;n1, &amp;l1);
+  
+  if (get_optionals(fname,opts)==0) return 0;
+
+  // default values if optional arguments are not given:  v1=[99] and v2=[3]
+
+  sciprint("number of optional parameters = %d\n", NumOpt());
+  sciprint("first optional parameters = %d\n", FirstOpt());
+  sciprint("FindOpt(v1) = %d\n", FindOpt("v1", opts));
+  sciprint("FindOpt(v2) = %d\n", FindOpt("v2", opts));
+
+  if (IsOpt(1,buffer_name))
+    sciprint("parameter 1 is optional: %s\n", buffer_name);
+  if (IsOpt(2,buffer_name))
+    sciprint("parameter 2 is optional: %s\n", buffer_name);
+  if (IsOpt(3,buffer_name))
+    sciprint("parameter 3 is optional: %s\n", buffer_name);
+
+  iopos = Rhs;
+
+  if (opts[0].position==-1)
+    {
+      iopos++;
+      opts[0].position = iopos;
+      opts[0].m = 1; opts[0].n = 1; 
+      opts[0].type = "d";
+      CreateVar(opts[0].position, opts[0].type, &amp;opts[0].m, &amp;opts[0].n, &amp;opts[0].l);
+      *stk(opts[0].l) = 99.0;
+    }
+
+  if (opts[1].position==-1) 
+    {
+      iopos++ ; 
+      opts[1].position = iopos;
+      opts[1].m = 1; opts[1].n = 1;
+      opts[1].type = "d";
+      CreateVar(opts[1].position, opts[1].type, &amp;opts[1].m, &amp;opts[1].n, &amp;opts[1].l);
+      *stk(opts[1].l) = 3;
+    }
+
+  ex2c(stk(opts[0].l),&amp;opts[0].m,&amp;opts[0].n,
+       stk(opts[1].l),&amp;opts[1].m,&amp;opts[1].n);
+
+  // return the first argument (unchanged ) then v1 and v2
+
+  LhsVar(1) = 1;
+  LhsVar(2) = opts[0].position;
+  LhsVar(3) = opts[1].position;
+
+  return 0;
+}
+  </programlisting>
+
+    <para>This file must be saved as "optional_parameters.c".</para>
+
+    <para>The main thing to highlight is that, to build a C interface
+    function, we need to include the header stack-c.h. In this header, we find
+    the prototypes and macros of the main C interface functions. We also need
+    to include sciprint.h because we use the sciprint function.</para>
+
+    <para>To be able to build and link such a C function to scilab, we need to
+    write a Scilab script which will compile this C function and then create a
+    loader script which will link the C function to a Scilab function.</para>
+  </refsection>
+
+  <refsection>
+    <title>The builder script</title>
+
+    <programlisting role="example"> 
+// This is the builder.sce 
+// must be run from this directory 
+
+lines(0);
+
+ilib_name  = 'lib_optional_parameters';
+
+files = ['optional_parameters.c'];
+
+libs  = [];
+
+table =['optional_parameters', 'sci_optional_parameters'];
+
+ldflags = "";
+cflags  = "";
+fflags  = "";
+
+// do not modify below 
+// ----------------------------------------------
+ilib_build(ilib_name,table,files,libs,'Makelib',ldflags,cflags,fflags);
+  </programlisting>
+
+    <para>This file must be saved as "builder.sce".</para>
+
+    <para>This script will tell Scilab which files must be compiled (here,
+    it's optional_parameters.c), what will be the name of the shared library
+    (here, it's lib_optional_parameters) and which C symbol will be linked to
+    a Scilab function (here, we will link the sci_optional_parameters C symbol
+    to the Scilab function "optional_parameters").</para>
+
+    <para>To build this function, we just need to to:</para>
+
+    <programlisting> 
+exec builder.sce;
+ </programlisting>
+
+    <para>Now we are able to test our new C function. First, let's load this
+    new function in scilab:</para>
+
+    <programlisting> 
+exec loader.sce; 
+ </programlisting>
+
+    <para>The script loader.sce is normally automatically built by
+    builder.sce.</para>
+  </refsection>
+
+  <refsection>
+    <title>Testing our new function</title>
+
+    <para>We now write a simple example to test our new functions.</para>
+
+    <programlisting role="example"> 
+// Example with optional argument specified with the 'arg=value syntax'
+// [a,b,c] = ex12c(x1, [v1 = arg1, v2 = arg2]), arg1 default value 99
+//                                              arg2 default value 3
+// only v1 and v2 are recognized as optional argument names 
+// the return value are a = x1, b = 2*v2, c = 3*v2 
+
+[a,b,c] = optional_parameters('test');
+disp('a = ' + a + ' b = ' + string(b) + ' c = ' + string(c));
+
+[a,b,c] = optional_parameters('test',v1=[10,20]);
+disp('a = ' + a + ' b = ' + string(b) + ' c = ' + string(c));
+
+[a,b,c] = optional_parameters('test',v1=[10,20],v2=8);
+disp('a = ' + a + ' b = ' + string(b) + ' c = ' + string(c));
+
+[a,b,c] = optional_parameters('test',v2=8,v1=[10]);
+disp('a = ' + a + ' b = ' + string(b) + ' c = ' + string(c));
+  </programlisting>
+
+    <para>The script must be saved as "optional_parameters.sce".</para>
+
+    <para>Let's run our scripts and see what is the result:</para>
+
+    <programlisting> 
+--&gt;exec builder.sce;
+   Génère un fichier gateway
+   Génère un fichier loader
+   Génère un Makefile : Makelib
+   Exécute le makefile
+   Compilation de optional_parameters.c
+   Construction de la bibliothèque partagée (soyez patient)
+--&gt;exec loader.sce;
+Bibliothèque partagée chargée.
+Link done.
+--&gt;exec optional_parameters.sce;
+number of optional parameters = 0
+first optional parameters = 2
+FindOpt(v1) = 0
+FindOpt(v2) = 0
+ a = test b = 198 c = 9   
+number of optional parameters = 1
+first optional parameters = 2
+FindOpt(v1) = 2
+FindOpt(v2) = 0
+parameter 2 is optional: v1
+!a = test b = 20 c = 9  a = test b = 40 c = 9  !
+number of optional parameters = 2
+first optional parameters = 2
+FindOpt(v1) = 2
+FindOpt(v2) = 3
+parameter 2 is optional: v1
+parameter 3 is optional: v2
+!a = test b = 20 c = 24  a = test b = 40 c = 24  !
+number of optional parameters = 2
+first optional parameters = 2
+FindOpt(v1) = 3
+FindOpt(v2) = 2
+parameter 2 is optional: v2
+parameter 3 is optional: v1
+ a = test b = 20 c = 24  
+ </programlisting>
+  </refsection>
+
+  <refsection>
+    <title>See Also</title>
+
+    <simplelist type="inline">
+      <member><link linkend="GetRhsVar">GetRhsVar</link></member>
+
+      <member><link linkend="CheckColumn">CheckColumn</link></member>
+
+      <member><link linkend="CheckDims">CheckDims</link></member>
+
+      <member><link linkend="CheckRow">CheckRow</link></member>
+
+      <member><link linkend="CheckScalar">CheckScalar</link></member>
+
+      <member><link linkend="CheckVector">CheckVector</link></member>
+
+      <member><link linkend="CheckDimProp">CheckDimProp</link></member>
+
+      <member><link linkend="CheckLength">CheckLength</link></member>
+
+      <member><link linkend="CheckSameDims">CheckSameDims</link></member>
+
+      <member><link linkend="CheckSquare">CheckSquare</link></member>
+
+      <member><link linkend="OverLoad">OverLoad</link></member>
+
+      <member><link linkend="ilib_build">ilib_build</link></member>
+    </simplelist>
+  </refsection>
+</refentry>
diff --git a/scilab/modules/core/help/en_US/capi/IsOpt.xml b/scilab/modules/core/help/en_US/capi/IsOpt.xml
new file mode 100644 (file)
index 0000000..22a3235
--- /dev/null
@@ -0,0 +1,139 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<refentry version="5.0-subset Scilab" xml:id="IsOpt" xml:lang="en"
+          xmlns="http://docbook.org/ns/docbook"
+          xmlns:xlink="http://www.w3.org/1999/xlink"
+          xmlns:svg="http://www.w3.org/2000/svg"
+          xmlns:mml="http://www.w3.org/1998/Math/MathML"
+          xmlns:html="http://www.w3.org/1999/xhtml"
+          xmlns:db="http://docbook.org/ns/docbook">
+  <refnamediv>
+    <refname>IsOpt</refname>
+
+    <refpurpose>C interface function which checks if a parameter is optional
+    and returns the name of the variable</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <title>Calling Sequence</title>
+
+    <synopsis>Res IsOpt(Pos,buffer_name)</synopsis>
+  </refsynopsisdiv>
+
+  <refsection>
+    <title>Parameters</title>
+
+    <variablelist>
+      <varlistentry>
+        <term>Pos</term>
+
+        <listitem>
+          <para>the position on the stack of the variable to be checked (input
+          parameter)</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>buffer_name</term>
+
+        <listitem>
+          <para>an array of char (of size csiz which correspond to the maximum
+          length of a Scilab variable) in which the name of the variable will
+          be copied if the position Pos is optional (output parameter)</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>Res</term>
+
+        <listitem>
+          <para>1 if Pos has an optional parameter, 0 otherwise</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+  </refsection>
+
+  <refsection>
+    <title>Description</title>
+
+    <para>C interface function which checks if a parameter is optional and
+    returns the name of the variable. You must include stack-c.h to benefit
+    from this function.</para>
+  </refsection>
+
+  <refsection>
+    <title>Examples</title>
+
+    <para>A more complete example is available in the directory
+    example/optional_parameters.</para>
+
+    <programlisting role="example"> 
+#include &lt;stack-c.h&gt;
+
+int sci_optional_parameters(char * fname)
+{ 
+  int m1,n1,l1;
+
+  // optional names must be stored in alphabetical order in opts
+  static rhs_opts opts[]= {{-1,"v1","d",0,0,0},
+                           {-1,"v2","d",0,0,0},
+                           {-1,NULL,NULL,0,0}};
+
+  int minrhs = 1, maxrhs = 1;
+  int minlhs = 1, maxlhs = 3;
+  int nopt, iopos, res;
+  char buffer_name[csiz]; // csiz used for character coding
+
+  nopt = NumOpt();
+
+  CheckRhs(minrhs,maxrhs+nopt);
+  CheckLhs(minlhs,maxlhs);
+
+  // first non optional argument
+  GetRhsVar( 1, "c", &amp;m1, &amp;n1, &amp;l1);
+  
+  if (get_optionals(fname,opts)==0) return 0;
+
+  sciprint("number of optional parameters = %d\n", NumOpt());
+  sciprint("first optional parameters = %d\n", FirstOpt());
+  sciprint("FindOpt(v1) = %d\n", FindOpt("v1", opts));
+  sciprint("FindOpt(v2) = %d\n", FindOpt("v2", opts));
+
+  if (IsOpt(1,buffer_name))
+    sciprint("parameter 1 is optional: %s\n", buffer_name);
+  if (IsOpt(2,buffer_name))
+    sciprint("parameter 2 is optional: %s\n", buffer_name);
+  if (IsOpt(3,buffer_name))
+    sciprint("parameter 3 is optional: %s\n", buffer_name);
+
+  return 0;
+}
+ </programlisting>
+  </refsection>
+
+  <refsection>
+    <title>See Also</title>
+
+    <simplelist type="inline">
+      <member><link linkend="CheckDims">CheckDims</link></member>
+
+      <member><link linkend="CheckRow">CheckRow</link></member>
+
+      <member><link linkend="CheckScalar">CheckScalar</link></member>
+
+      <member><link linkend="CheckVector">CheckVector</link></member>
+
+      <member><link linkend="OverLoad">CheckOverLoad</link></member>
+
+      <member><link linkend="CheckDimProp">CheckDimProp</link></member>
+
+      <member><link linkend="CheckLength">CheckLength</link></member>
+
+      <member><link linkend="CheckSameDims">CheckSameDims</link></member>
+
+      <member><link linkend="CheckSquare">CheckSquare</link></member>
+
+      <member><link
+      linkend="How to check parameters">HowToCheckParameters</link></member>
+    </simplelist>
+  </refsection>
+</refentry>
diff --git a/scilab/modules/core/help/en_US/capi/NumOpt.xml b/scilab/modules/core/help/en_US/capi/NumOpt.xml
new file mode 100644 (file)
index 0000000..3777ede
--- /dev/null
@@ -0,0 +1,120 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<refentry version="5.0-subset Scilab" xml:id="NumOpt" xml:lang="en"
+          xmlns="http://docbook.org/ns/docbook"
+          xmlns:xlink="http://www.w3.org/1999/xlink"
+          xmlns:svg="http://www.w3.org/2000/svg"
+          xmlns:mml="http://www.w3.org/1998/Math/MathML"
+          xmlns:html="http://www.w3.org/1999/xhtml"
+          xmlns:db="http://docbook.org/ns/docbook">
+  <refnamediv>
+    <refname>NumOpt</refname>
+
+    <refpurpose>C interface function which returns the number of optional
+    parameters sent to a C function</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <title>Calling Sequence</title>
+
+    <synopsis>Res = NumOpt()</synopsis>
+  </refsynopsisdiv>
+
+  <refsection>
+    <title>Parameters</title>
+
+    <variablelist>
+      <varlistentry>
+        <term>Res</term>
+
+        <listitem>
+          <para>the number of optional parameters detected</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+  </refsection>
+
+  <refsection>
+    <title>Description</title>
+
+    <para>C interface function which returns the number of optional parameters
+    sent to a C function. You must include stack-c.h to benefit from this
+    function.</para>
+  </refsection>
+
+  <refsection>
+    <title>Examples</title>
+
+    <para>A more complete example is available in the directory
+    example/optional_parameters.</para>
+
+    <programlisting role="example"> 
+#include &lt;stack-c.h&gt;
+
+int sci_optional_parameters(char * fname)
+{ 
+  int m1,n1,l1;
+
+  // optional names must be stored in alphabetical order in opts
+  static rhs_opts opts[]= {{-1,"v1","d",0,0,0},
+                           {-1,"v2","d",0,0,0},
+                           {-1,NULL,NULL,0,0}};
+
+  int minrhs = 1, maxrhs = 1;
+  int minlhs = 1, maxlhs = 3;
+  int nopt, iopos, res;
+  char buffer_name[csiz]; // csiz used for character coding
+
+  nopt = NumOpt();
+
+  CheckRhs(minrhs,maxrhs+nopt);
+  CheckLhs(minlhs,maxlhs);
+
+  // first non optional argument
+  GetRhsVar( 1, "c", &amp;m1, &amp;n1, &amp;l1);
+  
+  if (get_optionals(fname,opts)==0) return 0;
+
+  sciprint("number of optional parameters = %d\n", NumOpt());
+  sciprint("first optional parameters = %d\n", FirstOpt());
+  sciprint("FindOpt(v1) = %d\n", FindOpt("v1", opts));
+  sciprint("FindOpt(v2) = %d\n", FindOpt("v2", opts));
+
+  if (IsOpt(1,buffer_name))
+    sciprint("parameter 1 is optional: %s\n", buffer_name);
+  if (IsOpt(2,buffer_name))
+    sciprint("parameter 2 is optional: %s\n", buffer_name);
+  if (IsOpt(3,buffer_name))
+    sciprint("parameter 3 is optional: %s\n", buffer_name);
+
+  return 0;
+}
+ </programlisting>
+  </refsection>
+
+  <refsection>
+    <title>See Also</title>
+
+    <simplelist type="inline">
+      <member><link linkend="CheckDims">CheckDims</link></member>
+
+      <member><link linkend="CheckRow">CheckRow</link></member>
+
+      <member><link linkend="CheckScalar">CheckScalar</link></member>
+
+      <member><link linkend="CheckVector">CheckVector</link></member>
+
+      <member><link linkend="OverLoad">CheckOverLoad</link></member>
+
+      <member><link linkend="CheckDimProp">CheckDimProp</link></member>
+
+      <member><link linkend="CheckLength">CheckLength</link></member>
+
+      <member><link linkend="CheckSameDims">CheckSameDims</link></member>
+
+      <member><link linkend="CheckSquare">CheckSquare</link></member>
+
+      <member><link
+      linkend="How to check parameters">HowToCheckParameters</link></member>
+    </simplelist>
+  </refsection>
+</refentry>
diff --git a/scilab/modules/core/help/en_US/capi/OverLoad.xml b/scilab/modules/core/help/en_US/capi/OverLoad.xml
new file mode 100644 (file)
index 0000000..1b2a0c5
--- /dev/null
@@ -0,0 +1,147 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<refentry version="5.0-subset Scilab" xml:id="OverLoad" xml:lang="en"
+          xmlns="http://docbook.org/ns/docbook"
+          xmlns:xlink="http://www.w3.org/1999/xlink"
+          xmlns:svg="http://www.w3.org/2000/svg"
+          xmlns:mml="http://www.w3.org/1998/Math/MathML"
+          xmlns:html="http://www.w3.org/1999/xhtml"
+          xmlns:db="http://docbook.org/ns/docbook">
+  <refnamediv>
+    <refname>OverLoad</refname>
+
+    <refpurpose>C interface function which tells Scilab to look for another
+    overloaded function</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <title>Calling Sequence</title>
+
+    <synopsis>OverLoad(StackPos)</synopsis>
+  </refsynopsisdiv>
+
+  <refsection>
+    <title>Parameters</title>
+
+    <variablelist>
+      <varlistentry>
+        <term>StackPos</term>
+
+        <listitem>
+          <para>the position on the stack of the variable for which we want to
+          take into account for the overloading process (input
+          parameter)</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+  </refsection>
+
+  <refsection>
+    <title>Description</title>
+
+    <para>C interface function which tells Scilab to look for another
+    overloaded function. Scilab then appends to the name of the function a
+    prefix (like %sp_ if the parameter taken into account is sparse) and look
+    for the overloaded function. You must include stack-c.h to benefit from
+    this function. Be careful with the Scilab name of the function. Indeed,
+    the current overloading process of Scilab works only on Scilab primitives
+    (Scilab function wrote in C) which must have a name which is maximum 8
+    char wide.</para>
+  </refsection>
+
+  <refsection>
+    <title>Examples</title>
+
+    <para>In this example, the C interface function takes one input parameters
+    and prints the integer corresponding to the type of the variable sent as
+    parameter in the Scilab console.</para>
+
+    <programlisting> 
+#include &lt;stack-c.h&gt;
+#include &lt;sciprint.h&gt;
+
+int sci_check_properties_2(char * fname)
+{
+  int m1,n1,l1;
+
+  CheckRhs(1,1);
+  CheckLhs(0,1) ;
+
+  switch(VarType(1)) 
+    {
+    case sci_matrix: 
+      GetRhsVar(1, "d", &amp;m1, &amp;n1, &amp;l1);
+      sciprint("1 is a scalar matrix\n");
+      break;
+    case sci_strings:
+      GetRhsVar(1, "c", &amp;m1, &amp;n1, &amp;l1);
+      sciprint("1 is a string\n");
+      break;
+    case sci_sparse:
+      sciprint("1 is a sparse trying to overload\n");
+      OverLoad(1);
+    }
+
+  LhsVar(1) = 0;
+
+  return 0;
+}
+ </programlisting>
+
+    <para>The builder.sce script look like this:</para>
+
+    <programlisting> 
+// This is the builder.sce 
+// must be run from this directory 
+
+lines(0);
+
+ilib_name  = 'lib_check_properties';
+
+files = ['check_properties.c'];
+
+libs  = [];
+
+table =['chprop2', 'sci_check_properties_2'];
+
+// We must be careful when we choose a scilab function name in case of overloading.
+// We Scilab name function must be 8 char max.
+
+ldflags = "";
+cflags  = "";
+fflags  = "";
+
+// do not modify below 
+// ----------------------------------------------
+ilib_build(ilib_name,table,files,libs,'Makelib',ldflags,cflags,fflags);
+ </programlisting>
+
+    <para>And now, an example of use of this new function:</para>
+
+    <programlisting> 
+chprop2([1,2,2]);
+chprop2('foo');
+
+// overload case 
+
+deff('[]=%sp_chprop2(sp)','disp(''sparse overloaded'')');
+chprop2(sparse([1,2,3]));
+ </programlisting>
+  </refsection>
+
+  <refsection>
+    <title>See Also</title>
+
+    <simplelist type="inline">
+      <member><link linkend="CheckColumn">CheckColumn</link></member>
+      <member><link linkend="CheckDims">CheckDims</link></member>
+      <member><link linkend="CheckRow">CheckRow</link></member>
+      <member><link linkend="CheckScalar">CheckScalar</link></member>
+      <member><link linkend="CheckVector">CheckVector</link></member>
+      <member><link linkend="CheckDimProp">CheckDimProp</link></member>
+      <member><link linkend="CheckLength">CheckLength</link></member>
+      <member><link linkend="CheckSameDims">CheckSameDims</link></member>
+      <member><link linkend="CheckSquare">CheckSquare</link></member>
+      <member><link linkend="How to check parameters">HowToCheckParameters</link></member>
+    </simplelist>
+  </refsection>
+</refentry>
diff --git a/scilab/modules/core/help/en_US/capi/get_optionals.xml b/scilab/modules/core/help/en_US/capi/get_optionals.xml
new file mode 100644 (file)
index 0000000..38f42c2
--- /dev/null
@@ -0,0 +1,148 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<refentry version="5.0-subset Scilab" xml:id="get_optionals" xml:lang="en"
+          xmlns="http://docbook.org/ns/docbook"
+          xmlns:xlink="http://www.w3.org/1999/xlink"
+          xmlns:svg="http://www.w3.org/2000/svg"
+          xmlns:mml="http://www.w3.org/1998/Math/MathML"
+          xmlns:html="http://www.w3.org/1999/xhtml"
+          xmlns:db="http://docbook.org/ns/docbook">
+  <refnamediv>
+    <refname>get_optionals</refname>
+
+    <refpurpose>C interface function which initialize the list of optional
+    parameters</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <title>Calling Sequence</title>
+
+    <synopsis>res get_optionals(fname, opts)</synopsis>
+  </refsynopsisdiv>
+
+  <refsection>
+    <title>Parameters</title>
+
+    <variablelist>
+      <varlistentry>
+        <term>fname</term>
+
+        <listitem>
+          <para>the name passed to the C interface. The name of the calling
+          function (of type char *) (input parameter)</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>opts</term>
+
+        <listitem>
+          <para>a C list of optional parameters</para>
+
+          <programlisting> 
+typedef struct rhs_opts__ {
+  int position ; // stack position : -1 if not present
+  char *name; // the name of the variable
+  char *type; // a Scilab type (like "d") representing the type of the variable
+  int m,n; // the size of the variable
+  unsigned long int l; // a pointer to the Scilab stack
+} rhs_opts;
+ </programlisting>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>res</term>
+
+        <listitem>
+          <para>if no optional parameters has been sent, the res = 0.
+          Otherwise, res = 1.</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+  </refsection>
+
+  <refsection>
+    <title>Description</title>
+
+    <para>C interface function which initialize the list of optional
+    parameters. You must include stack-c.h to benefit from this
+    function.</para>
+  </refsection>
+
+  <refsection>
+    <title>Examples</title>
+
+    <para>A more complete example is available in the directory
+    example/optional_parameters.</para>
+
+    <programlisting role="example"> 
+#include &lt;stack-c.h&gt;
+
+int sci_optional_parameters(char * fname)
+{ 
+  int m1,n1,l1;
+
+  // optional names must be stored in alphabetical order in opts
+  static rhs_opts opts[]= {{-1,"v1","d",0,0,0},
+                           {-1,"v2","d",0,0,0},
+                           {-1,NULL,NULL,0,0}};
+
+  int minrhs = 1, maxrhs = 1;
+  int minlhs = 1, maxlhs = 3;
+  int nopt, iopos, res;
+  char buffer_name[csiz]; // csiz used for character coding
+
+  nopt = NumOpt();
+
+  CheckRhs(minrhs,maxrhs+nopt);
+  CheckLhs(minlhs,maxlhs);
+
+  // first non optional argument
+  GetRhsVar( 1, "c", &amp;m1, &amp;n1, &amp;l1);
+  
+  if (get_optionals(fname,opts)==0) return 0;
+
+  sciprint("number of optional parameters = %d\n", NumOpt());
+  sciprint("first optional parameters = %d\n", FirstOpt());
+  sciprint("FindOpt(v1) = %d\n", FindOpt("v1", opts));
+  sciprint("FindOpt(v2) = %d\n", FindOpt("v2", opts));
+
+  if (IsOpt(1,buffer_name))
+    sciprint("parameter 1 is optional: %s\n", buffer_name);
+  if (IsOpt(2,buffer_name))
+    sciprint("parameter 2 is optional: %s\n", buffer_name);
+  if (IsOpt(3,buffer_name))
+    sciprint("parameter 3 is optional: %s\n", buffer_name);
+
+  return 0;
+}
+ </programlisting>
+  </refsection>
+
+  <refsection>
+    <title>See Also</title>
+
+    <simplelist type="inline">
+      <member><link linkend="CheckDims">CheckDims</link></member>
+
+      <member><link linkend="CheckRow">CheckRow</link></member>
+
+      <member><link linkend="CheckScalar">CheckScalar</link></member>
+
+      <member><link linkend="CheckVector">CheckVector</link></member>
+
+      <member><link linkend="OverLoad">CheckOverLoad</link></member>
+
+      <member><link linkend="CheckDimProp">CheckDimProp</link></member>
+
+      <member><link linkend="CheckLength">CheckLength</link></member>
+
+      <member><link linkend="CheckSameDims">CheckSameDims</link></member>
+
+      <member><link linkend="CheckSquare">CheckSquare</link></member>
+
+      <member><link
+      linkend="How to check parameters">HowToCheckParameters</link></member>
+    </simplelist>
+  </refsection>
+</refentry>