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