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