add new help pages and examples for CAPI
Yann COLLETTE [Wed, 29 Apr 2009 19:34:51 +0000 (21:34 +0200)]
scilab/modules/core/examples/capi/create_list/builder.sce [new file with mode: 0755]
scilab/modules/core/examples/capi/create_list/create_list.c [new file with mode: 0755]
scilab/modules/core/examples/capi/print_list/builder.sce [new file with mode: 0755]
scilab/modules/core/examples/capi/print_list/print_list.c [new file with mode: 0755]
scilab/modules/core/help/en_US/capi/CreateListVarFrom.xml [new file with mode: 0755]
scilab/modules/core/help/en_US/capi/CreateListVarFromPtr.xml [new file with mode: 0755]
scilab/modules/core/help/en_US/capi/GetListRhsVar.xml [new file with mode: 0755]
scilab/modules/core/help/en_US/capi/HowToCreateAndAccessAList_1.xml [new file with mode: 0755]

diff --git a/scilab/modules/core/examples/capi/create_list/builder.sce b/scilab/modules/core/examples/capi/create_list/builder.sce
new file mode 100755 (executable)
index 0000000..0f1fbac
--- /dev/null
@@ -0,0 +1,20 @@
+// This is the builder.sce 
+// must be run from this directory 
+
+lines(0);
+
+ilib_name  = 'lib_create_list';
+
+files = ['create_list.c'];
+
+libs  = [];
+
+table =['create_list', 'sci_create_list'];
+
+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/create_list/create_list.c b/scilab/modules/core/examples/capi/create_list/create_list.c
new file mode 100755 (executable)
index 0000000..ba8d1ab
--- /dev/null
@@ -0,0 +1,52 @@
+#include <stack-c.h>
+#include <string.h>
+
+int sci_create_list(char * fname)
+{
+  int m_list_out, n_list_out;
+  int m_var1,     n_var1,     l_var1,  l_list_var1;
+  int m_var2,     n_var2,     l_var2,  l_list_var2;
+  int m_mlist,    n_mlist,    l_mlist;
+  // The labels of our mlist 
+  static const char * ListLabels [] = {"mylist","var1","var2"};
+
+  // First, we create the variables using a classical way
+  // The size of the Scilab variables
+  m_var1  = 1; n_var1  = strlen("a string")+1; // a null terminated string
+  m_var2  = 2; n_var2  = 2; // A 2x2 double matrix
+  m_mlist = 3; n_mlist = 1; // A mlist with 3 elements
+  
+  // Creation of the Scilab variables
+  // A('var1')
+  CreateVar(1, "c", &m_var1,  &n_var1,  &l_var1);
+  // A('var2')
+  CreateVar(2, "d", &m_var2,  &n_var2,  &l_var2);
+  // A
+  CreateVar(3, "m", &m_mlist, &n_mlist, &l_mlist);
+  
+  // We store values in the create variables
+  // The matrix will be stored in A('var2')
+  *stk(l_var2+0) = 1;              
+  *stk(l_var2+1) = 2;              
+  *stk(l_var2+2) = 3;              
+  *stk(l_var2+3) = 4;              
+  
+  // The string will be stored in A('var1')
+  strncpy(cstk(l_var1),"a string\0",n_var1);
+  
+  m_list_out = 3; n_list_out = 1;
+  
+  // now, affect the variable  to the mlist
+  // The labels (it corresponds to A = mlist(['mylist','var1','var2'], ...
+  CreateListVarFromPtr(3, 1, "S", &m_list_out, &n_list_out, ListLabels);
+  // The value stored in A('var1') (it corresponds to A = ...,'a string', ...
+  CreateListVarFrom(3, 2, "c", &m_var1, &n_var1, &l_list_var1, &l_var1);
+  // The value stored in A('var2') (it corresponds to A = ...,[1 2,3 4]);
+  CreateListVarFrom(3, 3, "d", &m_var2, &n_var2, &l_list_var2, &l_var2);
+  
+  // We return only the mlist which has been created at position 3
+  LhsVar(1) = 3;
+  
+  return 0;
+}
diff --git a/scilab/modules/core/examples/capi/print_list/builder.sce b/scilab/modules/core/examples/capi/print_list/builder.sce
new file mode 100755 (executable)
index 0000000..1df88c1
--- /dev/null
@@ -0,0 +1,20 @@
+// This is the builder.sce 
+// must be run from this directory 
+
+lines(0);
+
+ilib_name  = 'lib_print_list';
+
+files = ['print_list.c'];
+
+libs  = [];
+
+table =['print_list', 'sci_print_list'];
+
+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/print_list/print_list.c b/scilab/modules/core/examples/capi/print_list/print_list.c
new file mode 100755 (executable)
index 0000000..b4cbd96
--- /dev/null
@@ -0,0 +1,37 @@
+#include <stack-c.h>
+#include <sciprint.h>
+
+int sci_print_list(char * fname)
+{
+  int m_list_in, n_list_in, l_list_in;
+  int m_type,    n_type;
+  int m_var1,    n_var1,    l_var1;
+  int m_var2,    n_var2,    l_var2;
+  char ** LabelList = NULL;
+  
+  CheckRhs(1,1); // We accept only 1 parameter
+  
+  GetRhsVar(1,"m",&m_list_in,&n_list_in,&l_list_in); // Get a mlist
+  
+  // Get the type and the name of the variables (the first element of the mlist)
+  GetListRhsVar(1,1,"S",&m_type,&n_type,&LabelList);
+  
+  if (strcmp(LabelList[0],"mytype")!=0)
+    {
+      sciprint("error, you must ship a mlist or type mytype\n");
+      return 0;
+    }
+    
+  // Get the first variable (a string)
+  GetListRhsVar(1,2,"c",&m_var1,&n_var1,&l_var1);
+  sciprint("var1 = %s\n",cstk(l_var1));
+  
+  // Get the second variable (a double matrix)
+  GetListRhsVar(1,3,"d",&m_var2,&n_var2,&l_var2);
+  sciprint("var2 = [%f %f %f %f]\n",*stk(l_var2+0),
+                                    *stk(l_var2+1),
+                                    *stk(l_var2+2),
+                                    *stk(l_var2+3));
+    
+  return 0;
+}
diff --git a/scilab/modules/core/help/en_US/capi/CreateListVarFrom.xml b/scilab/modules/core/help/en_US/capi/CreateListVarFrom.xml
new file mode 100755 (executable)
index 0000000..b3f439f
--- /dev/null
@@ -0,0 +1,227 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<refentry version="5.0-subset Scilab" xml:id="CreateListVarFrom"
+          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>CreateListVarFrom</refname>
+
+    <refpurpose>a C interface function which allows to create a new Scilab
+    variable in a [mt]list</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <title>Calling Sequence</title>
+
+    <synopsis>CreateListVarFrom(StackPos,Type, &amp;m_rows, &amp;n_cols, &amp;l_stack_list_pos, &amp;l_stack_pos);</synopsis>
+  </refsynopsisdiv>
+
+  <refsection>
+    <title>Parameters</title>
+
+    <variablelist>
+      <varlistentry>
+        <term>StackPos</term>
+
+        <listitem>
+          <para>the rank of the variable to be created (input
+          parameter)</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>Type</term>
+
+        <listitem>
+          <para>the Scilab type of the variable to be created (input
+          parameter). Can be (see Scilab C Type for more informations):</para>
+
+          <itemizedlist>
+            <listitem>
+              <para>STRING_DATATYPE "c"</para>
+            </listitem>
+
+            <listitem>
+              <para>MATRIX_OF_STRING_DATATYPE "S"</para>
+            </listitem>
+
+            <listitem>
+              <para>MATRIX_OF_DOUBLE_DATATYPE "d"</para>
+            </listitem>
+
+            <listitem>
+              <para>MATRIX_OF_RATIONAL_DATATYPE "r"</para>
+            </listitem>
+
+            <listitem>
+              <para>MATRIX_OF_VARIABLE_SIZE_INTEGER_DATATYPE "I"</para>
+            </listitem>
+
+            <listitem>
+              <para>MATRIX_OF_INTEGER_DATATYPE "i"</para>
+            </listitem>
+
+            <listitem>
+              <para>MATRIX_OF_BOOLEAN_DATATYPE "b"</para>
+            </listitem>
+
+            <listitem>
+              <para>MATRIX_OF_COMPLEX_DATATYPE "z"</para>
+            </listitem>
+
+            <listitem>
+              <para>SPARSE_MATRIX_DATATYPE "s"</para>
+            </listitem>
+
+            <listitem>
+              <para>TYPED_LIST_DATATYPE "t"</para>
+            </listitem>
+
+            <listitem>
+              <para>MATRIX_ORIENTED_TYPED_LIST_DATATYPE "m"</para>
+            </listitem>
+
+            <listitem>
+              <para>SCILAB_POINTER_DATATYPE "p"</para>
+            </listitem>
+
+            <listitem>
+              <para>GRAPHICAL_HANDLE_DATATYPE "h"</para>
+            </listitem>
+
+            <listitem>
+              <para>EXTERNAL_DATATYPE "f"</para>
+            </listitem>
+
+            <listitem>
+              <para>MATRIX_OF_POLYNOMIAL_DATATYPE "x"</para>
+            </listitem>
+          </itemizedlist>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>m_rows</term>
+
+        <listitem>
+          <para>the number of lines of the matrix to be created (input
+          parameter)</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>n_cols</term>
+
+        <listitem>
+          <para>the number of columns of the matrix to be created (input
+          parameter)</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>l_stack_list_pos</term>
+
+        <listitem>
+          <para>the position on the stack of the created variable in the
+          list(output parameter)</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>l_stack_pos</term>
+
+        <listitem>
+          <para>the position on the stack of the created variable (input
+          parameter)</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+  </refsection>
+
+  <refsection>
+    <title>Description</title>
+
+    <para>A C interface function which allows to create a new Scilab variable
+    in a [mt]list</para>
+  </refsection>
+
+  <refsection>
+    <title>Examples</title>
+
+    <programlisting role="example"> 
+#include &lt;stack-c.h&gt;
+#include &lt;string.h&gt;
+
+int sci_create_list(char * fname)
+{
+  int m_list_out, n_list_out;
+  int m_var1,     n_var1,     l_var1,  l_list_var1;
+  int m_var2,     n_var2,     l_var2,  l_list_var2;
+  int m_mlist,    n_mlist,    l_mlist;
+  // The labels of our mlist 
+  static const char * ListLabels [] = {"mylist","var1","var2"};
+
+  // First, we create the variables using a classical way
+  // The size of the Scilab variables
+  m_var1  = 1; n_var1  = strlen("a string")+1; // a null terminated string
+  m_var2  = 2; n_var2  = 2; // A 2x2 double matrix
+  m_mlist = 3; n_mlist = 1; // A mlist with 3 elements
+  
+  // Creation of the Scilab variables
+  // A('var1')
+  CreateVar(1, "c", &amp;m_var1,  &amp;n_var1,  &amp;l_var1);
+  // A('var2')
+  CreateVar(2, "d", &amp;m_var2,  &amp;n_var2,  &amp;l_var2);
+  // A
+  CreateVar(3, "m", &amp;m_mlist, &amp;n_mlist, &amp;l_mlist);
+  
+  // We store values in the create variables
+  // The matrix will be stored in A('var2')
+  *stk(l_var2+0) = 1;              
+  *stk(l_var2+1) = 2;              
+  *stk(l_var2+2) = 3;              
+  *stk(l_var2+3) = 4;              
+  
+  // The string will be stored in A('var1')
+  strncpy(cstk(l_var1),"a string\0",n_var1);
+  
+  m_list_out = 3; n_list_out = 1;
+  
+  // now, affect the variable  to the mlist
+  // The labels (it corresponds to A = mlist(['mylist','var1','var2'], ...
+  CreateListVarFromPtr(3, 1, "S", &amp;m_list_out, &amp;n_list_out, ListLabels);
+  // The value stored in A('var1') (it corresponds to A = ...,'a string', ...
+  CreateListVarFrom(3, 2, "c", &amp;m_var1, &amp;n_var1, &amp;l_list_var1, &amp;l_var1);
+  // The value stored in A('var2') (it corresponds to A = ...,[1 2,3 4]);
+  CreateListVarFrom(3, 3, "d", &amp;m_var2, &amp;n_var2, &amp;l_list_var2, &amp;l_var2);
+  
+  // We return only the mlist which has been created at position 3
+  LhsVar(1) = 3;
+  
+  return 0;
+}
+ </programlisting>
+
+    <para>This example is available in example/create_list.</para>
+
+  </refsection>
+
+  <refsection>
+    <title>See Also</title>
+
+    <simplelist type="inline">
+      <member><link linkend="ScilabCTypes">Scilab C Type</link></member>
+
+      <member><link linkend="istk">istk</link></member>
+
+      <member><link linkend="LhsVar">LhsVar</link></member>
+
+      <member><link linkend="CreateVar">CreateVar</link></member>
+    </simplelist>
+  </refsection>
+</refentry>
diff --git a/scilab/modules/core/help/en_US/capi/CreateListVarFromPtr.xml b/scilab/modules/core/help/en_US/capi/CreateListVarFromPtr.xml
new file mode 100755 (executable)
index 0000000..f252f5a
--- /dev/null
@@ -0,0 +1,226 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<refentry version="5.0-subset Scilab" xml:id="CreateListVarFromPtr"
+          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>CreateListVarFromPtr</refname>
+
+    <refpurpose>a C interface function which allows to create a new Scilab
+    variable from a pointer in a [mt]list</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <title>Calling Sequence</title>
+
+    <synopsis>CreateListVarFrom(StackPos, Type, &amp;m_rows, &amp;n_cols, &amp;l_stack_list_pos, void * Pointer);</synopsis>
+  </refsynopsisdiv>
+
+  <refsection>
+    <title>Parameters</title>
+
+    <variablelist>
+      <varlistentry>
+        <term>StackPos</term>
+
+        <listitem>
+          <para>the rank of the variable to be created (input
+          parameter)</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>Type</term>
+
+        <listitem>
+          <para>the Scilab type of the variable to be created (input
+          parameter). Can be (see Scilab C Type for more informations):</para>
+
+          <itemizedlist>
+            <listitem>
+              <para>STRING_DATATYPE "c"</para>
+            </listitem>
+
+            <listitem>
+              <para>MATRIX_OF_STRING_DATATYPE "S"</para>
+            </listitem>
+
+            <listitem>
+              <para>MATRIX_OF_DOUBLE_DATATYPE "d"</para>
+            </listitem>
+
+            <listitem>
+              <para>MATRIX_OF_RATIONAL_DATATYPE "r"</para>
+            </listitem>
+
+            <listitem>
+              <para>MATRIX_OF_VARIABLE_SIZE_INTEGER_DATATYPE "I"</para>
+            </listitem>
+
+            <listitem>
+              <para>MATRIX_OF_INTEGER_DATATYPE "i"</para>
+            </listitem>
+
+            <listitem>
+              <para>MATRIX_OF_BOOLEAN_DATATYPE "b"</para>
+            </listitem>
+
+            <listitem>
+              <para>MATRIX_OF_COMPLEX_DATATYPE "z"</para>
+            </listitem>
+
+            <listitem>
+              <para>SPARSE_MATRIX_DATATYPE "s"</para>
+            </listitem>
+
+            <listitem>
+              <para>TYPED_LIST_DATATYPE "t"</para>
+            </listitem>
+
+            <listitem>
+              <para>MATRIX_ORIENTED_TYPED_LIST_DATATYPE "m"</para>
+            </listitem>
+
+            <listitem>
+              <para>SCILAB_POINTER_DATATYPE "p"</para>
+            </listitem>
+
+            <listitem>
+              <para>GRAPHICAL_HANDLE_DATATYPE "h"</para>
+            </listitem>
+
+            <listitem>
+              <para>EXTERNAL_DATATYPE "f"</para>
+            </listitem>
+
+            <listitem>
+              <para>MATRIX_OF_POLYNOMIAL_DATATYPE "x"</para>
+            </listitem>
+          </itemizedlist>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>m_rows</term>
+
+        <listitem>
+          <para>the number of lines of the matrix to be created (input
+          parameter)</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>n_cols</term>
+
+        <listitem>
+          <para>the number of columns of the matrix to be created (input
+          parameter)</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>l_stack_list_pos</term>
+
+        <listitem>
+          <para>the position on the stack of the created variable in the list
+          (output parameter)</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>Pointer</term>
+
+        <listitem>
+          <para>the pointer to the data area (input parameter)</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+  </refsection>
+
+  <refsection>
+    <title>Description</title>
+
+    <para>A C interface function which allows to create a new Scilab variable
+    from a pointer in a [mt]list</para>
+  </refsection>
+
+  <refsection>
+    <title>Examples</title>
+
+    <programlisting role="example"> 
+#include &lt;stack-c.h&gt;
+#include &lt;string.h&gt;
+
+int sci_create_list(char * fname)
+{
+  int m_list_out, n_list_out;
+  int m_var1,     n_var1,     l_var1,  l_list_var1;
+  int m_var2,     n_var2,     l_var2,  l_list_var2;
+  int m_mlist,    n_mlist,    l_mlist;
+  // The labels of our mlist 
+  static const char * ListLabels [] = {"mylist","var1","var2"};
+
+  // First, we create the variables using a classical way
+  // The size of the Scilab variables
+  m_var1  = 1; n_var1  = strlen("a string")+1; // a null terminated string
+  m_var2  = 2; n_var2  = 2; // A 2x2 double matrix
+  m_mlist = 3; n_mlist = 1; // A mlist with 3 elements
+  
+  // Creation of the Scilab variables
+  // A('var1')
+  CreateVar(1, "c", &amp;m_var1,  &amp;n_var1,  &amp;l_var1);
+  // A('var2')
+  CreateVar(2, "d", &amp;m_var2,  &amp;n_var2,  &amp;l_var2);
+  // A
+  CreateVar(3, "m", &amp;m_mlist, &amp;n_mlist, &amp;l_mlist);
+  
+  // We store values in the create variables
+  // The matrix will be stored in A('var2')
+  *stk(l_var2+0) = 1;              
+  *stk(l_var2+1) = 2;              
+  *stk(l_var2+2) = 3;              
+  *stk(l_var2+3) = 4;              
+  
+  // The string will be stored in A('var1')
+  strncpy(cstk(l_var1),"a string\0",n_var1);
+  
+  m_list_out = 3; n_list_out = 1;
+  
+  // now, affect the variable  to the mlist
+  // The labels (it corresponds to A = mlist(['mylist','var1','var2'], ...
+  CreateListVarFromPtr(3, 1, "S", &amp;m_list_out, &amp;n_list_out, ListLabels);
+  // The value stored in A('var1') (it corresponds to A = ...,'a string', ...
+  CreateListVarFrom(3, 2, "c", &amp;m_var1, &amp;n_var1, &amp;l_list_var1, &amp;l_var1);
+  // The value stored in A('var2') (it corresponds to A = ...,[1 2,3 4]);
+  CreateListVarFrom(3, 3, "d", &amp;m_var2, &amp;n_var2, &amp;l_list_var2, &amp;l_var2);
+  
+  // We return only the mlist which has been created at position 3
+  LhsVar(1) = 3;
+  
+  return 0;
+}
+ </programlisting>
+
+    <para>This example is available in example/create_list.</para>
+
+  </refsection>
+
+  <refsection>
+    <title>See Also</title>
+
+    <simplelist type="inline">
+      <member><link linkend="ScilabCTypes">Scilab C Type</link></member>
+
+      <member><link linkend="istk">istk</link></member>
+
+      <member><link linkend="LhsVar">LhsVar</link></member>
+
+      <member><link linkend="CreateVar">CreateVar</link></member>
+    </simplelist>
+  </refsection>
+</refentry>
diff --git a/scilab/modules/core/help/en_US/capi/GetListRhsVar.xml b/scilab/modules/core/help/en_US/capi/GetListRhsVar.xml
new file mode 100755 (executable)
index 0000000..aef60df
--- /dev/null
@@ -0,0 +1,214 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<refentry version="5.0-subset Scilab" xml:id="GetListRhsVar"
+          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>GetListRhsVar</refname>
+
+    <refpurpose>a C interface function which allows to access a parameter
+    stored in a [mt]list transmitted to a Scilab function</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <title>Calling Sequence</title>
+
+    <synopsis>GetListRhsVar(StackPos,ListPos, Type, &amp;m_rows, &amp;n_cols, &amp;l_stack_pos);</synopsis>
+  </refsynopsisdiv>
+
+  <refsection>
+    <title>Parameters</title>
+
+    <variablelist>
+      <varlistentry>
+        <term>StackPos</term>
+
+        <listitem>
+          <para>the rank of the [mt]list to be accessed (input
+          parameter)</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>ListPos</term>
+
+        <listitem>
+          <para>the rank in the list of the variable to be accessed (input
+          parameter)</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>Type</term>
+
+        <listitem>
+          <para>the Scilab type of the variable to be accessed (input
+          parameter). Can be (see Scilab C Type for more informations):</para>
+
+          <itemizedlist>
+            <listitem>
+              <para>STRING_DATATYPE "c"</para>
+            </listitem>
+
+            <listitem>
+              <para>MATRIX_OF_STRING_DATATYPE "S"</para>
+            </listitem>
+
+            <listitem>
+              <para>MATRIX_OF_DOUBLE_DATATYPE "d"</para>
+            </listitem>
+
+            <listitem>
+              <para>MATRIX_OF_RATIONAL_DATATYPE "r"</para>
+            </listitem>
+
+            <listitem>
+              <para>MATRIX_OF_VARIABLE_SIZE_INTEGER_DATATYPE "I"</para>
+            </listitem>
+
+            <listitem>
+              <para>MATRIX_OF_INTEGER_DATATYPE "i"</para>
+            </listitem>
+
+            <listitem>
+              <para>MATRIX_OF_BOOLEAN_DATATYPE "b"</para>
+            </listitem>
+
+            <listitem>
+              <para>MATRIX_OF_COMPLEX_DATATYPE "z"</para>
+            </listitem>
+
+            <listitem>
+              <para>SPARSE_MATRIX_DATATYPE "s"</para>
+            </listitem>
+
+            <listitem>
+              <para>TYPED_LIST_DATATYPE "t"</para>
+            </listitem>
+
+            <listitem>
+              <para>MATRIX_ORIENTED_TYPED_LIST_DATATYPE "m"</para>
+            </listitem>
+
+            <listitem>
+              <para>SCILAB_POINTER_DATATYPE "p"</para>
+            </listitem>
+
+            <listitem>
+              <para>GRAPHICAL_HANDLE_DATATYPE "h"</para>
+            </listitem>
+
+            <listitem>
+              <para>EXTERNAL_DATATYPE "f"</para>
+            </listitem>
+
+            <listitem>
+              <para>MATRIX_OF_POLYNOMIAL_DATATYPE "x"</para>
+            </listitem>
+          </itemizedlist>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>m_rows</term>
+
+        <listitem>
+          <para>the number of lines of the accessed variable (output
+          parameter)</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>n_cols</term>
+
+        <listitem>
+          <para>the number of columns of the accessed variable (output
+          parameter)</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>l_stack_pos</term>
+
+        <listitem>
+          <para>the position on the stack of the accessed variable (output
+          parameter)</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+  </refsection>
+
+  <refsection>
+    <title>Description</title>
+
+    <para>A C interface function which allows to access a parameter stored in
+    a [mt]list transmitted to a Scilab function</para>
+  </refsection>
+
+  <refsection>
+    <title>Examples</title>
+
+    <para>In this example, the function has one input parameter. It gets a
+    mlist and the prints some informations related to the content of the
+    mlist.</para>
+
+    <programlisting role="example"> 
+#include &lt;stack-c.h&gt;
+#include &lt;sciprint.h&gt;
+
+int sci_print_list(char * fname)
+{
+  int m_list_in, n_list_in, l_list_in;
+  int m_type,    n_type;
+  int m_var1,    n_var1,    l_var1;
+  int m_var2,    n_var2,    l_var2;
+  char ** LabelList = NULL;
+  
+  CheckRhs(1,1); // We accept only 1 parameter
+  
+  GetRhsVar(1,"m",&amp;m_list_in,&amp;n_list_in,&amp;l_list_in); // Get a mlist
+  
+  // Get the type and the name of the variables (the first element of the mlist)
+  GetListRhsVar(1,1,"S",&amp;m_type,&amp;n_type,&amp;LabelList);
+  
+  if (strcmp(LabelList[0],"mytype")!=0)
+    {
+      sciprint("error, you must ship a mlist or type mytype\n");
+      return 0;
+    }
+    
+  // Get the first variable (a string)
+  GetListRhsVar(1,2,"c",&amp;m_var1,&amp;n_var1,&amp;l_var1);
+  sciprint("var1 = %s\n",cstk(l_var1));
+  
+  // Get the second variable (a double matrix)
+  GetListRhsVar(1,3,"d",&amp;m_var2,&amp;n_var2,&amp;l_var2);
+  sciprint("var2 = [%f %f %f %f]\n",*stk(l_var2+0),
+                                    *stk(l_var2+1),
+                                    *stk(l_var2+2),
+                                    *stk(l_var2+3));
+    
+  return 0;
+}
+ </programlisting>
+
+    <para>This example is available in example/print_list.</para>
+
+  </refsection>
+
+  <refsection>
+    <title>See Also</title>
+
+    <simplelist type="inline">
+      <member><link linkend="ScilabCTypes">Scilab C Type</link></member>
+
+      <member><link linkend="istk">istk</link></member>
+
+      <member><link linkend="LhsVar">LhsVar</link></member>
+    </simplelist>
+  </refsection>
+</refentry>
diff --git a/scilab/modules/core/help/en_US/capi/HowToCreateAndAccessAList_1.xml b/scilab/modules/core/help/en_US/capi/HowToCreateAndAccessAList_1.xml
new file mode 100755 (executable)
index 0000000..02e25a3
--- /dev/null
@@ -0,0 +1,341 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<refentry version="5.0-subset Scilab" xml:id="HowToCreateAndAccessAList_1"
+          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 create and access a list</refname>
+
+    <refpurpose>How to create and access a list using the C API</refpurpose>
+  </refnamediv>
+
+  <refsection>
+    <title>Description</title>
+
+    <para>The goal is to get a [mt]list, to get some elements stored in that
+    this and to send a new [mt]list using a function written in C.</para>
+
+    <para>For this, we will wrote 2 C gateway function in which we will
+    retrieve the [mt]list, and we will create a new [mt]list.</para>
+  </refsection>
+
+  <refsection>
+    <title>The C function - access to a [mt]list</title>
+
+    <para>This example is available in example/print_list.</para>
+
+    <para>Let's initialize a mlist in Scilab.</para>
+
+    <programlisting> 
+A = mlist(['mytype','var1','var2'],'a string',[1 2; 3 4]);
+ </programlisting>
+
+    <para>This mlist is of type 'mytype' (typeof(A)=='mytype') and it has 2
+    elements:</para>
+
+    <itemizedlist>
+      <listitem>
+        <para>A('var1') which is equal to 'a string'</para>
+      </listitem>
+
+      <listitem>
+        <para>A('var2') which is equal to [1 2; 3 4]</para>
+      </listitem>
+    </itemizedlist>
+
+    <para>We now create a C function called sci_print_list which will print
+    the elements stored in the list.</para>
+
+    <programlisting> 
+#include &lt;stack-c.h&gt;
+#include &lt;sciprint.h&gt;
+
+int sci_print_list(char * fname)
+{
+  int m_list_in, n_list_in, l_list_in;
+  int m_type,    n_type;
+  int m_var1,    n_var1,    l_var1;
+  int m_var2,    n_var2,    l_var2;
+  char ** LabelList = NULL;
+  
+  CheckRhs(1,1); // We accept only 1 parameter
+  
+  GetRhsVar(1,"m",&amp;m_list_in,&amp;n_list_in,&amp;l_list_in); // Get a mlist
+  
+  // Get the type and the name of the variables (the first element of the mlist)
+  GetListRhsVar(1,1,"S",&amp;m_type,&amp;n_type,&amp;LabelList);
+  
+  if (strcmp(LabelList[0],"mytype")!=0)
+    {
+      sciprint("error, you must ship a mlist or type mytype\n");
+      return 0;
+    }
+    
+  // Get the first variable (a string)
+  GetListRhsVar(1,2,"c",&amp;m_var1,&amp;n_var1,&amp;l_var1);
+  sciprint("var1 = %s\n",cstk(l_var1));
+  
+  // Get the second variable (a double matrix)
+  GetListRhsVar(1,3,"d",&amp;m_var2,&amp;n_var2,&amp;l_var2);
+  sciprint("var2 = [%f %f %f %f]\n",*stk(l_var2+0),
+                                    *stk(l_var2+1),
+                                    *stk(l_var2+2),
+                                    *stk(l_var2+3));
+    
+  return 0;
+}
+ </programlisting>
+
+    <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. The C
+    file is available in the example directory. It is named
+    print_list.c.</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_print_list';
+
+files = ['print_list.c'];
+
+libs  = [];
+
+table =['print_list', 'sci_print_list'];
+
+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 print_list.c), what will be the name of the shared library (here,
+    it's lib_print_list) and which C symbol will be linked to a Scilab
+    function (here, we will link the sci_print_list C symbol to the Scilab
+    function "print_list").</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. Let's test our new function:</para>
+
+    <programlisting> 
+exec builder.sce;
+exec loader.sce;
+
+A = mlist(['mytype','var1','var2'],'a string',[1 2; 3 4]);
+print_list(A);
+ </programlisting>
+  </refsection>
+
+  <refsection>
+    <title>The C function - creation of a [mt]list</title>
+
+    <para>This example is available in example/create_list.</para>
+
+    <para>We now write a simple example to test our new function to create a
+    [mt]list.</para>
+
+    <programlisting> 
+A = create_list();
+
+disp(A);
+ </programlisting>
+
+    <para>First, let's write the C function:</para>
+
+    <programlisting> 
+#include &lt;stack-c.h&gt;
+#include &lt;string.h&gt;
+
+int sci_create_list(char * fname)
+{
+  int m_list_out, n_list_out;
+  int m_var1,     n_var1,     l_var1,  l_list_var1;
+  int m_var2,     n_var2,     l_var2,  l_list_var2;
+  int m_mlist,    n_mlist,    l_mlist;
+  // The labels of our mlist 
+  static const char * ListLabels [] = {"mylist","var1","var2"};
+
+  // First, we create the variables using a classical way
+  // The size of the Scilab variables
+  m_var1  = 1; n_var1  = strlen("a string")+1; // a null terminated string
+  m_var2  = 2; n_var2  = 2; // A 2x2 double matrix
+  m_mlist = 3; n_mlist = 1; // A mlist with 3 elements
+  
+  // Creation of the Scilab variables
+  // A('var1')
+  CreateVar(1, "c", &amp;m_var1,  &amp;n_var1,  &amp;l_var1);
+  // A('var2')
+  CreateVar(2, "d", &amp;m_var2,  &amp;n_var2,  &amp;l_var2);
+  // A
+  CreateVar(3, "m", &amp;m_mlist, &amp;n_mlist, &amp;l_mlist);
+  
+  // We store values in the create variables
+  // The matrix will be stored in A('var2')
+  *stk(l_var2+0) = 1;              
+  *stk(l_var2+1) = 2;              
+  *stk(l_var2+2) = 3;              
+  *stk(l_var2+3) = 4;              
+  
+  // The string will be stored in A('var1')
+  strncpy(cstk(l_var1),"a string\0",n_var1);
+  
+  m_list_out = 3; n_list_out = 1;
+  
+  // now, affect the variable  to the mlist
+  // The labels (it corresponds to A = mlist(['mylist','var1','var2'], ...
+  CreateListVarFromPtr(3, 1, "S", &amp;m_list_out, &amp;n_list_out, ListLabels);
+  // The value stored in A('var1') (it corresponds to A = ...,'a string', ...
+  CreateListVarFrom(3, 2, "c", &amp;m_var1, &amp;n_var1, &amp;l_list_var1, &amp;l_var1);
+  // The value stored in A('var2') (it corresponds to A = ...,[1 2,3 4]);
+  CreateListVarFrom(3, 3, "d", &amp;m_var2, &amp;n_var2, &amp;l_list_var2, &amp;l_var2);
+  
+  // We return only the mlist which has been created at position 3
+  LhsVar(1) = 3;
+  
+  return 0;
+}
+ </programlisting>
+
+    <para>Some important comments related to the CreateVar(Pos,"m",&amp;m,
+    &amp;n, &amp;l) function. When called on a mlist, only the m parameter is
+    taken in account, the n parameter is not used. So, be careful:</para>
+
+    <programlisting> 
+m_list = 3; n_list = 1;
+CreateVar(1, "m", &amp;m_list, &amp;n_list, &amp;l_list);
+ </programlisting>
+
+    <para>creates a mlist with 3 elements but:</para>
+
+    <programlisting> 
+m_list = 1; n_list = 3;
+CreateVar(1, "m", &amp;m_list, &amp;n_list, &amp;l_list);
+ </programlisting>
+
+    <para>creates a mlist with only 1 element !</para>
+
+    <para>Another important thing: when we create a list element using
+    CreateListVarFrom, it is not recommended to access the created variable
+    using, for example, stk(l_list_var2) because CreateListVarFrom performs
+    type transformation on the list variables.</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_create_list';
+
+files = ['create_list.c'];
+
+libs  = [];
+
+table =['create_list', 'sci_create_list'];
+
+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 create_list.c), what will be the name of the shared library (here,
+    it's lib_create_list) and which C symbol will be linked to a Scilab
+    function (here, we will link the sci_create_list C symbol to the Scilab
+    function "create_list").</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. Let's test our new function:</para>
+
+    <programlisting> 
+exec builder.sce;
+exec loader.sce;
+
+A = create_list();
+disp(typeof(A))
+disp(getfield(1,A))
+disp(A('var1'))
+disp(A('var2'))
+ </programlisting>
+  </refsection>
+
+  <refsection>
+    <title>See Also</title>
+
+    <simplelist type="inline">
+      <member><link linkend="GetRhsVar">GetRhsVar</link></member>
+
+      <member><link linkend="GetListRhsVar">GetListRhsVar</link></member>
+
+      <member><link linkend="CreateVar">CreateVar</link></member>
+
+      <member><link
+      linkend="CreateListVarFrom">CreateListVarFrom</link></member>
+
+      <member><link
+      linkend="CreateListVarFromPtr">CreateListVarFromPtr</link></member>
+
+      <member><link linkend="LhsVar">LhsVar</link></member>
+
+      <member><link linkend="stk">stk</link></member>
+
+      <member><link linkend="ilib_build">ilib_build</link></member>
+    </simplelist>
+  </refsection>
+</refentry>