Added CeCILL headers
[scilab.git] / scilab / modules / fileio / help / en_US / mget.xml
1 <?xml version="1.0" encoding="ISO-8859-1" standalone="no"?>
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 <!DOCTYPE MAN SYSTEM "../../../../modules/helptools/help.dtd">
15 <MAN>
16   <LANGUAGE>eng</LANGUAGE>
17   <TITLE>mget</TITLE>
18   <TYPE>Scilab Function</TYPE>
19   <DATE>$LastChangedDate$</DATE>
20   <SHORT_DESCRIPTION name="mget"> reads  byte or word in a given binary format and convert to double</SHORT_DESCRIPTION>
21   <SHORT_DESCRIPTION name="mgeti"> reads  byte or word in a given binary format return an int type</SHORT_DESCRIPTION>
22   <CALLING_SEQUENCE>
23     <CALLING_SEQUENCE_ITEM>x=mget([n,type,fd])  </CALLING_SEQUENCE_ITEM>
24     <CALLING_SEQUENCE_ITEM>x=mgeti([n,type,fd])  </CALLING_SEQUENCE_ITEM>
25   </CALLING_SEQUENCE>
26   <PARAM>
27     <PARAM_INDENT>
28       <PARAM_ITEM>
29         <PARAM_NAME>n</PARAM_NAME>
30         <PARAM_DESCRIPTION>
31           <SP>:a positive scalar: The number of items to be read.</SP>
32         </PARAM_DESCRIPTION>
33       </PARAM_ITEM>
34       <PARAM_ITEM>
35         <PARAM_NAME>fd</PARAM_NAME>
36         <PARAM_DESCRIPTION>
37           <SP>: scalar. The <VERB>fd</VERB> parameter returned by the function
38             <VERB>mopen</VERB>. -1 stands for last opened file. Default value
39             is -1.</SP> 
40         </PARAM_DESCRIPTION>
41       </PARAM_ITEM>
42       <PARAM_ITEM>
43         <PARAM_NAME>type</PARAM_NAME>
44         <PARAM_DESCRIPTION>
45           <SP>: a string. Give the binary format used to write all the entries of x.</SP>
46         </PARAM_DESCRIPTION>
47       </PARAM_ITEM>
48       <PARAM_ITEM>
49         <PARAM_NAME>x</PARAM_NAME>
50         <PARAM_DESCRIPTION>
51           <SP>: a vector of floating point or integer type numbers</SP>
52         </PARAM_DESCRIPTION>
53       </PARAM_ITEM>
54     </PARAM_INDENT>
55   </PARAM>
56   <DESCRIPTION>
57     <P>
58       The <VERB>mget</VERB> function reads data in the input specified by the
59       stream parameter <VERB>fd</VERB> and returns a vector of floating point data.
60       The <VERB>mgeti</VERB> function reads data in the input specified by the
61       stream parameter <VERB>fd</VERB> and returns a vector of integer data.
62     </P>
63     <P>
64       Data is read at the position at which the file pointer is currently
65       pointing and advances the indicator appropriately.
66     </P>
67     <P>
68       The <VERB>type</VERB> parameter is a conversion specifier which may be set to any of the
69       following flag characters (with default value &quot;l&quot;):
70     </P>
71     <P> <BD>WARNING</BD>, when reading binary files under Windows to not forget to open
72       the file with the <VERB>b</VERB> option like
73       <VERB>fd1=mopen(file1,'rb')</VERB> if not the file will be interpreted as
74       text file and the bytes with value <VERB>13</VERB> will be interpreted as
75       newlines and ommitted. </P>
76
77     <DESCRIPTION_INDENT>
78       <DESCRIPTION_ITEM label="&quot;l&quot;, &quot;i&quot;, &quot;s&quot;, &quot;ul&quot;,
79         &quot;ui&quot;, &quot;us&quot;, &quot;d&quot;, &quot;f&quot;,
80         &quot;c&quot;, &quot;uc&quot;"> 
81         <SP>: for reading respectively a long, an int, a short, an unsigned
82           long, an unsigned int, an unsigned short, a double, a float, a char
83           and an unsigned char. The bytes which are read are automatically
84           swapped if necessary (by checking little-endian status). This default
85           swapping mode can be suppressed by adding a flag in the
86           <VERB>mopen</VERB> function. Format &quot;l&quot;, &quot;d&quot; and
87           &quot;f&quot; are valid only with the <VERB>mget</VERB>
88           function.</SP> 
89       </DESCRIPTION_ITEM>
90       <DESCRIPTION_ITEM label="&quot;..l&quot; or &quot;..b&quot;">
91         <SP>: It is also possible to read in little-endian or big-endian mode
92           by adding a 'l' or 'b' character at the end of a type
93           specification. For example &quot;db&quot; will read a double in
94           big-endian mode.</SP> 
95       </DESCRIPTION_ITEM>
96     </DESCRIPTION_INDENT>
97   </DESCRIPTION>
98   <EXAMPLE>
99     <![CDATA[
100     file1 = 'test1.bin';
101     file2 = 'test2.bin';
102     fd1=mopen(file1,'wb');
103     fd2=mopen(file2,'wb');
104     mput(1996,'ull',fd1);
105     mput(1996,'ull',fd2);
106     mclose(fd1);
107     mclose(fd2);
108
109     fd1=mopen(file1,'rb');
110     if 1996<>mget(1,'ull',fd1) ;write(%io(2),'Bug');end;
111     fd2=mopen(file2,'rb');
112     if 1996<>mget(1,'ull',fd2) ;write(%io(2),'Bug');end;
113     mclose(fd1);
114     mclose(fd2);
115     ]]>
116   </EXAMPLE>
117   <SEE_ALSO>
118     <SEE_ALSO_ITEM>
119       <LINK>mclose</LINK>
120     </SEE_ALSO_ITEM>
121     <SEE_ALSO_ITEM>
122       <LINK>meof</LINK>
123     </SEE_ALSO_ITEM>
124     <SEE_ALSO_ITEM>
125       <LINK>mfprintf</LINK>
126     </SEE_ALSO_ITEM>
127     <SEE_ALSO_ITEM>
128       <LINK>fprintfMat</LINK>
129     </SEE_ALSO_ITEM>
130     <SEE_ALSO_ITEM>
131       <LINK>mfscanf</LINK>
132     </SEE_ALSO_ITEM>
133     <SEE_ALSO_ITEM>
134       <LINK>fscanfMat</LINK>
135     </SEE_ALSO_ITEM>
136     <SEE_ALSO_ITEM>
137       <LINK>mgetl</LINK>
138     </SEE_ALSO_ITEM>
139     <SEE_ALSO_ITEM>
140       <LINK>mgetstr</LINK>
141     </SEE_ALSO_ITEM>
142     <SEE_ALSO_ITEM>
143       <LINK>mopen</LINK>
144     </SEE_ALSO_ITEM>
145     <SEE_ALSO_ITEM>
146       <LINK>mprintf</LINK>
147     </SEE_ALSO_ITEM>
148     <SEE_ALSO_ITEM>
149       <LINK>mput</LINK>
150     </SEE_ALSO_ITEM>
151     <SEE_ALSO_ITEM>
152       <LINK>mputl</LINK>
153     </SEE_ALSO_ITEM>
154     <SEE_ALSO_ITEM>
155       <LINK>mputstr</LINK>
156     </SEE_ALSO_ITEM>
157     <SEE_ALSO_ITEM>
158       <LINK>mscanf</LINK>
159     </SEE_ALSO_ITEM>
160     <SEE_ALSO_ITEM>
161       <LINK>mseek</LINK>
162     </SEE_ALSO_ITEM>
163     <SEE_ALSO_ITEM>
164       <LINK>mtell</LINK>
165     </SEE_ALSO_ITEM>
166     <SEE_ALSO_ITEM>
167       <LINK>mdelete</LINK>
168     </SEE_ALSO_ITEM>
169   </SEE_ALSO>
170 </MAN>