Xcos help: fixed the simulation time, resized images, deleted unused links.
[scilab.git] / scilab / modules / xcos / help / en_US / palettes / Sources_pal / RFILE_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 xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:ns5="http://www.w3.org/1999/xhtml" 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="RFILE_f" xml:lang="en_US">
26     <refnamediv>
27         <refname>RFILE_f</refname>
28         <refpurpose>Read from input file</refpurpose>
29     </refnamediv>
30     <refsection>
31         <title>Block Screenshot</title>
32         <para>
33             <inlinemediaobject>
34                 <imageobject>
35                     <imagedata fileref="../../../../images/palettes/RFILE_f.png" align="center" valign="middle"/>
36                 </imageobject>
37             </inlinemediaobject>
38         </para>
39     </refsection>
40     <refsection id="Contents_RFILE_f">
41         <title>Contents</title>
42         <itemizedlist>
43             <listitem>
44                 <para>
45                     <link linkend="RFILE_f">Read from input file</link>
46                 </para>
47             </listitem>
48             <listitem>
49                 <itemizedlist>
50                     <listitem>
51                         <para>
52                             <xref linkend="Palette_RFILE_f">Palette</xref>
53                         </para>
54                     </listitem>
55                     <listitem>
56                         <para>
57                             <xref linkend="Description_RFILE_f">Description</xref>
58                         </para>
59                     </listitem>
60                     <listitem>
61                         <para>
62                             <xref linkend="Datatype_RFILE_f">Data types</xref>
63                         </para>
64                     </listitem>
65                     <listitem>
66                         <para>
67                             <xref linkend="Dialogbox_RFILE_f">Dialog box</xref>
68                         </para>
69                     </listitem>
70                     <listitem>
71                         <para>
72                             <xref linkend="Defaultproperties_RFILE_f">Default properties</xref>
73                         </para>
74                     </listitem>
75                     <listitem>
76                         <para>
77                             <xref linkend="Example_RFILE_f">Example</xref>
78                         </para>
79                     </listitem>
80                     <listitem>
81                         <para>
82                             <xref linkend="Interfacingfunction_RFILE_f">Interfacing function</xref>
83                         </para>
84                     </listitem>
85                     <listitem>
86                         <para>
87                             <xref linkend="Computationalfunction_RFILE_f">Computational function</xref>
88                         </para>
89                     </listitem>
90                     <listitem>
91                         <para>
92                             <xref linkend="Seealso_RFILE_f">See also</xref>
93                         </para>
94                     </listitem>
95                 </itemizedlist>
96             </listitem>
97         </itemizedlist>
98     </refsection>
99     <refsection id="Palette_RFILE_f">
100         <title>Palette</title>
101         <itemizedlist>
102             <listitem>
103                 <para>
104                     <link linkend="Sources_pal">Sources palette</link>
105                 </para>
106             </listitem>
107         </itemizedlist>
108     </refsection>
109     <refsection id="Description_RFILE_f">
110         <title>Description</title>
111         <para>
112             This block allows user to read data in a file with the name defined with the <emphasis role="bold">Input File Name</emphasis> parameter, in text formatted mode or in binary mode.
113         </para>
114         <para>
115             The file is a sequence of records. Each record has the length <emphasis role="bold">Record Size</emphasis> <literal>+ 1
116             </literal>
117             and the structure shown below:
118         </para>
119         <mediaobject>
120             <imageobject>
121                 <imagedata fileref="../../../images/palettes/sources_pal/en_US/rfile_f_record_en_US.gif"/>
122             </imageobject>
123             <textobject>
124                 <programlisting role="pic"><![CDATA[
125 .PS
126 box "Field #1";
127 box "Field #2";
128 box "...";
129 box "Field #(N-1)";
130 box "Field #N";
131 .PE
132                 ]]></programlisting>
133             </textobject>
134         </mediaobject>
135         <para>
136             The <emphasis role="bold">Time Record Selection</emphasis> parameter allows to user the selection of one field in the
137             record which represents time events. When this parameter is set, an activation output is added to the block to return
138             these events to the user.
139             With a feedback of the activation output to the event input of the block, the records are read in sequence until file end as in the example below.
140         </para>
141         <para>
142             The <emphasis role="bold">Outputs Record Selection</emphasis> is used to select the record's fields which will be
143             included in the regular output.
144         </para>
145         <para>
146             The <emphasis role="bold">Output Format</emphasis> parameter gives the record format.
147         </para>
148         <itemizedlist>
149             <listitem>
150                 <para>
151                     For a binary file, this parameter is an empty string.
152                 </para>
153             </listitem>
154             <listitem>
155                 <para>
156                     For a text file, this parameter is a string of format (Fortran syntax) enclosed by parentheses.
157                 </para>
158             </listitem>
159         </itemizedlist>
160         <para>Each event on the activation input of the block advances one record in the file.</para>
161     </refsection>
162     <refsection id="Datatype_RFILE_f">
163         <title>Data types</title>
164         <itemizedlist>
165             <listitem>
166                 <para>
167                     Output:  a scalar or a column vector of data of type double. The vector length is equal to the length of the
168                     <emphasis role="bold">Outputs Record Selection</emphasis> vector.
169                 </para>
170             </listitem>
171         </itemizedlist>
172     </refsection>
173     <refsection id="Dialogbox_RFILE_f">
174         <title>Dialog box</title>
175         <para>
176             <inlinemediaobject>
177                 <imageobject>
178                     <imagedata fileref="../../../gui/sources_pal/en_US/RFILE_f_gui.png" align="center"/>
179                 </imageobject>
180             </inlinemediaobject>
181         </para>
182         <para/>
183         <itemizedlist>
184             <listitem>
185                 <para>
186                     <emphasis role="bold">Time record selection</emphasis>
187                 </para>
188                 <para> An empty matrix or a positive integer.</para>
189                 <para>
190                     If an integer 
191                     <emphasis>
192                         <literal>i</literal>
193                     </emphasis>
194                     is given the 
195                     <emphasis><literal>
196                             i<superscript>th</superscript>
197                         </literal>
198                     </emphasis>
199                     element of the read record is assumed to be the date of the output event.
200                 </para>
201                 <para> If it is an empty matrice, no output event exists.</para>
202                 <para> Properties : Type 'vec' of size -1. </para>
203             </listitem>
204             <listitem>
205                 <para>
206                     <emphasis role="bold">Outputs record selection</emphasis>
207                 </para>
208                 <para>
209                     A vector of positive integer 
210                     <emphasis><literal>
211                             [k<subscript>i</subscript>,...,k<subscript>n</subscript>]
212                         </literal>
213                     </emphasis>
214                     the element 
215                     <emphasis><literal>
216                             k<subscript>i</subscript><superscript>th</superscript>
217                         </literal>
218                     </emphasis>
219                     of the read record gives the value of the 
220                     <emphasis><literal>
221                             i<superscript>th</superscript>
222                         </literal>
223                     </emphasis>
224                     output.
225                 </para>
226                 <para> Properties : Type 'vec' of size -1. </para>
227             </listitem>
228             <listitem>
229                 <para>
230                     <emphasis role="bold">Input file name</emphasis>
231                 </para>
232                 <para>
233                     A character string defining the path of the file. The block support file name expansion and you can use environment variables
234                     like <emphasis>PWD</emphasis> in the path, by example <emphasis>"PWD/my_data/"</emphasis>. Without path specifier, the file is read
235                     in the directory defined by the <emphasis>PWD</emphasis> variable.
236                 </para>
237                 <para>The file must exist, otherwise you will be prompted by an error message.</para>
238                 <para> Properties : Type 'str' of size 1. </para>
239             </listitem>
240             <listitem>
241                 <para>
242                     <emphasis role="bold">Input Format</emphasis>
243                 </para>
244                 <para>
245                     A character string defining the Fortran format to use or nothing for an unformatted (binary) write. If given, the format must began by a left parenthesis and end by a right parenthesis. Example: 
246                     <emphasis>
247                         <literal>(10e3)</literal>
248                     </emphasis>
249                 </para>
250                 <para> Properties : Type 'str' of size 1. </para>
251             </listitem>
252             <listitem>
253                 <para>
254                     <emphasis role="bold">Buffer size</emphasis>
255                 </para>
256                 <para>
257                     To improve efficiency it is possible to buffer the input data. The reading of samples on the peripheral fills
258                     the buffer so that there are always available data in memory for the block.
259                 </para>
260                 <para> Properties : Type 'vec' of size 1.</para>
261             </listitem>
262         </itemizedlist>
263     </refsection>
264     <refsection id="Defaultproperties_RFILE_f">
265         <title>Default properties</title>
266         <itemizedlist>
267             <listitem>
268                 <para>
269                     <emphasis role="bold">always active:</emphasis> no
270                 </para>
271             </listitem>
272             <listitem>
273                 <para>
274                     <emphasis role="bold">direct-feedthrough:</emphasis> no
275                 </para>
276             </listitem>
277             <listitem>
278                 <para>
279                     <emphasis role="bold">zero-crossing:</emphasis> no
280                 </para>
281             </listitem>
282             <listitem>
283                 <para>
284                     <emphasis role="bold">mode:</emphasis> no
285                 </para>
286             </listitem>
287             <listitem>
288                 <para>
289                     <emphasis role="bold">regular outputs:</emphasis>
290                 </para>
291                 <para>
292                     <emphasis role="bold">- port 1 : size [1,1] / type 1</emphasis>
293                 </para>
294             </listitem>
295             <listitem>
296                 <para>
297                     <emphasis role="bold">number/sizes of activation inputs:</emphasis> 1
298                 </para>
299             </listitem>
300             <listitem>
301                 <para>
302                     <emphasis role="bold">number/sizes of activation outputs:</emphasis> 0
303                 </para>
304             </listitem>
305             <listitem>
306                 <para>
307                     <emphasis role="bold">continuous-time state:</emphasis> no
308                 </para>
309             </listitem>
310             <listitem>
311                 <para>
312                     <emphasis role="bold">discrete-time state:</emphasis> yes
313                 </para>
314             </listitem>
315             <listitem>
316                 <para>
317                     <emphasis role="bold">object discrete-time state:</emphasis> no
318                 </para>
319             </listitem>
320             <listitem>
321                 <para>
322                     <emphasis role="bold">name of computational function:</emphasis>
323                     <emphasis role="italic">readf</emphasis>
324                 </para>
325             </listitem>
326         </itemizedlist>
327     </refsection>
328     <refsection id="Example_RFILE_f">
329         <title>Example</title>
330         <para>
331             This example reads the file: <emphasis>"SCI/modules/xcos/examples/sources_pal/en_US/rfile_f.txt"</emphasis> which contains a set of data generated by the example of the
332             <link linkend="WFILE_f">WFILE_f</link> block help page.
333         </para>
334         <para>
335             It use its activation output as event input of CSCOPE. In the file, the first field of the record is the time, the two others are regular data. The feedback of the
336             activation output on event input ensures the file sequential read.
337         </para>
338         <para/>
339         <para>
340             <link type="scilab" linkend="scilab.xcos/xcos/examples/sources_pal/en_US/rfile_f_en_US.zcos">
341                 <inlinemediaobject>
342                     <imageobject>
343                         <imagedata fileref="../../../../examples/sources_pal/en_US/rfile_f_en_US.zcos" align="center" valign="middle"/>
344                     </imageobject>
345                 </inlinemediaobject>
346             </link>
347         </para>
348     </refsection>
349     <refsection id="Interfacingfunction_RFILE_f">
350         <title>Interfacing function</title>
351         <itemizedlist>
352             <listitem>
353                 <para>
354                     <link type="scilab" linkend="scilab.scinotes/scicos_blocks/macros/Sources/RFILE_f.sci">SCI/modules/scicos_blocks/macros/Sources/RFILE_f.sci</link>
355                 </para>
356             </listitem>
357         </itemizedlist>
358     </refsection>
359     <refsection id="Computationalfunction_RFILE_f">
360         <title>Computational function</title>
361         <itemizedlist>
362             <listitem>
363                 <para> SCI/modules/scicos_blocks/src/fortran/readf.f (Type 0)</para>
364             </listitem>
365         </itemizedlist>
366     </refsection>
367     <refsection role="see also" id="Seealso_RFILE_f">
368         <title>See also</title>
369         <itemizedlist>
370             <listitem>
371                 <link linkend="WFILE_f">WFILE_f</link>
372             </listitem>
373             <listitem>
374                 <link linkend="READC_f">READC_f</link>
375             </listitem>
376             <listitem>
377                 <link linkend="WRITEC_f">WRITEC_f</link>
378             </listitem>
379         </itemizedlist>
380     </refsection>
381 </refentry>