Xcos-Scicos: indent some files before modification
[scilab.git] / scilab / modules / xcos / help / en_US / programming_scicos_blocks / c_computational_functions / C_struct.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!--
3  * Scicos
4  * 
5  * Copyright (C) INRIA - METALAU Project <scicos@inria.fr> (HTML version)
6  * Copyright (C) DIGITEO - Scilab Consortium (XML Docbook version)
7  * 
8  * This program is free software; you can redistribute it and/or modify
9  * it under the terms of the GNU General Public License as published by
10  * the Free Software Foundation; either version 2 of the License, or
11  *  (at your option) any later version.
12  * 
13  * This program is distributed in the hope that it will be useful,
14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
16  * GNU General Public License for more details.
17  * 
18  * You should have received a copy of the GNU General Public License
19  * along with this program; if not, write to the Free Software
20  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
21  * 
22  * See the file ./license.txt
23  -->
24 <refentry 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:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:id="C_struct">
25     <refnamediv>
26         <refname>C_struct</refname>
27         <refpurpose>C Block structure of a computational function</refpurpose>
28     </refnamediv>
29     <refsynopsisdiv>
30         <title>Description</title>
31         
32     </refsynopsisdiv>
33     <refsection id="Contents_C_struct">
34         <title>Contents</title>
35         <itemizedlist>
36             <listitem>
37                 <para>
38                     <link linkend="C_struct">C_struct - C Block structure of a computational function</link>
39                 </para>
40             </listitem>
41             <listitem>
42                 <itemizedlist>
43                     <listitem>
44                         <para>
45                             <xref linkend="Module_C_struct">Module</xref>
46                         </para>
47                     </listitem>
48                     <listitem>
49                         <para>
50                             <xref linkend="Description_C_struct">Description</xref>
51                         </para>
52                     </listitem>
53                     <listitem>
54                         <para>
55                             <xref linkend="Inputsoutputs_C_struct">Inputs/outputs</xref>
56                         </para>
57                     </listitem>
58                     <listitem>
59                         <para>
60                             <xref linkend="Events_C_struct">Events</xref>
61                         </para>
62                     </listitem>
63                     <listitem>
64                         <para>
65                             <xref linkend="Parameters_C_struct">Parameters</xref>
66                         </para>
67                     </listitem>
68                     <listitem>
69                         <para>
70                             <xref linkend="Statesandwork_C_struct">States and work</xref>
71                         </para>
72                     </listitem>
73                     <listitem>
74                         <para>
75                             <xref linkend="Zerocrossingsurfacesandmodes_C_struct">Zero crossing surfaces and modes</xref>
76                         </para>
77                     </listitem>
78                     <listitem>
79                         <para>
80                             <xref linkend="Miscallaneous_C_struct">Miscallaneous</xref>
81                         </para>
82                     </listitem>
83                 </itemizedlist>
84             </listitem>
85         </itemizedlist>
86     </refsection>
87     <refsection id="Module_C_struct">
88         <title>Module</title>
89         <itemizedlist>
90             <listitem>
91                 <para>
92                     <link linkend="xcos">xcos</link>
93                 </para>
94             </listitem>
95         </itemizedlist>
96     </refsection>
97     <refsection id="Description_C_struct">
98         <title>Description</title>
99         <para>
100             The C structure of a Scicos block defines all the fields to handle data provided by the simulator
101             such inputs/outputs, parameters, states, ...
102         </para>
103         <para>
104             That structure of type <literal>scicos_block</literal> is defined in the file scicos_block4.h, and user must include that header in each computational functions in the form :
105         </para>
106         <para>
107             
108         </para>
109         <para>
110             The fields, that can be either C pointers or directly data, are then accessible via the <literal>*block</literal>
111             structure :
112         </para>
113         <para>
114             
115         </para>
116         <para>
117             This access is a  approach and most of users should prefer the  approach for facilities purpose.
118         </para>
119         <para>
120             In the current version of Scicos, the <literal>scicos-&gt;block</literal> structure is defined :
121         </para>
122         <para>
123             
124         </para>
125         <para>
126             
127         </para>
128     </refsection>
129     <refsection id="Inputsoutputs_C_struct">
130         <title>Inputs/outputs</title>
131         <para>
132             
133         </para>
134         <itemizedlist>
135             <listitem>
136                 <para>
137                     <emphasis role="bold">block-&gt;nin :</emphasis> Integer that gives the number of regular input ports of the block.
138                 </para>
139                 <para> One can't override the index when reading sizes of input ports in the array and the index when reading data in the array with a C computational function.</para>
140                 <para> The number of regular input ports can also be got by the use of the C macros . </para>
141             </listitem>
142             <listitem>
143                 <para>
144                     <emphasis role="bold">block-&gt;insz :</emphasis> An array of integers of size that respectively gives the first dimensions, the second dimensions and the type of data driven by regular input ports.
145                 </para>
146                 <para> Note that this array of size differs from the array and to provide full compatibility with blocks that only use a single dimension.</para>
147                 <para> Suppose that you have a block with three inputs : the first is an int32 matrix of size 3,2, the second a single complex number (matrix of size 1,1) and the last a real matrix of size 4,1.</para>
148                 <para>
149                     In the<link linkend="scicos_model">scicos_model</link> of such a block, the inputs will be defined :
150                 </para>
151                 <programlisting role="code"><![CDATA[                     model.in    = [3;1;4] 
152
153 model.in2   = [2;1;1] 
154
155 model.intyp = [2;1;3] 
156                     ]]></programlisting>
157                 <para>
158                     
159                     and the corresponding 
160                 </para>
161                 <programlisting role="code"><![CDATA[block->insz]]></programlisting>
162                 <para> field at C computational function level will be
163                     coded as :
164                     
165                     
166                     
167                     
168                     Do the difference here in the type numbers defined at the <emphasis role="bold">Scilab level</emphasis> (2,1,3)
169                     and the type numbers defined at the <emphasis role="bold">C level</emphasis> (84,11,10). The following table gives
170                     the correspondance for all Scicos type:
171                     
172                 </para>
173                 <informaltable border="1" cellpadding="3">
174                     <tr>
175                         <td align="left">
176                             <emphasis role="bold">Scilab Type</emphasis>
177                         </td>
178                         <td align="left">
179                             <emphasis role="bold">Scilab Number</emphasis>
180                         </td>
181                         <td align="left">
182                             <emphasis role="bold">C Type</emphasis>
183                         </td>
184                         <td align="left">
185                             <emphasis role="bold">C Number</emphasis>
186                         </td>
187                     </tr>
188                     <tr>
189                         <td align="left">real</td>
190                         <td align="left">1</td>
191                         <td align="left">double</td>
192                         <td align="left">10</td>
193                     </tr>
194                     <tr>
195                         <td align="left">complex</td>
196                         <td align="left">2</td>
197                         <td align="left">double</td>
198                         <td align="left">11</td>
199                     </tr>
200                     <tr>
201                         <td align="left">int32</td>
202                         <td align="left">3</td>
203                         <td align="left">long</td>
204                         <td align="left">84</td>
205                     </tr>
206                     <tr>
207                         <td align="left">int16</td>
208                         <td align="left">4</td>
209                         <td align="left">short</td>
210                         <td align="left">82</td>
211                     </tr>
212                     <tr>
213                         <td align="left">int8</td>
214                         <td align="left">5</td>
215                         <td align="left">char</td>
216                         <td align="left">81</td>
217                     </tr>
218                     <tr>
219                         <td align="left">uint32</td>
220                         <td align="left">6</td>
221                         <td align="left">unsigned long</td>
222                         <td align="left">814</td>
223                     </tr>
224                     <tr>
225                         <td align="left">uint16</td>
226                         <td align="left">7</td>
227                         <td align="left">unsigned short</td>
228                         <td align="left">812</td>
229                     </tr>
230                     <tr>
231                         <td align="left">uint8</td>
232                         <td align="left">8</td>
233                         <td align="left">unsigned char</td>
234                         <td align="left">811</td>
235                     </tr>
236                 </informaltable>
237             </listitem>
238             <listitem>
239                 <para>
240                     <emphasis role="bold">block-&gt;inptr :</emphasis> An array of pointers of size nin,1 that allow to directly acces to the data contained in the regular input matrices.
241                 </para>
242                 <para> Suppose the previous example (block with three inputs : an int32 matrix of size [3,2], a complex scalar and a real matrix of size [4,1]).</para>
243                 <para>  contains three pointers, and should be viewed as arrays contained the data for the int32, the real and the complex matrices :
244                     
245                     
246                     
247                     For i.e., to directly access to the data, the user can use theses instructions :
248                     
249                 </para>
250                 <programlisting role="code"><![CDATA[                     #include "scicos_block4.h"
251                      ...
252
253 SCSINT32_COP *ptr_i;
254
255 SCSCOMPLEX_COP *ptr_dc;
256
257 SCSREAL_COP *ptr_d;
258
259 int n1,m1;
260
261 SCSINT32_COP cumsum_i=0;
262
263 int i;
264                      ...
265
266 void mycomputfunc(scicos_block *block,int flag) 
267                      {
268                      ...
269                      /*get the ptrs of the first int32 regular input port*/
270
271 ptr_i = (SCSINT32_COP *) block->inptr[0];
272                      /*get the ptrs of the second complex regular input port*/
273
274 ptr_dc = (SCSCOMPLEX_COP *) block->inptr[1];
275                      /*get the ptrs of the third real regular input port*/
276
277 ptr_d = (SCSREAL_COP *) block->inptr[2];
278                      ...
279                      /*get the dimension of the first int32 regular input port*/
280
281 n1=block->insz[0];
282
283 m1=block->insz[3];
284                      ...
285                      /*compute the cumsum of the input int32 matrix*/
286
287 for(i=0;i<n1*m1;i++) {
288
289 cumsum_i += ptr_i[i];
290                      }
291                      ...
292                      }
293                     ]]></programlisting>
294                 <para>
295                     
296                     One can also use the set of C macros :
297                 </para>
298                 <para>                    </para>
299                 <programlisting role="code"><![CDATA[GetInPortPtrs(blk,x)]]></programlisting>
300                 <para>, </para>
301                 <programlisting role="code"><![CDATA[GetRealInPortPtrs(block,x)]]></programlisting>
302                 <para>, 
303                 </para>
304                 <para>                    </para>
305                 <programlisting role="code"><![CDATA[GetImagInPortPtrs(block,x)]]></programlisting>
306                 <para>, </para>
307                 <programlisting role="code"><![CDATA[Getint8InPortPtrs(block,x)]]></programlisting>
308                 <para>, 
309                 </para>
310                 <para>                    </para>
311                 <programlisting role="code"><![CDATA[Getint16InPortPtrs(block,x)]]></programlisting>
312                 <para>, </para>
313                 <programlisting role="code"><![CDATA[Getint32InPortPtrs(block,x)]]></programlisting>
314                 <para>, 
315                 </para>
316                 <para>                    </para>
317                 <programlisting role="code"><![CDATA[Getuint8InPortPtrs(block,x)]]></programlisting>
318                 <para>, </para>
319                 <programlisting role="code"><![CDATA[Getuint16InPortPtrs(block,x)]]></programlisting>
320                 <para>, 
321                 </para>
322                 <para>                    </para>
323                 <programlisting role="code"><![CDATA[Getuint32InPortPtrs(block,x)]]></programlisting>
324                 <para> 
325                 </para>
326                 <para>
327                     to have the appropriate pointer of the data to handle and 
328                 </para>
329                 <para>                    </para>
330                 <programlisting role="code"><![CDATA[GetNin(block)]]></programlisting>
331                 <para>, </para>
332                 <programlisting role="code"><![CDATA[GetInPortRows(block,x)]]></programlisting>
333                 <para>, 
334                 </para>
335                 <para>                    </para>
336                 <programlisting role="code"><![CDATA[GetInPortCols(block,x)]]></programlisting>
337                 <para>, </para>
338                 <programlisting role="code"><![CDATA[GetInPortSize(block,x,y)]]></programlisting>
339                 <para>, 
340                 </para>
341                 <para>                    </para>
342                 <programlisting role="code"><![CDATA[GetInType(block,x)]]></programlisting>
343                 <para>, </para>
344                 <programlisting role="code"><![CDATA[GetSizeOfIn(block,x)]]></programlisting>
345                 <para> 
346                 </para>
347                 <para>
348                     to handle number, dimensions and type of regular input ports.
349                     (<emphasis role="bold">x is numbered from 1 to nin and y numbered  from 1 to 2</emphasis>).
350                 </para>
351                 <para> 
352                     For the previous example that gives :
353                     
354                 </para>
355                 <programlisting role="code"><![CDATA[                     #include "scicos_block4.h"
356                      ...
357
358 SCSINT32_COP *ptr_i;
359
360 SCSCOMPLEX_COP *ptr_dc;
361
362 SCSREAL_COP *ptr_d;
363
364 int n1,m1;
365
366 SCSINT32_COP cumsum_i=0;
367
368 int i;
369                      ...
370
371 void mycomputfunc(scicos_block *block,int flag)
372                      {
373                      ...
374                      /*get the ptrs of the first int32 regular input port*/
375
376 ptr_i = Getint32InPortPtrs(block,1);
377                      /*get the ptrs of the second complex regular input port*/
378
379 ptr_dc = GetRealInPortPtrs(block,2);
380                      /*get the ptrs of the third real regular input port*/
381
382 ptr_d = GetRealInPortPtrs(block,3);
383                      ...
384                      /*get the dimension of the first int32 regular input port*/
385
386 n1=GetInPortRows(block,1);
387
388 m1=GetInPortCols(block,1);
389                      ...
390                      }
391                     ]]></programlisting>
392                 <para>
393                     
394                     Finally note that the regular input port registers are only accessible for reading.
395                 </para>
396             </listitem>
397             <listitem>
398                 <para>
399                     <emphasis role="bold">block-&gt;nout :</emphasis> Integer that gives the number of regular output ports of the block.
400                 </para>
401                 <para> One can't override the index when reading sizes of output ports in the array and the index when reading data in the array with a C computational function.</para>
402                 <para> The number of regular output ports can also be got by the use of the C macros . </para>
403             </listitem>
404             <listitem>
405                 <para>
406                     <emphasis role="bold">block-&gt;outsz :</emphasis> An array of integers of size that respectively gives the first dimensions, the second dimensions and the type of data driven by regular output ports.
407                 </para>
408                 <para> Note that this array of size differs from the array and to provide full compatibility with blocks that only use a single dimension.</para>
409                 <para> Suppose that you have a block with two outputs : the first is an int32 matrix of size 3,2, the second a single complex number (matrix of size 1,1) and the last a real matrix of size 4,1.</para>
410                 <para>
411                     In the<link linkend="scicos_model">scicos_model</link> of such a block, the outputs will be defined :
412                 </para>
413                 <programlisting role="code"><![CDATA[                      model.out   = [3;1;4] 
414
415 model.out2   = [2;1;1] 
416
417 model.outtyp = [2;1;3] 
418                      ]]></programlisting>
419                 <para>
420                     
421                     and the corresponding 
422                 </para>
423                 <programlisting role="code"><![CDATA[block->outsz]]></programlisting>
424                 <para> field at C computational function level will be
425                     coded as :
426                     
427                     
428                     
429                     
430                     Do the difference here in the type numbers defined at the <emphasis role="bold">Scilab level</emphasis> (2,1,3)
431                     and the type numbers defined at the <emphasis role="bold">C level</emphasis> (84,11,10) and please report to the 
432                     previous table to have the correspondence for all Scicos type.
433                 </para>
434             </listitem>
435             <listitem>
436                 <para>
437                     <emphasis role="bold">block-&gt;outptr :</emphasis> An array of pointers of size nout,1 that allow to directly acces to the data contained in the regular output matrices.
438                 </para>
439                 <para> Suppose the previous example (block with three outputs : an int32 matrix of size [3,2], a complex scalar and a real matrix of size [4,1]).</para>
440                 <para>  contains three pointers, and should be viewed as arrays contained the data for the int32, the real and the complex matrices :
441                     
442                     
443                     
444                     For i.e., to directly access to the data, the user can use theses instructions :
445                     
446                 </para>
447                 <programlisting role="code"><![CDATA[                     #include "scicos_block4.h"
448                      ...
449
450 SCSINT32_COP *ptr_i;
451
452 SCSCOMPLEX_COP *ptr_dc;
453
454 SCSREAL_COP *ptr_d;
455
456 int n1,m1;
457
458 SCSINT32_COP cumsum_i=0;
459
460 int i;
461                      ...
462
463 void mycomputfunc(scicos_block *block,int flag)
464                      {
465                      /*get the ptrs of the first int32 regular output port*/
466
467 ptr_i = (SCSINT32_COP *) block->outptr[0];
468                      /*get the ptrs of the second complex regular output port*/
469
470 ptr_dc = (SCSCOMPLEX_COP *) block->outptr[1];
471                      /*get the ptrs of the third real regular output port*/
472
473 ptr_d = (SCSREAL_COP *) block->outptr[2];
474                      ...
475                      /*get the dimension of the first int32 regular output port*/
476
477 n1=block->outsz[0];
478
479 m1=block->outsz[3];
480                      ...
481                      /*compute the cumsum of the output int32 matrix*/
482
483 for(i=0;i<n1*m1;i++) {
484
485 cumsum_i += ptr_i[i];
486                      }
487                      ...
488                      }
489                     ]]></programlisting>
490                 <para>
491                     
492                     One can also use the set of C macros :
493                 </para>
494                 <para>                    </para>
495                 <programlisting role="code"><![CDATA[GetOutPortPtrs(block,x)]]></programlisting>
496                 <para>, </para>
497                 <programlisting role="code"><![CDATA[GetRealOutPortPtrs(block,x)]]></programlisting>
498                 <para>, 
499                 </para>
500                 <para>                    </para>
501                 <programlisting role="code"><![CDATA[GetImagOutPortPtrs(block,x)]]></programlisting>
502                 <para>, </para>
503                 <programlisting role="code"><![CDATA[Getint8OutPortPtrs(block,x)]]></programlisting>
504                 <para>, 
505                 </para>
506                 <para>                    </para>
507                 <programlisting role="code"><![CDATA[Getint16OutPortPtrs(block,x)]]></programlisting>
508                 <para>, </para>
509                 <programlisting role="code"><![CDATA[Getint32OutPortPtrs(block,x)]]></programlisting>
510                 <para>, 
511                 </para>
512                 <para>                    </para>
513                 <programlisting role="code"><![CDATA[Getuint8OutPortPtrs(block,x)]]></programlisting>
514                 <para>, </para>
515                 <programlisting role="code"><![CDATA[Getuint16OutPortPtrs(block,x)]]></programlisting>
516                 <para>, 
517                 </para>
518                 <para>                    </para>
519                 <programlisting role="code"><![CDATA[Getuint32OutPortPtrs(block,x)]]></programlisting>
520                 <para> 
521                 </para>
522                 <para>
523                     to have the appropriate pointer of the data to handle and 
524                 </para>
525                 <para>                    </para>
526                 <programlisting role="code"><![CDATA[GetNout(block)]]></programlisting>
527                 <para>, </para>
528                 <programlisting role="code"><![CDATA[GetOutPortRows(block,x)]]></programlisting>
529                 <para>, 
530                 </para>
531                 <para>                    </para>
532                 <programlisting role="code"><![CDATA[GetOutPortCols(block,x)]]></programlisting>
533                 <para>, </para>
534                 <programlisting role="code"><![CDATA[GetOutPortSize(block,x,y)]]></programlisting>
535                 <para>, 
536                 </para>
537                 <para>                    </para>
538                 <programlisting role="code"><![CDATA[GetOutType(block,x)]]></programlisting>
539                 <para>, </para>
540                 <programlisting role="code"><![CDATA[GetSizeOfOut(block,x)]]></programlisting>
541                 <para> 
542                 </para>
543                 <para>
544                     to handle number, dimensions and type of regular output ports.
545                     (<emphasis role="bold">x is numbered from 1 to nout and y is numbered  from 1 to 2</emphasis>).
546                     
547                     For the previous example that gives :
548                     
549                 </para>
550                 <programlisting role="code"><![CDATA[                     #include "scicos_block4.h"
551                      ...
552
553 SCSINT32_COP *ptr_i;
554
555 SCSCOMPLEX_COP *ptr_dc;
556
557 SCSREAL_COP *ptr_d;
558
559 int n1,m1;
560
561 SCSINT32_COP cumsum_i=0;
562
563 int i;
564                      ...
565
566 void mycomputfunc(scicos_block *block,int flag)
567                      {
568                      ...
569                      /*get the ptrs of the first int32 regular output port*/
570
571 ptr_i = GetOutPortPtrs(block,1);
572                      /*get the ptrs of the second complex regular output port*/
573
574 ptr_dc = GetRealOutPortPtrs(block,2);
575                      /*get the ptrs of the third real regular output port*/
576
577 ptr_d = GetRealOutPortPtrs(block,3);
578                      ...
579                      /*get the dimension of the first int32 regular output port*/
580
581 n1=GetOutPortRows(block,1);
582
583 m1=GetOutPortCols(block,1);
584                      ...
585                      }
586                     ]]></programlisting>
587                 <para>
588                     
589                     Finally note that the regular output port registers must be only written for 
590                 </para>
591                 <programlisting role="code"><![CDATA[flag]]></programlisting>
592                 <para>=1. </para>
593             </listitem>
594         </itemizedlist>
595         <para>
596             
597         </para>
598     </refsection>
599     <refsection id="Events_C_struct">
600         <title>Events</title>
601         <para>
602             
603         </para>
604         <itemizedlist>
605             <listitem>
606                 <para>
607                     <emphasis role="bold">block-&gt;nevprt :</emphasis> Integer that gives the event input port number by which the block has been activated. This number is a binary coding. For i.e, if block has two event inputs ports, can take the value 1 if the block has been called by its first event input port, the value 2 if it has been called by the second event input port and 3 if it is called by the same event on both input port 1 and 2.
608                 </para>
609                 <para> Note that can be -1 if the block is internally called.</para>
610                 <para> One can also retrieve this number by using the C macros . </para>
611             </listitem>
612             <listitem>
613                 <para>
614                     <emphasis role="bold">block-&gt;nevout :</emphasis> Integer that gives the number of event output ports of the block (also called the length of the output event register).
615                 </para>
616                 <para> One can't override the index when setting value of events in the output event register .</para>
617                 <para> The number of event output ports can also be got by the use of the C macro . </para>
618             </listitem>
619             <listitem>
620                 <para>
621                     <emphasis role="bold">block-&gt;evout :</emphasis> Array of double of size nevout,1 corresponding to the output event register. That register is used to program date of events during the simulation.
622                 </para>
623                 <para> When setting values in that array, you must understand that you give a delay relative to the current time of simulator :</para>
624                 <para>
625                     where 
626                     <inlinemediaobject>
627                         <imageobject>
628                             <imagedata fileref="../../../images/C_struct_img6_eng.gif" align="center" valign="middle"/>
629                         </imageobject>
630                     </inlinemediaobject>
631                     is the date of the programmed event, 
632                     <inlinemediaobject>
633                         <imageobject>
634                             <imagedata fileref="../../../images/C_struct_img7_eng.gif" align="center" valign="middle"/>
635                         </imageobject>
636                     </inlinemediaobject>
637                     is the current time in the simulator and 
638                     <inlinemediaobject>
639                         <imageobject>
640                             <imagedata fileref="../../../images/C_struct_img8_eng.gif" align="center" valign="middle"/>
641                         </imageobject>
642                     </inlinemediaobject>
643                     the value that must be informed in the output event register.
644                     For i.e, suppose that you want generate an event with the first event output port, 1ms after
645                     each calls of the block, then you'll use :
646                     
647                 </para>
648                 <programlisting role="code"><![CDATA[                      #include "scicos_block4.h"
649                       ...
650
651 void mycomputfunc(scicos_block *block,int flag)
652                       {
653                       ...
654
655 if (flag==3) { 
656
657 block->evout[0]=0.001;
658                       }
659                       ...
660                      }
661                      ]]></programlisting>
662                 <para>
663                 </para>
664                 <para> 
665                     Note that every events generated from output event register will be asynchronous with event
666                     coming from event input port (even if you set 
667                 </para>
668                 <programlisting role="code"><![CDATA[block->evout[x]=0]]></programlisting>
669                 <para>). 
670                 </para>
671                 <para>
672                     The event output register must be only written for 
673                 </para>
674                 <programlisting role="code"><![CDATA[flag]]></programlisting>
675                 <para>=3. </para>
676             </listitem>
677         </itemizedlist>
678         <para>
679             
680         </para>
681     </refsection>
682     <refsection id="Parameters_C_struct">
683         <title>Arguments</title>
684         <para>
685             
686         </para>
687         <itemizedlist>
688             <listitem>
689                 <para>
690                     <emphasis role="bold">block-&gt;nrpar :</emphasis> Integer that gives the length of the real parameter register.
691                 </para>
692                 <para> One can't override the index when reading value of real parameters in the register .</para>
693                 <para> The total number of real parameters can also be got by the use of the C macro . </para>
694             </listitem>
695             <listitem>
696                 <para>
697                     <emphasis role="bold">block-&gt;rpar :</emphasis> Array of double of size nrpar,1 corresponding to the real parameter register. That register is used to pass real parameters coming from the scilab/scicos environment to your block model.
698                 </para>
699                 <para> The C type of that array is (or C scicos type ).</para>
700                 <para>
701                     Suppose that you have defined the following real parameters in the<link linkend="scicos_model">scicos_model</link> of a block :
702                 </para>
703                 <programlisting role="code"><![CDATA[                     model.rpar   = [%pi;%pi/2;%pi/4]
704                     ]]></programlisting>
705                 <para>
706                     
707                     you can retrieve the previous data in the C computational function with :
708                     
709                 </para>
710                 <programlisting role="code"><![CDATA[                     #include "scicos_block4.h"
711                      ...
712
713 double PI;
714
715 double PI_2;
716
717 double PI_4;
718                      ...
719
720 void mycomputfunc(scicos_block *block,int flag)
721                      {
722                      ...
723                      /*get the first value of the real param register*/
724
725 PI = block->rpar[0];
726                      /*get the second value of the real param register*/
727
728 PI_2 = block->rpar[1];
729                      /*get the third value of the real param register*/
730
731 PI_4 = block->rpar[2];
732                      ...
733                      }
734                     ]]></programlisting>
735                 <para>
736                     
737                     You can also use the C macro 
738                 </para>
739                 <programlisting role="code"><![CDATA[GetRparPtrs(block)]]></programlisting>
740                 <para> to get the pointer of the
741                     real parameter register. For i.e., if we define the following
742                     <link linkend="scicos_model">scicos_model</link>
743                     in an interfacing function of a
744                     scicos block :
745                     
746                 </para>
747                 <programlisting role="code"><![CDATA[                     A = [1.3 ; 4.5 ; 7.9 ; 9.8];
748
749 B = [0.1 ; 0.98]; 
750
751 model.rpar   = [A;B] 
752                     ]]></programlisting>
753                 <para>
754                     
755                     in the corresponding C computational function of that block, we'll use :
756                     
757                 </para>
758                 <programlisting role="code"><![CDATA[                     #include "scicos_block4.h"
759                      ...
760
761 double *rpar;
762
763 double *A; 
764
765 double *B; 
766                      ...
767
768 void mycomputfunc(scicos_block *block,int flag)
769                      {
770                      ...
771                      /*get ptrs of the real param register*/
772
773 rpar = GetRparPtrs(block); 
774                      /*get the A ptrs array*/
775
776 A = rpar;
777                      /*get the B ptrs array*/
778
779 B = &rpar[4];
780                      /*or B = rpar + 4;*/
781                      ...
782                      }
783                     ]]></programlisting>
784                 <para>
785                     
786                     Note that real parameters register is only accessible for reading.
787                 </para>
788             </listitem>
789             <listitem>
790                 <para>
791                     <emphasis role="bold">block-&gt;nipar :</emphasis> Integer that gives the length of the integer parameter register.
792                 </para>
793                 <para> One can't override the index when reading value of integer parameters in the register .</para>
794                 <para> The total number of integer parameters can also be got by the use of the C macro . </para>
795             </listitem>
796             <listitem>
797                 <para>
798                     <emphasis role="bold">block-&gt;ipar :</emphasis> Array of int of size nipar,1 corresponding to the integer parameter register. That register is used to pass integer parameters coming from the scilab/scicos environment to your block model.
799                 </para>
800                 <para> The C type of that array is (or C scicos type ).</para>
801                 <para>
802                     Suppose that you have defined the following integer parameters in the<link linkend="scicos_model">scicos_model</link> of a block :
803                 </para>
804                 <programlisting role="code"><![CDATA[                     model.ipar   = [(1:3)';5] 
805                     ]]></programlisting>
806                 <para>
807                     
808                     you can retrieve the previous data in the C computational function with :
809                     
810                 </para>
811                 <programlisting role="code"><![CDATA[                     #include "scicos_block4.h"
812                      ...
813
814 int one;
815
816 int two;
817
818 int three;
819
820 int five;
821                      ...
822
823 void mycomputfunc(scicos_block *block,int flag)
824                      {
825                      ...
826                      /*get the first value of the integer param register*/
827
828 one = block->ipar[0]; 
829                      /*get the second value of the integer param register*/
830
831 two = block->ipar[1]; 
832                      /*get the third value of the integer param register*/
833
834 three = block->ipar[2]; 
835                      /*get the fourth value of the integer param register*/
836
837 five = block->ipar[3]; 
838                      ...
839                      }
840                     ]]></programlisting>
841                 <para>
842                     
843                     You can also use the C macro 
844                 </para>
845                 <programlisting role="code"><![CDATA[GetIparPtrs(block)]]></programlisting>
846                 <para> to get the pointer of the
847                     real parameter register.
848                 </para>
849                 <para>
850                     Most of time in the scicos C block libraries, the integer register is used to
851                     parametrize the length of real parameters. For i.e. if you define the following
852                     <link linkend="scicos_model">scicos_model</link>
853                     in a block :
854                     
855                 </para>
856                 <programlisting role="code"><![CDATA[                     // set a random size for the first real parameters 
857
858 A_sz = int(rand(10)*10); 
859                      // set a random size for the second real parameters 
860
861 B_sz = int(rand(10)*10); 
862                      // set the first real parameters 
863
864 A = rand(A_sz,1,``uniform''); 
865                      // set the second real parameters 
866
867 B = rand(B_sz,1,``normal''); 
868                      // set ipar 
869
870 model.ipar = [A_sz;B_sz] 
871                      // set rpar (length of A_sz+B_sz) 
872
873 model.rpar = [A;B] 
874                     ]]></programlisting>
875                 <para>
876                     
877                     the array of real parameters (parametrized by ipar) can be retrieved in the
878                     correspondig C computational function with :
879                     
880                 </para>
881                 <programlisting role="code"><![CDATA[                     #include "scicos_block4.h"
882                      ...
883
884 int A_sz; 
885
886 int B_sz; 
887
888 double *rpar; 
889
890 double *A; 
891
892 double *B; 
893
894 double cumsum;
895
896 int i; 
897                      ...
898
899 void mycomputfunc(scicos_block *block,int flag)
900                      {
901                      ...
902                      /*get ptrs of the real param register*/
903
904 rpar = GetRparPtrs(block); 
905                      /*get size of the first real param register*/
906
907 A_sz = block->ipar[0]; 
908                      /*get size of the second real param register*/
909
910 B_sz = block->ipar[1]; 
911                      /*get the A ptrs array*/
912
913 A = rpar; 
914                      /*get the B ptrs array*/
915
916 B = &rpar[A_sz]; 
917                      ...
918                      /*compute the cumsum of the first real parameter array*/
919
920 cumsum = 0;
921
922 for(i=0;i<A_sz;i++) {
923
924 cumsum += A[i];
925                      }
926                      ...
927                      /*compute the cumsum of the second real parameter array*/
928
929 cumsum = 0;
930
931 for(i=0;i<B_sz;i++) {
932
933 cumsum += B[i]; 
934                      }
935                     ]]></programlisting>
936                 <para>
937                     
938                     Note that integer parameters register is only accessible for reading.
939                 </para>
940             </listitem>
941             <listitem>
942                 <para>
943                     <emphasis role="bold">block-&gt;nopar :</emphasis> Integer that gives the number of the object parameters.
944                 </para>
945                 <para> One can't override the index when accessing data in the arrays , and in a C computational function.</para>
946                 <para> This value is also accessible via the C macro . </para>
947             </listitem>
948             <listitem>
949                 <para>
950                     <emphasis role="bold">block-&gt;oparsz :</emphasis> An array of integer of size nopar,2 that contains the dimensions of matrices of object parameters.
951                 </para>
952                 <para> The first column is for the first dimension and the second for the second dimension. For i.e. if we want the dimensions of the last object parameters, we'll use the instructions :
953                 </para>
954                 <programlisting role="code"><![CDATA[                     #include "scicos_block4.h"
955                      ...
956
957 int nopar;
958
959 int n,m;
960                      ...
961
962 void mycomputfunc(scicos_block *block,int flag)
963                      {
964                      ...
965                      /*get the number of object parameter*/
966
967 nopar=block>nopar;
968                      ...
969                      /*get number of row of the last object parameter*/
970
971 n=block>oparsz[nopar-1];
972                      /*get number of column of the last object parameter*/
973
974 m=block>oparsz[2*nopar-1];
975                      ...
976                      }
977                     ]]></programlisting>
978                 <para>
979                     
980                     The dimensions of object parameters can be get with the following C macro :
981                     
982                 </para>
983                 <programlisting role="code"><![CDATA[                     GetOparSize(block,x,1); /*get first dimension of opar*/ 
984
985 GetOparSize(block,x,2); /*get second dimension of opar*/ 
986                     ]]></programlisting>
987                 <para>
988                     
989                     with 
990                 </para>
991                 <programlisting role="code"><![CDATA[x]]></programlisting>
992                 <para>
993                     an integer that gives the index of the object parameter, <emphasis role="bold">numbered
994                         from 1 to nopar
995                     </emphasis>
996                     .
997                 </para>
998             </listitem>
999             <listitem>
1000                 <para>
1001                     <emphasis role="bold">block-&gt;opartyp :</emphasis> An array of integer of size nopar,1 that contains the type of matrices of object parameters.
1002                 </para>
1003                 <para> The following table gives the correspondence for scicos type expressed in Scilab number, in C number and also corresponding C pointers and C macros used for :
1004                     
1005                     The type of object parameter can also be got by the use of the C macro
1006                 </para>
1007                 <programlisting role="code"><![CDATA[GetOparType(block,x)]]></programlisting>
1008                 <para>. For i.e, if we want the C number type of the first
1009                     object parameter, we'll use the following C instructions:
1010                     
1011                 </para>
1012                 <programlisting role="code"><![CDATA[                      #include "scicos_block4.h"
1013                      ...
1014
1015 int opartyp_1;
1016                      ...
1017
1018 void mycomputfunc(scicos_block *block,int flag)
1019                       {
1020                       ...
1021                       /*get the number type of the first object parameter*/
1022
1023 opartyp_1 = GetOparType(block,1);
1024                       ...
1025                      }
1026                      ]]></programlisting>
1027                 <para>
1028                 </para>
1029             </listitem>
1030             <listitem>
1031                 <para>
1032                     <emphasis role="bold">block-&gt;oparptr :</emphasis> An array of pointers of size nopar,1 that allow to directly acces to the data contained in the object parameter.
1033                 </para>
1034                 <para>
1035                     Suppose that you have defined in the editor a block with the following<emphasis role="bold">opar</emphasis> field in<link linkend="scicos_model">scicos_model</link> :
1036                 </para>
1037                 <programlisting role="code"><![CDATA[model.opar=list(int32([1,2;3,4]),[1+%i %i 0.5]);]]></programlisting>
1038                 <para>
1039                     
1040                     Then we have two object parameters, one is an 32-bit integer matrix with two rows and two
1041                     columns and the second is a vector of complex numbers that can be understand as a matrix
1042                     of size 1,3.
1043                 </para>
1044                 <para>
1045                     At the C computational function level, the instructions 
1046                 </para>
1047                 <programlisting role="code"><![CDATA[block->oparsz[0]]]></programlisting>
1048         <para>,
1049                      </para>
1050         <programlisting role="code"><![CDATA[block->oparsz[1]]]></programlisting>
1051         <para>, </para>
1052         <programlisting role="code"><![CDATA[block->oparsz[2]]]></programlisting>
1053         <para>, </para>
1054         <programlisting role="code"><![CDATA[block->oparsz[3]]]></programlisting>
1055         <para> will respectively return the
1056                      values 2,1,2,3 and the instructions </para>
1057         <programlisting role="code"><![CDATA[block->opartyp[0]]]></programlisting>
1058         <para>, </para>
1059         <programlisting role="code"><![CDATA[block->opartyp[1]]]></programlisting>
1060         <para> the values 11 and
1061                      84.
1062 </para>
1063         <para>                     </para>
1064         <programlisting role="code"><![CDATA[block->oparptr]]></programlisting>
1065                 <para> will contain then two pointers, and should be viewed as arrays contained data of
1066                     object parameter as shown in the following figure :
1067                     
1068                     
1069                     
1070                     
1071                     For i.e., to directly access to the data, the user can use theses instructions :
1072                     
1073                 </para>
1074                 <programlisting role="code"><![CDATA[                     #include "scicos_block4.h"
1075                      ...
1076
1077 SCSINT32_COP *ptr_i;
1078
1079 SCSINT32_COP cumsum_i;
1080
1081 SCSCOMPLEX_COP *ptr_d;
1082
1083 SCSREAL_COP cumsum_d;
1084                      ...
1085
1086 void mycomputfunc(scicos_block *block,int flag)
1087                      {
1088                      ...
1089                      /*get the ptrs of an int32 object parameter*/
1090
1091 ptr_i = (SCSINT32_COP *) block->oparptr[0];
1092                      /*get the ptrs of a double object parameter*/
1093
1094 ptr_d = (SCSCOMPLEX_COP *) block->oparptr[1];
1095                      ...
1096                      /*compute the cumsum of the int32 matrix*/
1097
1098 cumsum_i = ptr_i[0]+ptr_i[1]+ptr_i[2]+ptr_i[3];
1099                      ...
1100                      /*compute the cumsum of the real part of the complex matrix*/
1101
1102 cumsum_d = ptr_d[0]+ptr_d[1]+ptr_d[2];
1103                      ...
1104                      }
1105                     ]]></programlisting>
1106                 <para>
1107                     
1108                     One can also use the set of C macros :
1109                 </para>
1110                 <para>                    </para>
1111                 <programlisting role="code"><![CDATA[GetRealOparPtrs(block,x)]]></programlisting>
1112                 <para>,  </para>
1113                 <programlisting role="code"><![CDATA[GetImagOparPtrs(block,x)]]></programlisting>
1114                 <para>,
1115                 </para>
1116                 <para>                    </para>
1117                 <programlisting role="code"><![CDATA[Getint8OparPtrs(block,x)]]></programlisting>
1118                 <para>,  </para>
1119                 <programlisting role="code"><![CDATA[Getint16OparPtrs(block,x)]]></programlisting>
1120                 <para>,
1121                 </para>
1122                 <para>                    </para>
1123                 <programlisting role="code"><![CDATA[Getint32OparPtrs(block,x)]]></programlisting>
1124                 <para>, </para>
1125                 <programlisting role="code"><![CDATA[Getuint8OparPtrs(block,x)]]></programlisting>
1126                 <para>,
1127                 </para>
1128                 <para>                    </para>
1129                 <programlisting role="code"><![CDATA[Getuint16OparPtrs(block,x)]]></programlisting>
1130                 <para>, </para>
1131                 <programlisting role="code"><![CDATA[Getuint32OparPtrs(block,x)]]></programlisting>
1132                 <para>
1133                 </para>
1134                 <para>
1135                     to have the appropriate pointer of the data to handle (<emphasis role="bold">x is numbered from 1 to nopar</emphasis>).
1136                 </para>
1137                 <para>
1138                     For the previous example that gives :
1139                     
1140                 </para>
1141                 <programlisting role="code"><![CDATA[                     #include "scicos_block4.h"
1142                      ...
1143
1144 SCSINT32_COP *ptr_i;
1145
1146 SCSREAL_COP *ptr_dr;
1147
1148 SCSREAL_COP *ptr_di;
1149                      ...
1150
1151 void mycomputfunc(scicos_block *block,int flag)
1152                      {
1153                      ...
1154                      /*get the ptrs of an int32 object parameter*/
1155
1156 ptr_i = Getint32OparPtrs(block,1);
1157                      /*get the ptrs of a double object parameter*/
1158
1159 ptr_dr = GetRealOparPtrs(block,2);
1160
1161 ptr_di = GetImagOparPtrs(block,2);
1162                      ...
1163                      }
1164                     ]]></programlisting>
1165                 <para>
1166                     
1167                     Note that object parameters register is only accessible for reading. 
1168                 </para>
1169             </listitem>
1170         </itemizedlist>
1171         <para>
1172             
1173         </para>
1174     </refsection>
1175     <refsection id="Statesandwork_C_struct">
1176         <title>States and work</title>
1177         <para>
1178             
1179         </para>
1180         <itemizedlist>
1181             <listitem>
1182                 <para>
1183                     <emphasis role="bold">block-&gt;nx :</emphasis> Integer that gives the length of the continus state register.
1184                 </para>
1185                 <para> One can't override the index when reading or writing data in the array , or with a C computational function. </para>
1186             </listitem>
1187             <listitem>
1188                 <para>
1189                     <emphasis role="bold">block-&gt;x :</emphasis> Array of double of size nx,1 corresponding to the continuous state register.
1190                 </para>
1191                 <para> That gives the result of the computation of the state derivative.</para>
1192                 <para> A value of a continuous state is readable (for i.e the first state) with the C instructions :
1193                 </para>
1194                 <programlisting role="code"><![CDATA[                  #include "scicos_block4.h"
1195                   ...
1196
1197 double x_1;
1198                   ...
1199
1200 void mycomputfunc(scicos_block *block,int flag)
1201                   {
1202                   ...
1203
1204 x_1=block->x[0];
1205                   ...
1206                   }
1207                  ]]></programlisting>
1208                 <para>
1209                     
1210                     Note that on 
1211                 </para>
1212                 <programlisting role="code"><![CDATA[flag]]></programlisting>
1213                 <para>=4, user can write some initial conditions in that register.
1214                 </para>
1215                 <para>
1216                     The pointer of that array can also be retrieve via the C macro 
1217                 </para>
1218                 <programlisting role="code"><![CDATA[GetState(block)]]></programlisting>
1219                 <para>.
1220                 </para>
1221             </listitem>
1222             <listitem>
1223                 <para>
1224                     <emphasis role="bold">block-&gt;xd :</emphasis> Array of double of size nx,1 corresponding to the derivative of the continuous state register.
1225                 </para>
1226                 <para> When systems are explicitly given in terms of Ordinary Differential Equations (ODE), it can be explicitly expressed or implicitly used in the residual vector when systems are expressed in terms of Differantial Algebraic Equations (DAE).</para>
1227                 <para> Both systems must be programmed with .</para>
1228                 <para> For i.e the Lorentz attractor written as an ODE system with three state variables, of the form :
1229                 </para>
1230                 <para>
1231                     will be defined :
1232                 </para>
1233                 <programlisting role="code"><![CDATA[                   #include "scicos_block4.h"
1234                    ...
1235
1236 double *x = block->x;
1237
1238 double *xd = block->xd;
1239                    ...
1240                    /* define parameters */
1241
1242 double a = 10;
1243
1244 double b = 28;
1245
1246 double c = 8/3;
1247                    ...
1248
1249 void mycomputfunc(scicos_block *block,int flag)
1250                    {
1251                    ...
1252
1253 if (flag == 0) {
1254
1255 xd[0] = a*(x[1]-x[0]);
1256
1257 xd[1] = x[1]*(b-x[2])-x[1];
1258
1259 xd[2] = x[0]*x[1]-c*x[2];
1260                    }
1261                    ...
1262                    }
1263                   ]]></programlisting>
1264                 <para>
1265                 </para>
1266             </listitem>
1267             <listitem>
1268                 <para>
1269                     <emphasis role="bold">block-&gt;res :</emphasis> Array of double of size nx,1 corresponding to Differential Algebraic Equation (DAE) residual.
1270                 </para>
1271                 <para> It is used to write the vector of systems that have the following form :</para>
1272                 <para>  For i.e the Lorentz attractor written as a DAE system with three state variables, will be defined :
1273                 </para>
1274                 <programlisting role="code"><![CDATA[                    #include "scicos_block4.h"
1275                     ...
1276
1277 double *x = block->x;
1278
1279 double *xd = block->xd;
1280
1281 double *res = block->res;
1282                     ...
1283                     /* define parameters */
1284
1285 double a = 10;
1286
1287 double b = 28;
1288
1289 double c = 8/3;
1290                     ...
1291
1292 void mycomputfunc(scicos_block *block,int flag)
1293                     {
1294                     ...
1295
1296 if (flag == 0) {
1297
1298 res[0] =  - xd[0] + (a*(x[1]-x[0]));
1299
1300 res[1] =  - xd[1] + (x[0]*(b-x[2])-x[1]);
1301
1302 res[2] =  - xd[2] + (x[0]*x[1]-c*x[2]);
1303                     }
1304                     ...
1305                     }
1306                    ]]></programlisting>
1307                 <para>
1308                 </para>
1309             </listitem>
1310             <listitem>
1311                 <para>
1312                     <emphasis role="bold">block-&gt;nz :</emphasis> Integer that gives the length of the discrete state register.
1313                 </para>
1314                 <para> One can't override the index when reading data in the array with a C computational function.</para>
1315                 <para> This value is also accessible via the C macros . </para>
1316             </listitem>
1317             <listitem>
1318                 <para>
1319                     <emphasis role="bold">block-&gt;z :</emphasis> Array of double of size nz,1 corresponding to the discrete state register.
1320                 </para>
1321                 <para> A value of a discrete state is directly readable (for i.e the second state) with the C instructions :
1322                 </para>
1323                 <programlisting role="code"><![CDATA[                  #include "scicos_block4.h"
1324                   ...
1325
1326 double z_2;
1327                   ...
1328
1329 void mycomputfunc(scicos_block *block,int flag)
1330                   {
1331                   ...
1332
1333 z_2=block->z[1];
1334                   ...
1335                   }
1336                  ]]></programlisting>
1337                 <para>
1338                     
1339                     Note that the state register should be only written for 
1340                 </para>
1341                 <programlisting role="code"><![CDATA[flag]]></programlisting>
1342                 <para>=4 and </para>
1343                 <programlisting role="code"><![CDATA[flag]]></programlisting>
1344                 <para>=2.
1345                 </para>
1346                 <para>
1347                     The pointer of that array can also be retrieve via the C macro 
1348                 </para>
1349                 <programlisting role="code"><![CDATA[GetDstate(block)]]></programlisting>
1350                 <para>.
1351                 </para>
1352             </listitem>
1353             <listitem>
1354                 <para>
1355                     <emphasis role="bold">block-&gt;noz :</emphasis> Integer that gives the number of the discrete object states.
1356                 </para>
1357                 <para> One can't override the index when accessing data in the arrays , and in a C computational function.</para>
1358                 <para> This value is also accessible via the C macro . </para>
1359             </listitem>
1360             <listitem>
1361                 <para>
1362                     <emphasis role="bold">block-&gt;ozsz :</emphasis> An array of integer of size noz,2 that contains the dimensions of matrices of discrete object states.
1363                 </para>
1364                 <para> The first column is for the first dimension and the second for the second dimension. For i.e. if we want the dimensions of the last object state, we'll use the instructions :
1365                 </para>
1366                 <programlisting role="code"><![CDATA[                     #include "scicos_block4.h"
1367                      ...
1368
1369 int noz;
1370
1371 int n,m;
1372                      ...
1373                      /*get the number of object state*/
1374
1375 noz=block>noz;
1376                      ...
1377
1378 void mycomputfunc(scicos_block *block,int flag)
1379                      {
1380                      ...
1381                      /*get number of row of the last object state*/
1382
1383 n=block>ozsz[noz-1];
1384                      /*get number of column of the last object state*/
1385
1386 m=block>ozsz[2*noz-1];
1387                      ...
1388                      }
1389                     ]]></programlisting>
1390                 <para>
1391                     
1392                     The dimensions of object discrete states can be get with the following C macro :
1393                     
1394                 </para>
1395                 <programlisting role="code"><![CDATA[                     GetOzSize(block,x,1); /*get first dimension of oz*/ 
1396
1397 GetOzSize(block,x,2); /*get second dimension of oz*/ 
1398                     ]]></programlisting>
1399                 <para>
1400                     
1401                     with 
1402                 </para>
1403                 <programlisting role="code"><![CDATA[x]]></programlisting>
1404                 <para>
1405                     an integer that gives the index of the discrete object state, <emphasis role="bold">numbered
1406                         from 1 to noz
1407                     </emphasis>
1408                     .
1409                 </para>
1410             </listitem>
1411             <listitem>
1412                 <para>
1413                     <emphasis role="bold">block-&gt;oztyp :</emphasis> An array of integer of size noz,1 that contains the type of matrices of discrete object states.
1414                 </para>
1415                 <para> The following table gives the correspondence table for scicos type expressed in Scilab number, in C number and also corresponding C pointers and C macros used for :
1416                     
1417                     The type of discrete object state can also be got by the use of the C macro
1418                 </para>
1419                 <programlisting role="code"><![CDATA[GetOzType(block,x)]]></programlisting>
1420                 <para>. For i.e, if we want the C number type of the first
1421                     discrete object state, we'll use the following C instructions:
1422                     
1423                 </para>
1424                 <programlisting role="code"><![CDATA[                      #include "scicos_block4.h"
1425                       ...
1426
1427 int oztyp_1;
1428                       ...
1429
1430 void mycomputfunc(scicos_block *block,int flag)
1431                       {
1432                       ...
1433                       /*get the number type of the first object state*/
1434
1435 oztyp_1 = GetOzType(block,1);
1436                      ...
1437                      }
1438                      ]]></programlisting>
1439                 <para>
1440                 </para>
1441             </listitem>
1442             <listitem>
1443                 <para>
1444                     <emphasis role="bold">block-&gt;ozptr :</emphasis> An array of pointers of size noz,1 that allow to directly acces to the data contained in the discrete object state.
1445                 </para>
1446                 <para>
1447                     Suppose that you have defined in the editor a block with the following<emphasis role="bold">odstate</emphasis> field in <link linkend="scicos_model">scicos_model</link> :
1448                 </para>
1449                 <programlisting role="code"><![CDATA[model.odstate=list(int32([1,2;3,4]),[1+%i %i 0.5]);]]></programlisting>
1450                 <para>
1451                     
1452                     Then we have two discrete object states, one is an 32-bit integer matrix with two rows and two
1453                     columns and the second is a vector of complex numbers that can be understand as a matrix
1454                     of size 1,3.
1455                 </para>
1456                 <para>
1457                     At the C computational function level, the instructions 
1458                 </para>
1459                 <programlisting role="code"><![CDATA[block->ozsz[0]]]></programlisting>
1460         <para>,
1461                      </para>
1462         <programlisting role="code"><![CDATA[block->ozsz[1]]]></programlisting>
1463         <para>, </para>
1464         <programlisting role="code"><![CDATA[block->ozsz[2]]]></programlisting>
1465         <para>, </para>
1466         <programlisting role="code"><![CDATA[block->ozsz[3]]]></programlisting>
1467         <para> will respectively return the
1468                      values 2,1,2,3 and the instructions </para>
1469         <programlisting role="code"><![CDATA[block->oztyp[0]]]></programlisting>
1470         <para>, </para>
1471         <programlisting role="code"><![CDATA[block->oztyp[1]]]></programlisting>
1472         <para> the values 11 and
1473                      84.
1474 </para>
1475         <para>                     </para>
1476         <programlisting role="code"><![CDATA[block->ozptr]]></programlisting>
1477                 <para> will contain then two pointers, and should be viewed as arrays contained data of
1478                     discrete object state as shown in the following figure :
1479                     
1480                     
1481                     
1482                     
1483                     For i.e., to directly access to the data, the user can use theses instructions :
1484                     
1485                 </para>
1486                 <programlisting role="code"><![CDATA[                     #include "scicos_block4.h"
1487                      ...
1488
1489 SCSINT32_COP *ptr_i;
1490
1491 SCSINT32_COP cumsum_i;
1492
1493 SCSCOMPLEX_COP *ptr_d;
1494
1495 SCSREAL_COP cumsum_d;
1496                      ...
1497
1498 void mycomputfunc(scicos_block *block,int flag)
1499                      {
1500                      ...
1501                      /*get the ptrs of an int32 discrete object state*/
1502
1503 ptr_i = (SCSINT32_COP *) block->ozptr[0];
1504                      /*get the ptrs of a double discrete object state*/
1505
1506 ptr_d = (SCSCOMPLEX_COP *) block->ozptr[1];
1507                      ...
1508                      /*compute the cumsum of the int32 matrix*/
1509
1510 cumsum_i = ptr_i[0]+ptr_i[1]+ptr_i[2]+ptr_i[3];
1511                      ...
1512                      /*compute the cumsum of the real part of the complex matrix*/
1513
1514 cumsum_d = ptr_d[0]+ptr_d[1]+ptr_d[2];
1515                      ...
1516                      }
1517                     ]]></programlisting>
1518                 <para>
1519                     
1520                     One can also use the set of C macros :
1521                 </para>
1522                 <para>                    </para>
1523                 <programlisting role="code"><![CDATA[GetRealOzPtrs(block,x)]]></programlisting>
1524                 <para>,  </para>
1525                 <programlisting role="code"><![CDATA[GetImagOzPtrs(block,x)]]></programlisting>
1526                 <para>,
1527                 </para>
1528                 <para>                    </para>
1529                 <programlisting role="code"><![CDATA[Getint8OzPtrs(block,x)]]></programlisting>
1530                 <para>,  </para>
1531                 <programlisting role="code"><![CDATA[Getint16OzPtrs(block,x)]]></programlisting>
1532                 <para>,
1533                 </para>
1534                 <para>                    </para>
1535                 <programlisting role="code"><![CDATA[Getint32OzPtrs(block,x)]]></programlisting>
1536                 <para>, </para>
1537                 <programlisting role="code"><![CDATA[Getuint8OzPtrs(block,x)]]></programlisting>
1538                 <para>,
1539                 </para>
1540                 <para>                    </para>
1541                 <programlisting role="code"><![CDATA[Getuint16OzPtrs(block,x)]]></programlisting>
1542                 <para>, </para>
1543                 <programlisting role="code"><![CDATA[Getuint32OzPtrs(block,x)]]></programlisting>
1544                 <para> 
1545                 </para>
1546                 <para>
1547                     to have the appropriate pointer of the data to handle (<emphasis role="bold">x is numbered from 1 to noz</emphasis>).
1548                 </para>
1549                 <para>
1550                     For the previous example that gives :
1551                     
1552                 </para>
1553                 <programlisting role="code"><![CDATA[                     #include "scicos_block4.h"
1554                      ...
1555
1556 SCSINT32_COP *ptr_i;
1557
1558 SCSREAL_COP *ptr_dr;
1559
1560 SCSREAL_COP *ptr_di;
1561                      ...
1562
1563 void mycomputfunc(scicos_block *block,int flag)
1564                      {
1565                      ...
1566                      /*get the ptrs of an int32 discrete object state*/
1567
1568 ptr_i = Getint32OzPtrs(block,1);
1569                      /*get the ptrs of a double discrete object state*/
1570
1571 ptr_dr = GetRealOzPtrs(block,2);
1572
1573 ptr_di = GetImagOzPtrs(block,2);
1574                      ...
1575                      }
1576                     ]]></programlisting>
1577                 <para>
1578                     
1579                     Finally note that the discrete objects state should be only written for 
1580                 </para>
1581                 <programlisting role="code"><![CDATA[flag]]></programlisting>
1582                 <para>=4 and </para>
1583                 <programlisting role="code"><![CDATA[flag]]></programlisting>
1584                 <para>=2.
1585                 </para>
1586             </listitem>
1587             <listitem>
1588                 <para>
1589                     <emphasis role="bold">block-&gt;work :</emphasis> A free pointer to set a working array for the block.
1590                 </para>
1591                 <para> The work pointer must be firstly allocated when = 4 and finally be free in the = 5.</para>
1592                 <para> Then a basic life cyle of that pointer in a C computational function should be :
1593                 </para>
1594                 <programlisting role="code"><![CDATA[                            #include "scicos_block4.h"
1595                             ...
1596
1597 void** work=block->work;
1598                             ...
1599
1600 void mycomputfunc(scicos_block *block,int flag)
1601                             {
1602                            ...
1603                             /*initialization*/
1604
1605 if (flag==4) {
1606                               /*allocation of work*/
1607
1608 if (*work=scicos_malloc(sizeof(double))==NULL) {
1609
1610 set_block_error(-16);
1611
1612 return;
1613                               }
1614                             ...
1615                             }
1616                             ...
1617                             /*other flag treatment*/
1618                             ...
1619                             /*finish*/
1620
1621 else if (flag==5) {
1622
1623 scicos_free(*work);
1624                             }
1625                             ...
1626                             }
1627                            ]]></programlisting>
1628                 <para>
1629                     
1630                     Note that if a block use a 
1631                 </para>
1632                 <programlisting role="code"><![CDATA[work]]></programlisting>
1633                 <para> pointer, it will be called with </para>
1634                 <programlisting role="code"><![CDATA[flag]]></programlisting>
1635                 <para>=2 even if
1636                     the block do not use discrete states.
1637                 </para>
1638                 <para>
1639                     The pointer of that array can also be retrieve via the C macro 
1640                 </para>
1641                 <programlisting role="code"><![CDATA[GetWorkPtrs(block)]]></programlisting>
1642                 <para>. </para>
1643             </listitem>
1644         </itemizedlist>
1645         <para>
1646             
1647         </para>
1648     </refsection>
1649     <refsection id="Zerocrossingsurfacesandmodes_C_struct">
1650         <title>Zero crossing surfaces and modes</title>
1651         <para>
1652             
1653         </para>
1654         <itemizedlist>
1655             <listitem>
1656                 <para>
1657                     <emphasis role="bold">block-&gt;ng :</emphasis> Integer that gives the number of zero crossing surface of the block.
1658                 </para>
1659                 <para> One can't override the index when reading/writing data in the array with a C computational function.</para>
1660                 <para> The number of zero crossing surface can also be got by the use of the C macro . </para>
1661             </listitem>
1662             <listitem>
1663                 <para>
1664                     <emphasis role="bold">block-&gt;g :</emphasis> Array of double of size ng,1 corresponding to the zero crossing surface register.
1665                 </para>
1666                 <para> That register is used to detect zero crossing of state variable during time domain integration.</para>
1667                 <para> Note that it is accessible for writing for = 9.</para>
1668                 <para> The pointer of that array can also be retrieve via the C macro . </para>
1669             </listitem>
1670             <listitem>
1671                 <para>
1672                     <emphasis role="bold">block-&gt;nmode :</emphasis> Integer that gives the number of mode of the block.
1673                 </para>
1674                 <para> One can't override the index when reading/writing data in the array with a C computational function.</para>
1675                 <para> The number of mode can also be got by the use of the C macro . </para>
1676             </listitem>
1677             <listitem>
1678                 <para>
1679                     <emphasis role="bold">block-&gt;mode :</emphasis> Array of integer of size nmode,1 corresponding to the mode register.
1680                 </para>
1681                 <para> That register is used to set the mode of state variable during time domain integration.</para>
1682                 <para> It is typically accessible for writing for = 9.</para>
1683                 <para> The pointer of that array can also be retrieve via the C macro . </para>
1684             </listitem>
1685         </itemizedlist>
1686         <para>
1687             
1688         </para>
1689     </refsection>
1690     <refsection id="Miscallaneous_C_struct">
1691         <title>Miscallaneous</title>
1692         <para>
1693             
1694             
1695         </para>
1696         <itemizedlist>
1697             <listitem>
1698                 <para>
1699                     <emphasis role="bold">block-&gt;type :</emphasis> Integer that gives the type of the computational function. For C blocks, this number is equal to 4. 
1700                 </para>
1701             </listitem>
1702             <listitem>
1703                 <para>
1704                     <emphasis role="bold">block-&gt;label :</emphasis> Strings array that allows to retrieve the label of the block.
1705                 </para>
1706             </listitem>
1707         </itemizedlist>
1708     </refsection>
1709 </refentry>
1710