add more help pages related to CAPI - check parameters - optional parameters
[scilab.git] / scilab / modules / core / help / en_US / capi / HowToCheckParameters.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <refentry version="5.0-subset Scilab" xml:id="HowToCheckParameters"
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>How to check parameters</refname>
12
13     <refpurpose>how to check parameter send to an interface using the C
14     API</refpurpose>
15   </refnamediv>
16
17   <refsection>
18     <title>Description</title>
19
20     <para>The goal is to get a set of parameters via a C interface and then to
21     perform some checks in the C function.</para>
22
23     <para>This example is available in the directory
24     CAPI/examples/check_properties.</para>
25   </refsection>
26
27   <refsection>
28     <title>The C function</title>
29
30     <programlisting role="example"> 
31 #include &lt;stack-c.h&gt;
32 #include &lt;sciprint.h&gt;
33
34 int sci_check_properties_1(char * fname)
35 {
36   int m1, n1, l1;
37   int m2, n2, l2;
38   int m3, n3, l3;
39   int m4, n4, l4;
40   int m5, n5, l5;
41
42   CheckRhs(5,5);
43   CheckLhs(0,1) ;
44
45   ////////////////////////////
46   // Getting first argument //
47   ////////////////////////////
48
49   GetRhsVar(1, "d", &amp;m1, &amp;n1, &amp;l1);
50
51   CheckVector(1,m1,n1);   // Check that first argument is a vector
52   CheckLength(1,m1*n1,4); // Check vector length
53   
54   /////////////////////////////
55   // Getting second argument //
56   /////////////////////////////
57
58   GetRhsVar(2, "d", &amp;m2, &amp;n2, &amp;l2);
59
60   CheckRow(2,m2,n2); // Checks that second argument is a row vector
61                      // CheckColumn can also be used
62
63   CheckDimProp(1,2, m1 * n1 != n2); // Check compatibility beetween arg 1 and arg 2. We want m1*n1 == n2 
64
65   ////////////////////////////
66   // Getting third argument //
67   ////////////////////////////
68
69   GetRhsVar(3, "d", &amp;m3, &amp;n3, &amp;l3);
70
71   CheckSameDims(1,3,m1,n1,m3,n3); // Checks that arg 1 and arg3 have same dimensions
72
73   /////////////////////////////
74   // Getting fourth argument //
75   /////////////////////////////
76
77   GetRhsVar(4,"d",&amp;m4,&amp;n4,&amp;l4);
78   
79   CheckScalar(4,m4,n4); // arg 4 must be scalar
80
81   /////////////////////////////
82   // Getting fourth argument //
83   /////////////////////////////
84
85   GetRhsVar(5,"d",&amp;m5,&amp;n5,&amp;l5);
86   
87   CheckSquare(5,m5,n5);   // square matrix
88   CheckDims(5,m5,m5,5,5); // check dimensions
89
90   LhsVar(1)=0;
91
92   return 0;
93 }
94
95 // We must be careful on the scilab name function (8 chars max).
96
97 int sci_check_properties_2(char * fname)
98 {
99   int m1,n1,l1;
100
101   CheckRhs(1,1);
102   CheckLhs(0,1) ;
103
104   switch(VarType(1)) 
105     {
106     case 1: 
107       GetRhsVar(1, "d", &amp;m1, &amp;n1, &amp;l1);
108       sciprint("1 is a scalar matrix\n");
109       break;
110     case 10:
111       GetRhsVar(1, "c", &amp;m1, &amp;n1, &amp;l1);
112       sciprint("1 is a string\n");
113       break;
114     case 5:
115       sciprint("1 is a sparse trying to overload\n");
116       OverLoad(1);
117     }
118
119   LhsVar(1) = 0;
120
121   return 0;
122 }
123   </programlisting>
124
125     <para>This file must be saved as "check_properties.c".</para>
126
127     <para>The main thing to highlight is that, to build a C interface
128     function, we need to include the header stack-c.h. In this header, we find
129     the prototypes and macros of the main C interface functions. We also need
130     to include sciprint.h because we use the sciprint function.</para>
131
132     <para>To be able to build and link such a C function to scilab, we need to
133     write a Scilab script which will compile this C function and then create a
134     loader script which will link the C function to a Scilab function.</para>
135   </refsection>
136
137   <refsection>
138     <title>The builder script</title>
139
140     <programlisting role="example"> 
141 // This is the builder.sce 
142 // must be run from this directory 
143
144 lines(0);
145
146 ilib_name  = 'lib_check_properties';
147
148 files = ['check_properties.c'];
149
150 libs  = [];
151
152 table =['check_properties_1', 'sci_check_properties_1'; ...
153         'chprop2',            'sci_check_properties_2'];
154
155 // We must be careful when we choose a scilab function name in case of overloading.
156 // We Scilab name function must be 8 char max.
157
158 ldflags = "";
159 cflags  = "";
160 fflags  = "";
161
162 // do not modify below 
163 // ----------------------------------------------
164 ilib_build(ilib_name,table,files,libs,'Makelib',ldflags,cflags,fflags);
165   </programlisting>
166
167     <para>This file must be saved as "builder.sce".</para>
168
169     <para>This script will tell Scilab which files must be compiled (here,
170     it's check_properties.c), what will be the name of the shared library
171     (here, it's lib_check_properties) and which C symbol will be linked to a
172     Scilab function (here, we will link the sci_check_properties_1 C symbol to
173     the Scilab function "check_properties_1").</para>
174
175     <para>For the other C function, we must be careful on the name of the
176     Scilab function we will choose. Because this function will be overloading,
177     the current overloading process of Scilab works only on Scilab primitives
178     (Scilab function wrote in C) which have a name which is maximum 8 char
179     wide.</para>
180
181     <para>For this function, we will link the sci_check_properties_2 C symbol
182     to the Scilab function "chprop2").</para>
183
184     <para>To build this function, we just need to to:</para>
185
186     <programlisting> 
187 exec builder.sce;
188  </programlisting>
189
190     <para>Now we are able to test our new C function. First, let's load this
191     new function in scilab:</para>
192
193     <programlisting> 
194 exec loader.sce; 
195  </programlisting>
196
197     <para>The script loader.sce is normally automatically built by
198     builder.sce.</para>
199   </refsection>
200
201   <refsection>
202     <title>Testing our new function</title>
203
204     <para>We now write a simple example to test our new functions.</para>
205
206     <programlisting role="example"> 
207 // checks arguments compatibility 
208
209 check_properties_1([1;2;3;4],[3,4,5,6],[6;7;8;9],90,rand(5,5))
210
211 // first argument can have different types 
212
213 chprop2([1,2,2]);
214 chprop2('foo');
215
216 // overload case 
217
218 deff('[]=%sp_chprop2(sp)','disp(''sparse overloaded'')');
219 chprop2(sparse([1,2,3]));
220
221 // tests which give an error message with check_properties_1
222
223 try
224   check_properties_1([1;2;3;4]',[3,4,5,6],[6;7;8;9],90,rand(5,5))
225 catch
226   disp(lasterror());
227 end
228
229 try
230   check_properties_1([1;2;3;4],[3,4,5,6]',[6;7;8;9],90,rand(5,5))
231 catch
232   disp(lasterror());
233 end
234
235 try
236   check_properties_1([1;2;3;4],[3,4,5,6],[6;7;8;9]',90,rand(5,5))
237 catch
238   disp(lasterror());
239 end
240
241 try
242   check_properties_1([1;2;3;4],[3,4,5,6],[6;7;8;9],[],rand(5,5))
243 catch
244   disp(lasterror());
245 end
246
247 try
248   check_properties_1([1;2;3;4],[3,4,5,6],[6;7;8;9],90,rand(4,4))
249 catch
250   disp(lasterror());
251 end
252  </programlisting>
253
254     <para>The script must be saved as "check_properties.sce".</para>
255
256     <para>Let's run our scripts and see what is the result:</para>
257
258     <programlisting> 
259 --&gt;exec builder.sce;
260    Génère un fichier gateway
261    Génère un fichier loader
262    Génère un Makefile : Makelib
263    Exécute le makefile
264    Compilation de check_properties.c
265    Construction de la bibliothèque partagée (soyez patient)
266  
267 --&gt;exec loader.sce;
268 Bibliothèque partagée chargée.
269 Link done.
270  
271 --&gt;exec check_properties.sce;
272 1 is a scalar matrix
273 1 is a string
274 1 is a sparse trying to overload
275  
276  sparse overloaded   
277  
278  check_properties_1 : Les paramètres first et third a des dimensions incompatibles (1x4) # (4x1)   
279  
280  check_properties_1: second paramètre devrait être un vecteur ligne   
281  
282  check_properties_1 : Les paramètres first et third a des dimensions incompatibles (4x1) # (1x4)   
283  
284  check_properties_1: fourth paramètre devrait être un scalaire   
285  
286  check_properties_1 : Argument numéro 5 n'a pas les bonnes dimensions (4,4),  (5,5) attendues.    
287  </programlisting>
288   </refsection>
289
290   <refsection>
291     <title>See Also</title>
292
293     <simplelist type="inline">
294       <member><link linkend="GetRhsVar">GetRhsVar</link></member>
295
296       <member><link linkend="CheckColumn">CheckColumn</link></member>
297
298       <member><link linkend="CheckDims">CheckDims</link></member>
299
300       <member><link linkend="CheckRow">CheckRow</link></member>
301
302       <member><link linkend="CheckScalar">CheckScalar</link></member>
303
304       <member><link linkend="CheckVector">CheckVector</link></member>
305
306       <member><link linkend="CheckDimProp">CheckDimProp</link></member>
307
308       <member><link linkend="CheckLength">CheckLength</link></member>
309
310       <member><link linkend="CheckSameDims">CheckSameDims</link></member>
311
312       <member><link linkend="CheckSquare">CheckSquare</link></member>
313
314       <member><link linkend="OverLoad">OverLoad</link></member>
315
316       <member><link linkend="ilib_build">ilib_build</link></member>
317     </simplelist>
318   </refsection>
319 </refentry>