add CDATA + role in the fileio module
[scilab.git] / scilab / modules / fileio / help / en_US / mget.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!--
3  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
4  * Copyright (C) 2008 - INRIA
5  * ...
6  * 
7  * This file must be used under the terms of the CeCILL.
8  * This source file is licensed as described in the file COPYING, which
9  * you should have received as part of this distribution.  The terms
10  * are also available at    
11  * http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt
12  *
13  -->
14 <refentry version="5.0-subset Scilab" xml:id="mget" xml:lang="en"
15           xmlns="http://docbook.org/ns/docbook"
16           xmlns:xlink="http://www.w3.org/1999/xlink"
17           xmlns:svg="http://www.w3.org/2000/svg"
18           xmlns:ns5="http://www.w3.org/1999/xhtml"
19           xmlns:mml="http://www.w3.org/1998/Math/MathML"
20           xmlns:db="http://docbook.org/ns/docbook">
21   <info>
22     <pubdate>$LastChangedDate$</pubdate>
23   </info>
24
25   <refnamediv>
26     <refname>mget</refname>
27
28     <refpurpose>reads byte or word in a given binary format and convert to
29     double</refpurpose>
30   </refnamediv>
31
32   <refnamediv xml:id="mgeti">
33     <refname>mgeti</refname>
34
35     <refpurpose>reads byte or word in a given binary format return an int
36     type</refpurpose>
37   </refnamediv>
38
39   <refsynopsisdiv>
40     <title>Calling Sequence</title>
41
42     <synopsis>x=mget([n,type,fd])
43 x=mgeti([n,type,fd])</synopsis>
44   </refsynopsisdiv>
45
46   <refsection>
47     <title>Parameters</title>
48
49     <variablelist>
50       <varlistentry>
51         <term>n</term>
52
53         <listitem>
54           <para>a positive scalar: The number of items to be read.</para>
55         </listitem>
56       </varlistentry>
57
58       <varlistentry>
59         <term>fd</term>
60
61         <listitem>
62           <para>a scalar. The <literal>fd</literal> parameter returned by the
63           function <literal>mopen</literal>. -1 stands for last opened file.
64           Default value is -1.</para>
65         </listitem>
66       </varlistentry>
67
68       <varlistentry>
69         <term>type</term>
70
71         <listitem>
72           <para>a string. Give the binary format used to write all the entries
73           of x.</para>
74         </listitem>
75       </varlistentry>
76
77       <varlistentry>
78         <term>x</term>
79
80         <listitem>
81           <para>a vector of floating point or integer type numbers</para>
82         </listitem>
83       </varlistentry>
84     </variablelist>
85   </refsection>
86
87   <refsection>
88     <title>Description</title>
89
90     <para>The <literal>mget</literal> function reads data in the input
91     specified by the stream parameter <literal>fd</literal> and returns a
92     vector of floating point data. The <literal>mgeti</literal> function reads
93     data in the input specified by the stream parameter <literal>fd</literal>
94     and returns a vector of integer data.</para>
95
96     <para>Data is read at the position at which the file pointer is currently
97     pointing and advances the indicator appropriately.</para>
98
99     <para>The <literal>type</literal> parameter is a conversion specifier
100     which may be set to any of the following flag characters (with default
101     value "l"):</para>
102
103     <para><emphasis role="bold">Note </emphasis>, On Windows, default behavior
104     is to skip byte 13 (0x0D). mopen should be called with the `b` option,
105     e.g. fd1=mopen(file1,'rb') , so that all bytes will be read without
106     exception.</para>
107
108     <para>Data type:</para>
109
110     <variablelist>
111       <varlistentry>
112         <term>d</term>
113         <listitem>
114           <para>double</para>
115         </listitem>
116       </varlistentry>
117
118       <varlistentry>
119         <term>f</term>
120         <listitem>
121           <para>float</para>
122         </listitem>
123       </varlistentry>
124
125       <varlistentry>
126         <term>l</term>
127         <listitem>
128           <para>long</para>
129         </listitem>
130       </varlistentry>
131
132       <varlistentry>
133         <term>i</term>
134         <listitem>
135           <para>int</para>
136         </listitem>
137       </varlistentry>
138
139       <varlistentry>
140         <term>s</term>
141         <listitem>
142           <para>short</para>
143         </listitem>
144       </varlistentry>
145
146       <varlistentry>
147         <term>c</term>
148         <listitem>
149           <para>character</para>
150         </listitem>
151       </varlistentry>
152     </variablelist>
153
154     <para>Optional flag:</para>
155
156     <variablelist>
157       <varlistentry>
158         <term>u..</term>
159         <listitem>
160           <para>unsigned (in combination with one of the above types)</para>
161         </listitem>
162       </varlistentry>
163
164       <varlistentry>
165         <term>..l</term>
166         <listitem>
167           <para>little endian (in combination with one of the above types)</para>
168         </listitem>
169       </varlistentry>
170
171       <varlistentry>
172         <term>..b</term>
173         <listitem>
174           <para>big endian (in combination with one of the above types)</para>
175         </listitem>
176       </varlistentry>
177     </variablelist>
178
179     <para>Bytes read are automatically swapped if necessary (by checking
180     little=endian status).</para>
181
182     <para>This default swapping behavior can be suprressed by adding a flag in
183     the mopen function.</para>
184
185     <para>Formats "l", "d", and "f" are only valid with the mget
186     function.</para>
187   </refsection>
188
189   <refsection>
190     <title>Examples</title>
191
192     <programlisting role="example"><![CDATA[ 
193 file1 = 'test1.bin';
194 file2 = 'test2.bin';
195 fd1=mopen(file1,'wb');
196 fd2=mopen(file2,'wb');
197 mput(1996,'ull',fd1);
198 mput(1996,'ull',fd2);
199 mclose(fd1);
200 mclose(fd2);
201
202 fd1=mopen(file1,'rb');
203 if 1996<>mget(1,'ull',fd1) ;write(%io(2),'Bug');end;
204 fd2=mopen(file2,'rb');
205 if 1996<>mget(1,'ull',fd2) ;write(%io(2),'Bug');end;
206 mclose(fd1);
207 mclose(fd2);
208  ]]></programlisting>
209   </refsection>
210
211   <refsection>
212     <title>See Also</title>
213
214     <simplelist type="inline">
215       <member><link linkend="mclose">mclose</link></member>
216
217       <member><link linkend="meof">meof</link></member>
218
219       <member><link linkend="mfprintf">mfprintf</link></member>
220
221       <member><link linkend="fprintfMat">fprintfMat</link></member>
222
223       <member><link linkend="mfscanf">mfscanf</link></member>
224
225       <member><link linkend="fscanfMat">fscanfMat</link></member>
226
227       <member><link linkend="mgetl">mgetl</link></member>
228
229       <member><link linkend="mgetstr">mgetstr</link></member>
230
231       <member><link linkend="mopen">mopen</link></member>
232
233       <member><link linkend="mprintf">mprintf</link></member>
234
235       <member><link linkend="mput">mput</link></member>
236
237       <member><link linkend="mputl">mputl</link></member>
238
239       <member><link linkend="mputstr">mputstr</link></member>
240
241       <member><link linkend="mscanf">mscanf</link></member>
242
243       <member><link linkend="mseek">mseek</link></member>
244
245       <member><link linkend="mtell">mtell</link></member>
246
247       <member><link linkend="mdelete">mdelete</link></member>
248     </simplelist>
249   </refsection>
250 </refentry>