869f41fd2512c0383c00a3a2c0209414d24dbf6d
[scilab.git] / scilab / modules / fileio / help / en_US / mget.xml
1 <?xml version="1.0" encoding="ISO-8859-1"?>
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 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" version="5.0-subset Scilab" xml:lang="en" xml:id="mget">
15   <info>
16     <pubdate>$LastChangedDate$</pubdate>
17   </info>
18   <refnamediv>
19     <refname>mget</refname>
20     <refpurpose> reads  byte or word in a given binary format and convert to double</refpurpose>
21   </refnamediv>
22   <refnamediv xml:id="mgeti">
23     <refname>mgeti</refname>
24     <refpurpose> reads  byte or word in a given binary format return an int type</refpurpose>
25   </refnamediv>
26   <refsynopsisdiv>
27     <title>Calling Sequence</title>
28     <synopsis>x=mget([n,type,fd])
29 x=mgeti([n,type,fd])</synopsis>
30   </refsynopsisdiv>
31   <refsection>
32     <title>Parameters</title>
33     <variablelist>
34       <varlistentry>
35         <term>n</term>
36         <listitem>
37           <para>:a positive scalar: The number of items to be read.</para>
38         </listitem>
39       </varlistentry>
40       <varlistentry>
41         <term>fd</term>
42         <listitem>
43           <para>scalar. The <literal>fd</literal> parameter returned by the function
44             <literal>mopen</literal>. -1 stands for last opened file. Default value
45             is -1.</para>
46         </listitem>
47       </varlistentry>
48       <varlistentry>
49         <term>type</term>
50         <listitem>
51           <para>a string. Give the binary format used to write all the entries of x.</para>
52         </listitem>
53       </varlistentry>
54       <varlistentry>
55         <term>x</term>
56         <listitem>
57           <para>a vector of floating point or integer type numbers</para>
58         </listitem>
59       </varlistentry>
60     </variablelist>
61   </refsection>
62   <refsection>
63     <title>Description</title>
64     <para>
65       The <literal>mget</literal> function reads data in the input specified by the
66       stream parameter <literal>fd</literal> and returns a vector of floating point data.
67       The <literal>mgeti</literal> function reads data in the input specified by the
68       stream parameter <literal>fd</literal> and returns a vector of integer data.
69     </para>
70     <para>
71       Data is read at the position at which the file pointer is currently
72       pointing and advances the indicator appropriately.
73     </para>
74     <para>
75       The <literal>type</literal> parameter is a conversion specifier which may be set to any of the
76       following flag characters (with default value "l"):
77     </para>
78     <para><emphasis role="bold">WARNING</emphasis>, when reading binary files under Windows to not forget to open
79       the file with the <literal>b</literal> option like
80       <literal>fd1=mopen(file1,'rb')</literal> if not the file will be interpreted as
81       text file and the bytes with value <literal>13</literal> will be interpreted as
82       newlines and ommitted. </para>
83     <variablelist>
84       <varlistentry>
85         <term>"l", "i", "s", "ul",  "ui", "us", "d", "f",  "c", "uc"</term>
86         <listitem>
87           <para>for reading respectively a long, an int, a short, an unsigned
88           long, an unsigned int, an unsigned short, a double, a float, a char
89           and an unsigned char. The bytes which are read are automatically
90           swapped if necessary (by checking little-endian status). This default
91           swapping mode can be suppressed by adding a flag in the
92           <literal>mopen</literal> function. Format "l", "d" and
93           "f" are valid only with the <literal>mget</literal>
94           function.</para>
95         </listitem>
96       </varlistentry>
97       <varlistentry>
98         <term>"..l" or "..b"</term>
99         <listitem>
100           <para>It is also possible to read in little-endian or big-endian mode
101           by adding a 'l' or 'b' character at the end of a type
102           specification. For example "db" will read a double in
103           big-endian mode.</para>
104         </listitem>
105       </varlistentry>
106     </variablelist>
107   </refsection>
108   <refsection>
109     <title>Examples</title>
110     <programlisting role="example"><![CDATA[
111     
112     file1 = 'test1.bin';
113     file2 = 'test2.bin';
114     fd1=mopen(file1,'wb');
115     fd2=mopen(file2,'wb');
116     mput(1996,'ull',fd1);
117     mput(1996,'ull',fd2);
118     mclose(fd1);
119     mclose(fd2);
120
121     fd1=mopen(file1,'rb');
122     if 1996<>mget(1,'ull',fd1) ;write(%io(2),'Bug');end;
123     fd2=mopen(file2,'rb');
124     if 1996<>mget(1,'ull',fd2) ;write(%io(2),'Bug');end;
125     mclose(fd1);
126     mclose(fd2);
127     
128   ]]></programlisting>
129   </refsection>
130   <refsection>
131     <title>See Also</title>
132     <simplelist type="inline">
133       <member>
134         <link linkend="mclose">mclose</link>
135       </member>
136       <member>
137         <link linkend="meof">meof</link>
138       </member>
139       <member>
140         <link linkend="mfprintf">mfprintf</link>
141       </member>
142       <member>
143         <link linkend="fprintfMat">fprintfMat</link>
144       </member>
145       <member>
146         <link linkend="mfscanf">mfscanf</link>
147       </member>
148       <member>
149         <link linkend="fscanfMat">fscanfMat</link>
150       </member>
151       <member>
152         <link linkend="mgetl">mgetl</link>
153       </member>
154       <member>
155         <link linkend="mgetstr">mgetstr</link>
156       </member>
157       <member>
158         <link linkend="mopen">mopen</link>
159       </member>
160       <member>
161         <link linkend="mprintf">mprintf</link>
162       </member>
163       <member>
164         <link linkend="mput">mput</link>
165       </member>
166       <member>
167         <link linkend="mputl">mputl</link>
168       </member>
169       <member>
170         <link linkend="mputstr">mputstr</link>
171       </member>
172       <member>
173         <link linkend="mscanf">mscanf</link>
174       </member>
175       <member>
176         <link linkend="mseek">mseek</link>
177       </member>
178       <member>
179         <link linkend="mtell">mtell</link>
180       </member>
181       <member>
182         <link linkend="mdelete">mdelete</link>
183       </member>
184     </simplelist>
185   </refsection>
186 </refentry>