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>