ae6b0b75161b0ec73cbef3dddfc96181bcabf186
[scilab.git] / 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             <link type="scilab" linkend="scilab.xcos/xcos/examples/sinks_pal/en_US/writec_f_en_US.zcos">
308                 Open this example in Xcos
309             </link>
310             .
311         </para>
312         <para/>
313         <para>
314             <link type="scilab" linkend="scilab.xcos/xcos/examples/sinks_pal/en_US/writec_f_en_US.zcos">
315                 <inlinemediaobject>
316                     <imageobject>
317                         <imagedata fileref="../../../../examples/sinks_pal/en_US/writec_f_en_US.zcos" align="center" valign="middle"/>
318                     </imageobject>
319                 </inlinemediaobject>
320             </link>
321         </para>
322     </refsection>
323     
324     <refsection id="Interfacingfunction_WRITEC_f">
325         <title>Interfacing function</title>
326         <itemizedlist>
327             <listitem>
328                 <para>
329                     <link type="scilab" linkend="scilab.scinotes/scicos_blocks/macros/Sinks/WRITEC_f.sci">SCI/modules/scicos_blocks/macros/Sinks/WRITEC_f.sci</link>
330                 </para>
331             </listitem>
332         </itemizedlist>
333     </refsection>
334     
335     <refsection id="Computationalfunction_WRITEC_f">
336         <title>Computational function</title>
337         <itemizedlist>
338             <listitem>
339                 <para> SCI/modules/scicos_blocks/src/c/writec.c (Type 2)</para>
340             </listitem>
341         </itemizedlist>
342     </refsection>
343     
344     <refsection role="see also" id="Seealso_WRITEC_f">
345         <title>See also</title>
346         <itemizedlist>
347             <listitem>
348                 <link linkend="READC_f">READC_f</link>
349             </listitem>
350             <listitem>
351                 <link linkend="RFILE_f">RFILE_f</link>
352             </listitem>
353             <listitem>
354                 <link linkend="WFILE_f">WFILE_f</link>
355             </listitem>
356         </itemizedlist>
357     </refsection>
358 </refentry>