add new help pages and examples for CAPI
[scilab.git] / scilab / modules / core / help / en_US / capi / GetListRhsVar.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <refentry version="5.0-subset Scilab" xml:id="GetListRhsVar"
3           xmlns="http://docbook.org/ns/docbook"
4           xmlns:xlink="http://www.w3.org/1999/xlink"
5           xmlns:xi="http://www.w3.org/2001/XInclude"
6           xmlns:svg="http://www.w3.org/2000/svg"
7           xmlns:mml="http://www.w3.org/1998/Math/MathML"
8           xmlns:html="http://www.w3.org/1999/xhtml"
9           xmlns:db="http://docbook.org/ns/docbook">
10   <refnamediv>
11     <refname>GetListRhsVar</refname>
12
13     <refpurpose>a C interface function which allows to access a parameter
14     stored in a [mt]list transmitted to a Scilab function</refpurpose>
15   </refnamediv>
16
17   <refsynopsisdiv>
18     <title>Calling Sequence</title>
19
20     <synopsis>GetListRhsVar(StackPos,ListPos, Type, &amp;m_rows, &amp;n_cols, &amp;l_stack_pos);</synopsis>
21   </refsynopsisdiv>
22
23   <refsection>
24     <title>Parameters</title>
25
26     <variablelist>
27       <varlistentry>
28         <term>StackPos</term>
29
30         <listitem>
31           <para>the rank of the [mt]list to be accessed (input
32           parameter)</para>
33         </listitem>
34       </varlistentry>
35
36       <varlistentry>
37         <term>ListPos</term>
38
39         <listitem>
40           <para>the rank in the list of the variable to be accessed (input
41           parameter)</para>
42         </listitem>
43       </varlistentry>
44
45       <varlistentry>
46         <term>Type</term>
47
48         <listitem>
49           <para>the Scilab type of the variable to be accessed (input
50           parameter). Can be (see Scilab C Type for more informations):</para>
51
52           <itemizedlist>
53             <listitem>
54               <para>STRING_DATATYPE "c"</para>
55             </listitem>
56
57             <listitem>
58               <para>MATRIX_OF_STRING_DATATYPE "S"</para>
59             </listitem>
60
61             <listitem>
62               <para>MATRIX_OF_DOUBLE_DATATYPE "d"</para>
63             </listitem>
64
65             <listitem>
66               <para>MATRIX_OF_RATIONAL_DATATYPE "r"</para>
67             </listitem>
68
69             <listitem>
70               <para>MATRIX_OF_VARIABLE_SIZE_INTEGER_DATATYPE "I"</para>
71             </listitem>
72
73             <listitem>
74               <para>MATRIX_OF_INTEGER_DATATYPE "i"</para>
75             </listitem>
76
77             <listitem>
78               <para>MATRIX_OF_BOOLEAN_DATATYPE "b"</para>
79             </listitem>
80
81             <listitem>
82               <para>MATRIX_OF_COMPLEX_DATATYPE "z"</para>
83             </listitem>
84
85             <listitem>
86               <para>SPARSE_MATRIX_DATATYPE "s"</para>
87             </listitem>
88
89             <listitem>
90               <para>TYPED_LIST_DATATYPE "t"</para>
91             </listitem>
92
93             <listitem>
94               <para>MATRIX_ORIENTED_TYPED_LIST_DATATYPE "m"</para>
95             </listitem>
96
97             <listitem>
98               <para>SCILAB_POINTER_DATATYPE "p"</para>
99             </listitem>
100
101             <listitem>
102               <para>GRAPHICAL_HANDLE_DATATYPE "h"</para>
103             </listitem>
104
105             <listitem>
106               <para>EXTERNAL_DATATYPE "f"</para>
107             </listitem>
108
109             <listitem>
110               <para>MATRIX_OF_POLYNOMIAL_DATATYPE "x"</para>
111             </listitem>
112           </itemizedlist>
113         </listitem>
114       </varlistentry>
115
116       <varlistentry>
117         <term>m_rows</term>
118
119         <listitem>
120           <para>the number of lines of the accessed variable (output
121           parameter)</para>
122         </listitem>
123       </varlistentry>
124
125       <varlistentry>
126         <term>n_cols</term>
127
128         <listitem>
129           <para>the number of columns of the accessed variable (output
130           parameter)</para>
131         </listitem>
132       </varlistentry>
133
134       <varlistentry>
135         <term>l_stack_pos</term>
136
137         <listitem>
138           <para>the position on the stack of the accessed variable (output
139           parameter)</para>
140         </listitem>
141       </varlistentry>
142     </variablelist>
143   </refsection>
144
145   <refsection>
146     <title>Description</title>
147
148     <para>A C interface function which allows to access a parameter stored in
149     a [mt]list transmitted to a Scilab function</para>
150   </refsection>
151
152   <refsection>
153     <title>Examples</title>
154
155     <para>In this example, the function has one input parameter. It gets a
156     mlist and the prints some informations related to the content of the
157     mlist.</para>
158
159     <programlisting role="example"> 
160 #include &lt;stack-c.h&gt;
161 #include &lt;sciprint.h&gt;
162
163 int sci_print_list(char * fname)
164 {
165   int m_list_in, n_list_in, l_list_in;
166   int m_type,    n_type;
167   int m_var1,    n_var1,    l_var1;
168   int m_var2,    n_var2,    l_var2;
169   char ** LabelList = NULL;
170   
171   CheckRhs(1,1); // We accept only 1 parameter
172   
173   GetRhsVar(1,"m",&amp;m_list_in,&amp;n_list_in,&amp;l_list_in); // Get a mlist
174   
175   // Get the type and the name of the variables (the first element of the mlist)
176   GetListRhsVar(1,1,"S",&amp;m_type,&amp;n_type,&amp;LabelList);
177   
178   if (strcmp(LabelList[0],"mytype")!=0)
179     {
180       sciprint("error, you must ship a mlist or type mytype\n");
181       return 0;
182     }
183     
184   // Get the first variable (a string)
185   GetListRhsVar(1,2,"c",&amp;m_var1,&amp;n_var1,&amp;l_var1);
186   sciprint("var1 = %s\n",cstk(l_var1));
187   
188   // Get the second variable (a double matrix)
189   GetListRhsVar(1,3,"d",&amp;m_var2,&amp;n_var2,&amp;l_var2);
190   sciprint("var2 = [%f %f %f %f]\n",*stk(l_var2+0),
191                                     *stk(l_var2+1),
192                                     *stk(l_var2+2),
193                                     *stk(l_var2+3));
194     
195   return 0;
196 }
197  </programlisting>
198
199     <para>This example is available in example/print_list.</para>
200
201   </refsection>
202
203   <refsection>
204     <title>See Also</title>
205
206     <simplelist type="inline">
207       <member><link linkend="ScilabCTypes">Scilab C Type</link></member>
208
209       <member><link linkend="istk">istk</link></member>
210
211       <member><link linkend="LhsVar">LhsVar</link></member>
212     </simplelist>
213   </refsection>
214 </refentry>