[doc] save() page updated for 6.0 (rewritten)
[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  * Copyright (C) 2012 - 2016 - Scilab Enterprises
6  * Copyright (C) 2018 - Samuel GOUGEON
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"
17         xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns4="http://www.w3.org/1999/xhtml"
18         xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook"
19         xmlns:scilab="http://www.scilab.org" xml:id="save" xml:lang="en">
20     <refnamediv>
21         <refname>save</refname>
22         <refpurpose>Saves some chosen variables in a binary data file
23         </refpurpose>
24     </refnamediv>
25     <refsynopsisdiv>
26         <title>Syntax</title>
27         <synopsis>
28             save(filename)
29             save(filename, x1, x2,...,xn)
30             save(filename, x1, x2,...,xn, "-append")
31         </synopsis>
32     </refsynopsisdiv>
33     <refsection>
34         <title>Arguments</title>
35         <variablelist>
36             <varlistentry>
37                 <term>filename</term>
38                 <listitem>
39                     <para>Character string containing the path of the file.</para>
40                 </listitem>
41             </varlistentry>
42             <varlistentry>
43                 <term>xi</term>
44                 <listitem>
45                     <para>
46                         Names (as strings) of Scilab variables to be saved. Objects returned by
47                         expressions -- like gcf() -- can't be directly saved. They must be
48                         explicitly named: <literal>f = gcf(); save(filename, "f")</literal>.
49                     </para>
50                 </listitem>
51             </varlistentry>
52         </variablelist>
53     </refsection>
54     <refsection>
55         <title>Description</title>
56         <para>
57             <literal>save(filename)</literal> saves in the file defined by <literal>filename</literal>
58             <emphasis>all</emphasis> Scilab variables defined by the user, and reachable at the
59             current level.
60         </para>
61         <note>
62             <itemizedlist>
63                 <listitem>
64                     <para>
65                         When some global variables are defined, only their local counterparts
66                         -- if any -- can be saved. Hence, the "global status" is never saved.
67                     </para>
68                 </listitem>
69                 <listitem>
70                     <para>
71                         If a variable is a graphic handle, <literal>save(..)</literal> records all
72                         the corresponding <emphasis>descending</emphasis>
73                         <link linkend="graphics_entities">graphical entity</link> definition,
74                         including its existing children -- if any.
75                     </para>
76                 </listitem>
77                 <listitem>
78                     <para>
79                         Saving a XML pointer is possible but does not save the pointed object. If in
80                         the meantime the XML object is deleted, restoring its pointer won't restore
81                         the object. Please see the dedicated example.
82                     </para>
83                 </listitem>
84                 <listitem>
85                     <para>
86                         TCL variables defined from Scilab (with <link linkend="TCL_SetVar">TCL_SetVar</link>)
87                         can't be saved. Only their counterparts in Scilab -- if any -- can be considered.
88                     </para>
89                 </listitem>
90                 <listitem>
91                     <para>
92                         Scilab save/load functions use the Scilab Open Data (SOD) binary format,
93                         based on the HDF-5 storage format. The SOD format is described
94                         <link linkend="save_format">there</link>. Scilab binary data files can be read
95                         and handled through external HDF-5 libraries or applications.
96                     </para>
97                 </listitem>
98             </itemizedlist>
99         </note>
100         <para>
101             When only some variables chosen among all defined ones must be saved, their names must
102             be listed after the filename, as in <literal>save(filename,"x","y")</literal>. If one
103             indicated variable is not defined, the file is not created or overwritten and an error
104             is yielded.
105         </para>
106         <para>
107             The <literal>"-append"</literal> keyword can be used in option at any place after
108             the <varname>filename</varname>. Then, listed variables are appended to the existing
109             file. If some listed variables already exist in the file, their stored values are updated.
110         </para>
111         <para>
112             Saved variables can be reloaded by the
113             <literal>
114                 <link linkend="load">load</link>
115             </literal>
116             command.
117         </para>
118         <note>
119             The archives files generated with save() are portable to other operating systems and
120             architectures (little and big endian automatically handled).
121         </note>
122         <warning>
123             Built-in functions can't be saved.
124         </warning>
125     </refsection>
126     <refsection>
127         <title>Examples</title>
128         <para>
129             With homogeneous arrays of simple data types:
130         </para>
131         <programlisting role="example"><![CDATA[
132 // For each created object, we make a current copy for comparison after restoring.
133 b = [%t %f %f];          bc = b;  // Booleans
134 i = int8([0 -17 38 ]);   ic = i;  // Encoded integers
135 d = [%pi %e %inf %i];    dc = d;  // Decimal numbers (real or complex numbers)
136 p = (1-%z)^[1 2];        pc = p;  // Polynomials (real or complex coefficients)
137 r = %z./(1-%z)^[1 2];    rc = r;  // Rationals (real or complex coefficients)
138 t = ["Sci" "‫البرمجیات‬"];    tc = t;  // Texts
139 sp = sprand(4,10,0.1);  spc = sp; // Sparse matrix of numbers
140 spb = sp < 0.5;        spbc = spb;// Sparse matrix of boolean numbers
141
142 path = TMPDIR + "/test.dat";
143 save(path, "b","i","d","p","r","t","sp","spb")
144 clear b i d p r t sp spb
145 isdef(["b" "i" "d" "p" "r" "t" "sp" "spb"],"l")
146 listvarinfile(path);
147 load(path);
148 isdef(["b" "i" "d" "p" "r" "t" "sp" "spb"],"l")
149 [b==bc, i==ic, d==dc, t==tc, p==pc, r==rc, and(sp==spc), and(spb==spbc)]
150     ]]></programlisting>
151         <screen><![CDATA[
152 --> path = TMPDIR + "/test.dat";
153 --> save(path, "b","i","d","p","r","t","sp","spb")
154 --> clear b i d p r t sp spb
155 --> isdef(["b" "i" "d" "p" "r" "t" "sp" "spb"],"l")
156  ans  =
157   F F F F F F F F
158
159 --> listvarinfile(path);
160 Name                     Type           Size            Bytes
161 -------------------------------------------------------------
162 b                        boolean        1 by 3          12
163 d                        double         1 by 4          64
164 i                        integer        1 by 3          3
165 p                        polynomial     1 by 2          40
166 r                        tlist          4               108
167 sp                       sparse         4 by 10         76
168 spb                      boolean sparse 4 by 10         160
169 t                        string         1 by 2          108
170
171 --> load(path);
172 --> isdef(["b" "i" "d" "p" "r" "t" "sp" "spb"],"l")
173  ans  =
174   T T T T T T T T
175
176 --> [b==bc, i==ic, d==dc, t==tc, p==pc, r==rc, and(sp==spc), and(spb==spbc)]
177 ans  =
178   T T T T T T T T T T T T T T T T T
179 ]]></screen>
180         <para>
181             With a user-defined macro:
182         </para>
183         <programlisting role="example"><![CDATA[
184 path = TMPDIR + "/test.dat";
185 function myTest(), disp("User-defined macros can be saved"), endfunction
186 save(path, "myTest")
187 clear myTest
188 listvarinfile(path);
189 load(path);
190 myTest()
191     ]]></programlisting>
192         <screen><![CDATA[
193 --> clear myTest
194 --> listvarinfile(path);
195 Name                     Type           Size            Bytes
196 -------------------------------------------------------------
197 myTest                   macro          1 by 1          0
198
199 --> load(path);
200 --> myTest()
201  User-defined macros can be saved
202 ]]></screen>
203         <para>
204             With (nested) heterogeneous containers:
205         </para>
206         <programlisting role="example"><![CDATA[
207 // lists
208 L = list(%pi,%t,%s^2,"abc",{"Scilab" 2},list(%e,%z/(1-%z))); Lc = L;
209 // cells arrays
210 c = {%pi, %t ; %s^2, "abc"};  cc = c;
211 // array of structures
212 s = struct("n",%i+1, "p",(1+%z)^3, "L",L, "c",c); sc = s;
213
214 path = TMPDIR + "/test.dat";
215 save(path, "L", "c", "s")
216 clear L c s
217 isdef(["L" "c" "s"], "l")
218 listvarinfile(path);
219 load(path);
220 [isequal(L,Lc) isequal(c,cc) isequal(s,sc)]
221     ]]></programlisting>
222         <screen><![CDATA[
223 --> isdef(["L" "c" "s"], "l")
224  ans  =
225   F F F
226
227 --> listvarinfile(path);
228 Name                     Type           Size            Bytes
229 -------------------------------------------------------------
230 L                        list           6               156
231 c                        cell           2 by 2          48
232 s                        struct         2 by 2          864
233
234 --> load(path);
235 --> [isequal(L,Lc) isequal(c,cc) isequal(s,sc)]
236  ans  =
237   F F F
238 ]]></screen>
239         <para>
240             With some graphic handles:
241         </para>
242         <programlisting role="example"><![CDATA[
243 clf reset
244 subplot(1,2,1), param3d()
245 subplot(1,2,2), plot2d4(), xtitle("plot2d4()"); a = gca();
246 path = TMPDIR + "/test.dat";
247 save(path, "a");       // We save only the right axes (plot2d4)
248 clf reset, clear a
249 xload(path);           // The right axes is restored and rendered
250 gcf().axes_size = [700 300];
251     ]]></programlisting>
252         <scilab:image>
253             subplot(1,2,1), param3d()
254             subplot(1,2,2), plot2d4(), xtitle("plot2d4()"); a = gca();
255             path = TMPDIR + "/test.dat";
256             save(path, "a");       // We save only the right axes (hist3d)
257             clf reset, clear a
258             xload(path);           // The right axes is restored and rendered
259             gcf().axes_size = [700 300];
260         </scilab:image>
261         <para>
262             With a global variable:
263         </para>
264         <programlisting role="example"><![CDATA[
265 path = TMPDIR + "/test.dat";
266 clear a
267 global a, a = 1.234;
268 isglobal a
269 save(path, "a")
270 clear a, clearglobal a
271 load(path); a
272 isglobal("a")   // The global attribute was not saved and so is not restored
273     ]]></programlisting>
274         <screen><![CDATA[
275 --> isglobal a
276  ans  =
277   T
278 --> save(path, "a")
279 --> clear a, clearglobal a
280 --> load(path); a
281  a  =
282    1.234
283 --> isglobal("a")
284  ans  =
285   F
286 ]]></screen>
287         <para>
288             With a XML pointer:
289         </para>
290         <programlisting role="example"><![CDATA[
291 path = TMPDIR + "/test.dat";
292 doc = xmlReadStr("<root><b>Hello</b></root>");
293 save(path, "doc")
294 clear doc             // This does not delete the document
295 load(path); doc       // We restore the saved pointer to the document. It is still valid.
296 // Let's delete both the document and the pointer to it:
297 xmlDelete(doc), clear doc
298 load(path);           // We restore the saved pointer (to the unexisting document)
299 isdef("doc","l")        // The pointer is restored...
300 xmlIsValidObject doc  //  but not the pointed document
301     ]]></programlisting>
302         <screen><![CDATA[
303 --> path = TMPDIR + "/test.dat";
304 --> doc = xmlReadStr("<root><b>Hello</b></root>");
305 --> save(path, "doc")
306 --> clear doc
307 --> load(path); doc
308  doc  =
309 XML Document
310 url: Undefined
311 root: XML Element
312
313 --> xmlDelete(doc), clear doc
314 --> load(path)
315 --> isdef("doc","l")
316  ans  =
317   T
318  doc  =
319 --> xmlIsValidObject doc
320  ans  =
321   F
322 ]]></screen>
323         <para>
324             With the "-append" option:
325         </para>
326         <programlisting role="example"><![CDATA[
327 a = 1; b = %t;
328 path = TMPDIR + "/test.dat";
329 save(path, "a", "b");
330 listvarinfile(path);
331 a = [%e %pi];
332 c = %i;
333 save(path, "a", "c", "-append");
334 listvarinfile(path);
335 clear a
336 load(path, "a"); a
337     ]]></programlisting>
338         <screen><![CDATA[
339 --> save(path, "a", "b");
340 --> listvarinfile(path);
341 Name                     Type           Size            Bytes
342 -------------------------------------------------------------
343 a                        double         1 by 1          8
344 b                        boolean        1 by 1          4
345
346 --> a = [%e %pi];
347 --> c = %i;
348 --> save(path, "a", "c", "-append");
349 --> listvarinfile(path);
350 Name                     Type           Size            Bytes
351 -------------------------------------------------------------
352 a                        double         1 by 2          16
353 b                        boolean        1 by 1          4
354 c                        double         1 by 1          16
355
356 --> clear a
357 --> load(path, "a"); a    // has been updated
358  a  =
359    2.7182818   3.1415927
360 ]]></screen>
361         <para>
362             save() can't save TCL variables:
363         </para>
364         <programlisting role="example"><![CDATA[
365 TCL_SetVar("myPi", 3.14);   // Creates the myPi variable in the TCL session
366 myPi    // => error: the variable is a TCL one, not a Scilab one => It can't be save()d
367 ]]></programlisting>
368         <screen><![CDATA[
369 --> myPi
370 Undefined variable: myPi
371 ]]></screen>
372     </refsection>
373     <refsection role="see also">
374         <title>See also</title>
375         <simplelist type="inline">
376             <member>
377                 <link linkend="load">load</link>
378             </member>
379             <member>
380                 <link linkend="save_format">save_format</link>
381             </member>
382             <member>
383                 <link linkend="savematfile">savematfile</link>
384             </member>
385             <member>
386                 <link linkend="xsave">xsave</link>
387             </member>
388             <member>
389                 <link linkend="saveGui">saveGui</link>
390             </member>
391             <member>
392                 <link linkend="write">write</link>
393             </member>
394             <member>
395                 <link linkend="TCL_SetVar">TCL_SetVar</link>
396             </member>
397         </simplelist>
398     </refsection>
399     <refsection>
400         <title>History</title>
401         <revhistory>
402             <revision>
403                 <revnumber>5.0.0</revnumber>
404                 <revremark>
405                     All <link linkend="uimenu">uimenu</link> or
406                     <link linkend="uicontrol">uicontrol</link> handles are also saved by this function.
407                 </revremark>
408             </revision>
409             <revision>
410                 <revnumber>5.4.0</revnumber>
411                 <revdescription>
412                     <itemizedlist>
413                         <listitem>
414                             When called with variables names (character string) as input, variables
415                             are saved in SOD format (HDF5-based).
416                         </listitem>
417                         <listitem>
418                             The Scilab &lt;5.4 binary data format is deprecated.
419                         </listitem>
420                         <listitem>
421                             Using save() with a file descriptor as first input argument is deprecated.
422                         </listitem>
423                     </itemizedlist>
424                 </revdescription>
425             </revision>
426             <revision>
427                 <revnumber>6.0</revnumber>
428                 <revremark>
429                     <itemizedlist>
430                         <listitem>
431                             save() no longer supports the old Scilab &lt;5.4 data format.
432                         </listitem>
433                         <listitem>
434                             The syntaxes save(fid) and save(fid, x1,..) with a file id are no longer
435                             supported.
436                         </listitem>
437                     </itemizedlist>
438                 </revremark>
439             </revision>
440         </revhistory>
441     </refsection>
442 </refentry>