* Bug #13102 fixed - matio: 7.3 support
[scilab.git] / scilab / modules / matio / help / en_US / matfile_open.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 - Vincent COUVERT
5     *
6     * This file must be used under the terms of the CeCILL.
7     * This source file is licensed as described in the file COPYING, which
8     * you should have received as part of this distribution.  The terms
9     * are also available at
10     * http://www.cecill.info/licences/Licence_CeCILL_V2.1-en.txt
11     *
12     -->
13 <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" xmlns:scilab="http://www.scilab.org" xml:lang="en" xml:id="matfile_open">
14     <refnamediv>
15         <refname>matfile_open</refname>
16         <refpurpose>Opens a Matlab binary MAT-file.</refpurpose>
17     </refnamediv>
18     <refsynopsisdiv>
19         <title>Calling Sequence</title>
20         <synopsis>fd = matfile_open(filename[, mode[, version]])</synopsis>
21     </refsynopsisdiv>
22     <refsection>
23         <title>Arguments</title>
24         <variablelist>
25             <varlistentry>
26                 <term>filename</term>
27                 <listitem>
28                     <para>String: the path of the file. Must contain only ANSI character.</para>
29                 </listitem>
30             </varlistentry>
31             <varlistentry>
32                 <term>mode</term>
33                 <listitem>
34                     <para>
35                         String: file access type (<literal>"r"</literal> by default).
36                     </para>
37                     <itemizedlist>
38                         <listitem>
39                             <para>
40                                 <emphasis>"r"</emphasis>: opens the file for reading.
41                             </para>
42                         </listitem>
43                         <listitem>
44                             <para>
45                                 <emphasis>"w"</emphasis>: opens the file for writing.
46                             </para>
47                         </listitem>
48                     </itemizedlist>
49                 </listitem>
50             </varlistentry>
51             <varlistentry>
52                 <term>version</term>
53                 <listitem>
54                     <para>
55                         Scalar string: file version format (<literal>"5"</literal> by default).
56                     </para>
57                     <itemizedlist>
58                         <listitem>
59                             <para>
60                                 <emphasis>"5"</emphasis>: Matlab 5 file.
61                             </para>
62                         </listitem>
63                         <listitem>
64                             <para>
65                                 <emphasis>"7.3"</emphasis>: Matlab 7.3 file.
66                             </para>
67                         </listitem>
68                     </itemizedlist>
69                 </listitem>
70             </varlistentry>
71             <varlistentry>
72                 <term>fd</term>
73                 <listitem>
74                     <para>Real: file descriptor (-1 if opening failed).</para>
75                 </listitem>
76             </varlistentry>
77         </variablelist>
78     </refsection>
79     <refsection>
80         <title>Description</title>
81         <para>
82             Opens a Matlab binary MAT-file for reading or writing data.
83         </para>
84         <para>
85             <warning>
86                 If <varname>mode</varname> is set to <literal>w</literal>, the content of <varname>filename</varname> will be reseted.
87             </warning>
88         </para>
89     </refsection>
90     <refsection>
91         <title>Examples</title>
92         <programlisting role="example"><![CDATA[
93 A = rand(10, 10);
94 B = sprand(100, 100, 0.1);
95 savematfile("test_matfile.mat", "A", "B", "-v6");
96 clear();
97 fd = matfile_open("test_matfile.mat");
98 matfile_listvar(fd)
99 matfile_close(fd);
100
101 //fd = matfile_open("test_matfile.mat", "w"); // Empty test_matfile.mat
102
103 //fd = matfile_open("test_matfile.mat", "w", "7.3"); // Empty test_matfile.mat as a Matlab 7.3 file
104  ]]></programlisting>
105     </refsection>
106     <refsection role="see also">
107         <title>See Also</title>
108         <simplelist type="inline">
109             <member>
110                 <link linkend="matfile_close">matfile_close</link>
111             </member>
112             <member>
113                 <link linkend="matfile_varreadnext">matfile_varreadnext</link>
114             </member>
115             <member>
116                 <link linkend="matfile_varwrite">matfile_varwrite</link>
117             </member>
118             <member>
119                 <link linkend="matfile_listvar">matfile_listvar</link>
120             </member>
121         </simplelist>
122     </refsection>
123     <refsection>
124         <title>Bibliography</title>
125         <para>
126             This function uses MATIO library (
127             <literal>
128                 <ulink url="http://sourceforge.net/projects/matio/">http://sourceforge.net/projects/matio/</ulink>
129             </literal>
130             ).
131         </para>
132     </refsection>
133     <refsection>
134         <title>History</title>
135         <revhistory>
136             <revision>
137                 <revnumber>5.5.0</revnumber>
138                 <revremark>Support for Matlab 7.3 files.</revremark>
139             </revision>
140         </revhistory>
141     </refsection>
142 </refentry>