433131f1537bde5f07666dd3156b7076d3175eaf
[scilab.git] / scilab / modules / io / help / en_US / save.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) XXXX-2008 - INRIA
5  *
6  * Copyright (C) 2012 - 2016 - Scilab Enterprises
7  *
8  * This file is hereby licensed under the terms of the GNU GPL v2.0,
9  * pursuant to article 5.3.4 of the CeCILL v.2.1.
10  * This file was originally licensed under the terms of the CeCILL v2.1,
11  * and continues to be available under such terms.
12  * For more information, see the COPYING file which you should have received
13  * along with this program.
14  *
15  -->
16 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns4="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:id="save" xml:lang="en">
17     <refnamediv>
18         <refname>save</refname>
19         <refpurpose>Save a variable or a serie of variables in a binary
20             file
21         </refpurpose>
22     </refnamediv>
23     <refsynopsisdiv>
24         <title>Syntax</title>
25         <synopsis>save(filename [,x1,x2,...,xn])
26             save(fd [,x1,x2,...,xn])
27         </synopsis>
28     </refsynopsisdiv>
29     <refsection>
30         <title>Arguments</title>
31         <variablelist>
32             <varlistentry>
33                 <term>filename</term>
34                 <listitem>
35                     <para>Character string containing the path of the file</para>
36                 </listitem>
37             </varlistentry>
38             <varlistentry>
39                 <term>fd</term>
40                 <listitem>
41                     <para>A file descriptor given by a call to mopen</para>
42                 </listitem>
43             </varlistentry>
44             <varlistentry>
45                 <term>xi</term>
46                 <listitem>
47                     <para>Arbitrary Scilab variable(s)</para>
48                 </listitem>
49             </varlistentry>
50         </variablelist>
51     </refsection>
52     <refsection>
53         <title>Description</title>
54         <para>
55             The <literal>save</literal> command can be used to save Scilab
56             current variables in a binary file. If a variable is a graphic handle, the
57             <literal>save</literal> function saves all the corresponding <link linkend="graphics_entities">graphics_entities</link> definition.
58         </para>
59         <para>The file can be given either by its paths or by its descriptor
60             previously given by <literal>mopen</literal>.
61         </para>
62         <para>
63             <literal>save(filename)</literal> saves all current variables in the
64             file defined by <literal>filename</literal>.
65         </para>
66         <para>
67             <literal>save(fd)</literal> saves all current variables in the file
68             defined by the descriptor <literal>fd</literal>. <emphasis role="bold">This prototype is obsolete and will be removed in Scilab 6.</emphasis>
69         </para>
70         <para>
71             <literal>save(filename,x,y)</literal> or <literal>save(fd,x,y)</literal> (with <literal>x</literal> and <literal>y</literal> variables of your environment) saves only named variables <literal>x</literal> and <literal>y</literal>. <literal>save(fd,x,y)</literal> <emphasis role="bold"> is obsolete and will be removed in Scilab 6.</emphasis>
72         </para>
73         <para>
74             <literal>save(filename,"x","y")</literal> (with <literal>"x"</literal> and <literal>"y"</literal> names of variables of your environment) will save your data using the SOD (Scilab Open Data) format (based on HDF5), format that will be readable by Scilab 6 family.
75         </para>
76         <para>
77             <literal>save(filename,"-append","w", "z")</literal> (with <literal>"w"</literal> and <literal>"z"</literal> names of variables of your environment) will append your data in the existing SOD file called <literal>filename</literal>.
78         </para>
79         <para>
80             The change of format between the family 5 and 6 of Scilab has been decided because the 5 format is undocumented, not specified and hard to read. SOD (Scilab 6 default format) is fully documented and easy to read through HDF5 libraries or applications.
81         </para>
82         <para>
83             Saved variables can be reloaded by the
84             <literal>
85                 <link linkend="load">load</link>
86             </literal>
87             command.
88         </para>
89         <para>Note that the written file is portable to other operating systems and architectures (little and big endian).
90         </para>
91     </refsection>
92     <refsection>
93         <title>Examples</title>
94         <programlisting role="example"><![CDATA[
95 // Binary format readable up to Scilab 5 family
96 a=eye(2,2);b=ones(a);
97 save('val.dat',a,b);
98 clear a
99 clear b
100 load('val.dat','a','b');
101
102 // sequential save into a file
103 fd=mopen('TMPDIR/foo','wb')
104 for k=1:4, x=k^2;save(fd,x,k),end
105 mclose(fd)
106 fd=mopen('TMPDIR/foo','rb')
107 for i=1:4, load(fd,'x','k');x,k,end
108 mclose(fd)
109
110 // appending variables to an old save file
111 fd=mopen('TMPDIR/foo','rb+')
112 mseek(0,fd,'end')
113 lst=list(1,2,3)
114 save(fd,lst)
115 mclose(fd)
116
117 // Binary format readable by Scilab 5.4.X and Scilab 6 family
118 a=eye(2,2);b=ones(a);
119 save("val.sod", "a", "b");
120 clear a
121 clear b
122 load("val.sod", "a", "b");
123  ]]></programlisting>
124     </refsection>
125     <refsection role="see also">
126         <title>See also</title>
127         <simplelist type="inline">
128             <member>
129                 <link linkend="load">load</link>
130             </member>
131             <member>
132                 <link linkend="write">write</link>
133             </member>
134             <member>
135                 <link linkend="save_format">save_format</link>
136             </member>
137             <member>
138                 <link linkend="mopen">mopen</link>
139             </member>
140         </simplelist>
141     </refsection>
142     <refsection>
143         <title>History</title>
144         <revhistory>
145             <revision>
146                 <revnumber>5.0.0</revnumber>
147                 <revremark>
148                     All <link linkend="uimenu">uimenu</link> or <link linkend="uicontrol">uicontrol</link> handles are also saved by this function.
149                 </revremark>
150             </revision>
151             <revision>
152                 <revnumber>5.4.0</revnumber>
153                 <revdescription>
154                     <itemizedlist>
155                         <listitem>When called with variables names (character string) as input, variables are saved in SOD format, format that will be readable by Scilab 6 family.</listitem>
156                         <listitem>The Scilab 5.X format is deprecated and will be removed with Scilab 6.</listitem>
157                         <listitem>Using save with a file descriptor as first input argument is deprecated and will be removed with Scilab 6.</listitem>
158                     </itemizedlist>
159                 </revdescription>
160             </revision>
161         </revhistory>
162     </refsection>
163 </refentry>