scilab/modules/xcos/help/en_US/palettes/Sinks_pal/WRITEC_f.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!--
   3  * Xcos
   4  *
   5  * Copyright (C) INRIA - METALAU Project <scicos@inria.fr> (HTML version)
   6  * Copyright (C) DIGITEO - Scilab Consortium (XML Docbook version)
   7  * Copyright (C) 2011 - Bernard DUJARDIN <bernard.dujardin@contrib.scilab.org>
   8  *
   9  * This program is free software; you can redistribute it and/or modify
  10  * it under the terms of the GNU General Public License as published by
  11  * the Free Software Foundation; either version 2 of the License, or
  12  *  (at your option) any later version.
  13  *
  14  * This program is distributed in the hope that it will be useful,
  15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  17  * GNU General Public License for more details.
  18  *
  19  * You should have received a copy of the GNU General Public License
  20  * along with this program; if not, write to the Free Software
  21  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  22  *
  23  * See the file ./license.txt
  24  -->
  25 <refentry
  26   xmlns:scilab="http://www.scilab.org" xml:id="WRITEC_f" xml:lang="en_US"
  27   xmlns="http://docbook.org/ns/docbook"
  28   xmlns:xlink="http://www.w3.org/1999/xlink"
  29   xmlns:svg="http://www.w3.org/2000/svg"
  30   xmlns:ns5="http://www.w3.org/1999/xhtml"
  31   xmlns:mml="http://www.w3.org/1998/Math/MathML"
  32   xmlns:db="http://docbook.org/ns/docbook"
  33 >
  34     <refnamediv>
  35         <refname>WRITEC_f</refname>
  36         <refpurpose>Write to C binary file</refpurpose>
  37     </refnamediv>
  38
  39     <refsection>
  40         <title>Block Screenshot</title>
  41         <para>
  42             <inlinemediaobject>
  43                 <imageobject>
  44                     <imagedata fileref="../../../../images/palettes/WRITEC_f.png" align="center" valign="middle"/>
  45                 </imageobject>
  46             </inlinemediaobject>
  47         </para>
  48     </refsection>
  49
  50     <refsection id="Contents_WRITEC_f">
  51         <title>Contents</title>
  52         <itemizedlist>
  53             <listitem>
  54                 <para>
  55                     <link linkend="WRITEC_f">Write to C binary file</link>
  56                 </para>
  57             </listitem>
  58             <listitem>
  59                 <itemizedlist>
  60                     <listitem>
  61                         <para>
  62                             <xref linkend="Palette_WRITEC_f">Palette</xref>
  63                         </para>
  64                     </listitem>
  65                     <listitem>
  66                         <para>
  67                             <xref linkend="Description_WRITEC_f">Description</xref>
  68                         </para>
  69                     </listitem>
  70                     <listitem>
  71                         <para>
  72                             <xref linkend="Datatype_WRITEC_f">Data types</xref>
  73                         </para>
  74                     </listitem>
  75                     <listitem>
  76                         <para>
  77                             <xref linkend="Dialogbox_WRITEC_f">Dialog box</xref>
  78                         </para>
  79                     </listitem>
  80                     <listitem>
  81                         <para>
  82                             <xref linkend="Defaultproperties_WRITEC_f">Default properties</xref>
  83                         </para>
  84                     </listitem>
  85                     <listitem>
  86                         <para>
  87                             <xref linkend="Interfacingfunction_WRITEC_f">Interfacing function</xref>
  88                         </para>
  89                     </listitem>
  90                     <listitem>
  91                         <para>
  92                             <xref linkend="Computationalfunction_WRITEC_f">Computational function</xref>
  93                         </para>
  94                     </listitem>
  95                     <listitem>
  96                         <para>
  97                             <xref linkend="Seealso_WRITEC_f">See also</xref>
  98                         </para>
  99                     </listitem>
 100                 </itemizedlist>
 101             </listitem>
 102         </itemizedlist>
 103     </refsection>
 104
 105     <refsection id="Palette_WRITEC_f">
 106         <title>Palette</title>
 107         <itemizedlist>
 108             <listitem>
 109                 <para>
 110                     <link linkend="Sinks_pal">Sinks palette</link>
 111                 </para>
 112             </listitem>
 113         </itemizedlist>
 114     </refsection>
 115
 116     <refsection id="Description_WRITEC_f">
 117         <title>Description</title>
 118         <para>
 119             This block allows to user to write data in a C binary file with the name defined by the string <emphasis role="bold">Output File Name</emphasis>.
 120             The file is a sequence of records. Each record has the length fixed by the parameter <emphasis role="bold">Input Size</emphasis> and the structure shown
 121             below:
 122         </para>
 123         <mediaobject>
 124             <imageobject>
 125                 <imagedata fileref="../../../images/palettes/sinks_pal/en_US/writec_f_record_en_US.gif"/>
 126             </imageobject>
 127             <textobject>
 128                 <programlisting role="pic"><![CDATA[
 129 .PS
 130 box "Field #1";
 131 box "Field #2";
 132 box "...";
 133 box "Field #(N-1)";
 134 box "Field #N";
 135 .PE
 136                 ]]></programlisting>
 137             </textobject>
 138         </mediaobject>
 139         <para>where the block inputs are numbered from top to bottom.</para>
 140         <para>
 141             The record fields must contains data of the same type defined by the parameter <emphasis role="bold">Output Format</emphasis>.
 142         </para>
 143         <para>
 144             Each event on the activation input of the bloc writes a record in the file. Note that contrary in <link linkend="WFILE_f">WFILE_f</link>, the event dates are not recorded.
 145         </para>
 146     </refsection>
 147
 148     <refsection id="Datatype_WRITEC_f">
 149         <title>Data types</title>
 150         <itemizedlist>
 151             <listitem>
 152                 <para>
 153                     Input: a scalar or a column vector of size <emphasis role="bold">Input Size</emphasis>.
 154                 </para>
 155             </listitem>
 156         </itemizedlist>
 157     </refsection>
 158
 159     <refsection id="Dialogbox_WRITEC_f">
 160         <title>Dialog box</title>
 161         <para>
 162             <inlinemediaobject>
 163                 <imageobject>
 164                     <imagedata fileref="../../../gui/sinks_pal/en_US/WRITEC_f_gui.png" align="center" valign="middle"/>
 165                 </imageobject>
 166             </inlinemediaobject>
 167         </para>
 168         <para />
 169         <itemizedlist>
 170             <listitem>
 171                 <para>
 172                     <emphasis role="bold">Input Size</emphasis>
 173                 </para>
 174                 <para>A scalar, the size of the input column vector.</para>
 175                 <para>Properties : Type 'vec' of size 1 </para>
 176             </listitem>
 177             <listitem>
 178                 <para>
 179                     <emphasis role="bold">Output File Name</emphasis>
 180                 </para>
 181                 <para>
 182                     A character string defining the path and the file name of the file to be write. The block support file name expansion and you can use environment variables like
 183                     <emphasis>HOME</emphasis> in the path, by example <emphasis>"HOME/my_data/foo.data"</emphasis>. Without file path, the file is wrote in the directory defined by the
 184                     <emphasis>PWD</emphasis> variable.
 185                 </para>
 186                 <para>The file path must exist, otherwise you will be prompted by an error message.</para>
 187                 <para> Properties : Type 'str' of size 1 </para>
 188             </listitem>
 189             <listitem>
 190                 <para>
 191                     <emphasis role="bold">Output Format</emphasis>
 192                 </para>
 193                 <para>
 194                     A character string defining the format to use. The following string "l", "i", "s", "ul", "ui", "us", "d", "f", "c", "uc"
 195                     are used respectively to write int32, int16, int8, uint32, uint16, uint8, double, float, char or unsigned char data type.
 196                 </para>
 197                 <para>
 198                     You must use the same format when you read the file with  <link linkend="READC_f">READC_f</link>.
 199                 </para>
 200                 <para> Properties : Type 'str' of size 1 </para>
 201             </listitem>
 202             <listitem>
 203                 <para>
 204                     <emphasis role="bold">Buffer size</emphasis>
 205                 </para>
 206                 <para>
 207                     To improve efficiency it is possible to buffer the input data. Data writing on the file is only done
 208                     when the buffer is full.
 209                 </para>
 210                 <para> Properties : Type 'vec' of size 1 </para>
 211             </listitem>
 212             <listitem>
 213                 <para>
 214                     <emphasis role="bold">Swap Mode (0:No, 1:Yes)</emphasis>
 215                 </para>
 216                 <para>Endian IEEE format</para>
 217                 <itemizedlist>
 218                     <listitem>
 219                         <para>
 220                             <emphasis role="bold">0</emphasis>: automatic bytes swap is disabled.
 221                         </para>
 222                     </listitem>
 223                     <listitem>
 224                         <para>
 225                             <emphasis role="bold">1</emphasis>: the file is supposed to be coded in "little endian IEEE format" and data are
 226                             swapped if necessary to match the IEEE format of the processor.
 227                         </para>
 228                     </listitem>
 229                 </itemizedlist>
 230                 <para> Properties : Type 'vec' of size 1 </para>
 231             </listitem>
 232         </itemizedlist>
 233     </refsection>
 234
 235     <refsection id="Defaultproperties_WRITEC_f">
 236         <title>Default properties</title>
 237         <itemizedlist>
 238             <listitem>
 239                 <para>
 240                     <emphasis role="bold">always active:</emphasis> no
 241                 </para>
 242             </listitem>
 243             <listitem>
 244                 <para>
 245                     <emphasis role="bold">direct-feedthrough:</emphasis> yes
 246                 </para>
 247             </listitem>
 248             <listitem>
 249                 <para>
 250                     <emphasis role="bold">zero-crossing:</emphasis> no
 251                 </para>
 252             </listitem>
 253             <listitem>
 254                 <para>
 255                     <emphasis role="bold">mode:</emphasis> no
 256                 </para>
 257             </listitem>
 258             <listitem>
 259                 <para>
 260                     <emphasis role="bold">regular inputs:</emphasis>
 261                 </para>
 262                 <para>
 263                     <emphasis role="bold">- port 1 : size [1,1] / type 1</emphasis>
 264                 </para>
 265             </listitem>
 266             <listitem>
 267                 <para>
 268                     <emphasis role="bold">number/sizes of activation inputs:</emphasis> 1
 269                 </para>
 270             </listitem>
 271             <listitem>
 272                 <para>
 273                     <emphasis role="bold">number/sizes of activation outputs:</emphasis> 0
 274                 </para>
 275             </listitem>
 276             <listitem>
 277                 <para>
 278                     <emphasis role="bold">continuous-time state:</emphasis> no
 279                 </para>
 280             </listitem>
 281             <listitem>
 282                 <para>
 283                     <emphasis role="bold">discrete-time state:</emphasis> yes
 284                 </para>
 285             </listitem>
 286             <listitem>
 287                 <para>
 288                     <emphasis role="bold">object discrete-time state:</emphasis> no
 289                 </para>
 290             </listitem>
 291             <listitem>
 292                 <para>
 293                     <emphasis role="bold">name of computational function:</emphasis>
 294                     <emphasis role="italic">writec</emphasis>
 295                 </para>
 296             </listitem>
 297         </itemizedlist>
 298     </refsection>
 299
 300     <refsection id="Example_WRITEC_f">
 301         <title>Example</title>
 302         <para>
 303             In this example the block is used to record the output of the sine wave generator. To record at the same time, the time
 304             events, we use a TIME_f block and a multiplexer to form the input vector of the WRITEC_f block which record the data in
 305             the file <emphasis>"TMPDIR/writec_f.data"</emphasis>. Then you can read these data with the block
 306             <link linkend="READC_f">READC_f</link>.
 307         </para>
 308         <para/>
 309         <para>
 310             <link type="scilab" linkend="scilab.xcos/xcos/examples/sinks_pal/en_US/writec_f_en_US.zcos">
 311                 <inlinemediaobject>
 312                     <imageobject>
 313                         <imagedata fileref="../../../../examples/sinks_pal/en_US/writec_f_en_US.zcos" align="center" valign="middle"/>
 314                     </imageobject>
 315                 </inlinemediaobject>
 316             </link>
 317         </para>
 318     </refsection>
 319
 320     <refsection id="Interfacingfunction_WRITEC_f">
 321         <title>Interfacing function</title>
 322         <itemizedlist>
 323             <listitem>
 324                 <para>
 325                     <link type="scilab" linkend="scilab.scinotes/scicos_blocks/macros/Sinks/WRITEC_f.sci">SCI/modules/scicos_blocks/macros/Sinks/WRITEC_f.sci</link>
 326                 </para>
 327             </listitem>
 328         </itemizedlist>
 329     </refsection>
 330
 331     <refsection id="Computationalfunction_WRITEC_f">
 332         <title>Computational function</title>
 333         <itemizedlist>
 334             <listitem>
 335                 <para> SCI/modules/scicos_blocks/src/c/writec.c (Type 2)</para>
 336             </listitem>
 337         </itemizedlist>
 338     </refsection>
 339
 340     <refsection role="see also" id="Seealso_WRITEC_f">
 341         <title>See also</title>
 342         <itemizedlist>
 343             <listitem>
 344                 <link linkend="READC_f">READC_f</link>
 345             </listitem>
 346             <listitem>
 347                 <link linkend="RFILE_f">RFILE_f</link>
 348             </listitem>
 349             <listitem>
 350                 <link linkend="WFILE_f">WFILE_f</link>
 351             </listitem>
 352         </itemizedlist>
 353     </refsection>
 354 </refentry>