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