scilab/modules/io/help/en_US/load.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:ns3="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="load" xml:lang="en">
  20     <refnamediv>
  21         <refname>load</refname>
  22         <refpurpose>
  23             Loads some archived variables, a saved graphic figure, a library of functions
  24         </refpurpose>
  25     </refnamediv>
  26     <refsynopsisdiv>
  27         <title>Syntax</title>
  28         <synopsis>
  29             load(filename)
  30             load(filename, x1,...,xn)
  31             load("path/myfigure.scg")
  32             load("libdir/lib")
  33         </synopsis>
  34     </refsynopsisdiv>
  35     <refsection>
  36         <title>Arguments</title>
  37         <variablelist>
  38             <varlistentry>
  39                 <term>filename</term>
  40                 <listitem>
  41                     <para>path and name of the single file where archived variables are stored.
  42                         Any prepended "SCI", "TMPDIR", "SCIHOME" or "home" word being a predefined
  43                         Scilab variable is expanded into its value.
  44                     </para>
  45                 </listitem>
  46             </varlistentry>
  47             <varlistentry>
  48                 <term>xi</term>
  49                 <listitem>
  50                     <para>
  51                         name(s) -- given as strings -- of Scilab variable(s) to be recovered.
  52                     </para>
  53                 </listitem>
  54             </varlistentry>
  55         </variablelist>
  56     </refsection>
  57     <refsection>
  58         <title>Description</title>
  59         <refsect3>
  60             <title>Archived variables</title>
  61             <para>
  62                 The <literal>load</literal> command can be used to reload in the Scilab session
  63                 variables previously saved in a file with the
  64                 <literal>
  65                     <link linkend="save">save</link>
  66                 </literal>
  67                 command.
  68             </para>
  69             <para>
  70                 <literal>load(filename,'x','y')</literal> loads only variables <literal>x, y</literal>.
  71                 <itemizedlist>
  72                     <listitem>
  73                         <para>
  74                             The list of variables stored in a file can be retrieved with the
  75                             <link linkend="listvarinfile">listvarinfile</link> function.
  76                         </para>
  77                     </listitem>
  78                     <listitem>
  79                         <para>
  80                             <literal>load()</literal> loads restores variables in the current scope
  81                             (not on the global one).
  82                         </para>
  83                     </listitem>
  84                     <listitem>
  85                         <para>
  86                             If a variable to be loaded is not in the file, an error is generated.
  87                         </para>
  88                     </listitem>
  89                     <listitem>
  90                         If a restored variable has the same name as an existing variable of
  91                         the current scope, the current variable is silently overwritten.
  92                     </listitem>
  93                     <listitem>
  94                         <para>
  95                             When a variable to be restored is a graphic handle/identifier, the
  96                             corresponding <link linkend="graphics_entities">graphic entity</link>
  97                             is drawn with the current graphic driver.
  98                         </para>
  99                     </listitem>
 100                     <listitem>
 101                         <para>
 102                             The SOD binary format used by Scilab 6 to save (and load) variables is
 103                             based on the HDF5 format. It is fully documented and easy to read
 104                             through HDF5 libraries or applications.
 105                         </para>
 106                     </listitem>
 107                     <listitem>
 108                         <para>
 109                             Data files written with Scilab from other operating systems and
 110                             architectures (little and big endian) are portable and accepted.
 111                         </para>
 112                     </listitem>
 113                 </itemizedlist>
 114             </para>
 115         </refsect3>
 116         <refsect3>
 117             <title>Graphic figures *.scg</title>
 118             <para>
 119                 Any graphic figure can be saved in its whole either with <literal>save()</literal>
 120                 through its identifier as a variable (as decribed hereabove), or with
 121                 <literal>xsave()</literal> or the <emphasis>File => Save</emphasis> figure's Menu,
 122                 that do the same. The preferred (but not mandatory) file extension is
 123                 <emphasis role="bold">.scg</emphasis> (for SCilab Graphics).
 124                 Then, <literal>load(..)</literal> or <literal>xload()</literal>
 125                 may be used to restore saved figures. When using <literal>save(..)</literal>,
 126                 several figures may be saved in the same file.
 127             </para>
 128             <para>
 129                 Each restored figure gets a new incremented #id, so usually not the original one.
 130             </para>
 131             <para>
 132                 Figures including some interactive (uicontrol) components are fully restored.
 133             </para>
 134         </refsect3>
 135         <refsect3>
 136             <title>lib files: libraries of functions in Scilab language</title>
 137             <para>
 138                 <literal>genlib(..)</literal> allows to compile a set of *.sci files and bundle
 139                 compiled binaries into a library described in a file always named
 140                 <literal>lib</literal>.
 141             </para>
 142             <para>
 143                 Then, <literal>load("/path/to/lib")</literal> allows to load the library in the
 144                 session. All its functions become available at the level where
 145                 <literal>load(..)</literal> is called.
 146             </para>
 147             <para>
 148                 When loading a library, <literal>load(..)</literal> silently creates a variable
 149                 representing it. Its name is registered in the lib file (that is XML formatted),
 150                 in the <literal>&lt;scilablib name="..."></literal> tag.
 151             </para>
 152             <para>
 153                 The library's name can be retrieved with
 154                 <literal>xmlGetValues("/scilablib", "name", "/path/to/lib")</literal>,
 155                 where "/path/to/lib" is replaced with the actual pathname of the lib file.
 156             </para>
 157         </refsect3>
 158         <warning>
 159             <para>
 160                 Scilab 6 can load data saved with Scilab>=5.4 in SOD format.
 161             </para>
 162             <para>
 163                 Data saved in the old Scilab&lt;5.4 format
 164                 <ulink url="http://bugzilla.scilab.org/14840">can't be directly loaded</ulink>:
 165                 Scilab 5.5.2 must be used as an intermediate to load them from the old format
 166                 and save them to the SOD format, which can be loaded in Scilab 6.
 167             </para>
 168         </warning>
 169     </refsection>
 170     <refsection>
 171         <title>Examples</title>
 172         <para>
 173             With arrays of regular data types:
 174         </para>
 175         <programlisting role="example"><![CDATA[
 176 d = rand(3,4,2);
 177 b = d < 0.5;
 178 i = int8((d-0.5)*100);
 179 t = string(i);
 180 p = (1-%z).^0:2;
 181 r = p./%z;
 182 s = sprand(3,5, 0.3);
 183 save("TMPDIR/val.dat", "b", "i", "d", "t", "s", "p", "r");
 184 clear d i b t s p r
 185 load("TMPDIR/val.dat");
 186 d, i, b, t, s, p, r
 187      ]]></programlisting>
 188         <para>
 189             Overwriting permanent variables is forbidden when loading:
 190         </para>
 191         <programlisting role="example"><![CDATA[
 192 save("TMPDIR/val.dat", "%e");
 193 load("TMPDIR/val.dat");
 194      ]]></programlisting>
 195         <screen><![CDATA[
 196 --> load("TMPDIR/val.dat");
 197 Redefining permanent variable.
 198 ]]></screen>
 199         <para>
 200             With graphic handles:
 201         </para>
 202         <programlisting role="example"><![CDATA[
 203 clf reset
 204 subplot(1,3,1), plot2d(), a1 = gca();
 205 subplot(1,3,2), hist3d()
 206 subplot(1,3,3), plot3d(), a3 = gca();
 207 save(TMPDIR+"/test.scg", "a3", "a1")
 208 clf reset
 209 load(TMPDIR+"/test.scg")
 210      ]]></programlisting>
 211         <screen><![CDATA[
 212 --> load("TMPDIR/val.dat");
 213 Redefining permanent variable.
 214 ]]></screen>
 215         <para>
 216             Loading a library of functions compiled in Scilab language:
 217         </para>
 218         <programlisting role="example"><![CDATA[
 219 path = "SCI/modules/scicos_blocks/macros/Threshold/lib";
 220 load(path)
 221 xmlGetValues("/scilablib", "name", path)
 222 Thresholdlib
 223      ]]></programlisting>
 224         <screen><![CDATA[
 225 --> xmlGetValues("/scilablib", "name", path)
 226  ans  =
 227  Thresholdlib
 228
 229  --> Thresholdlib
 230  Thresholdlib  =
 231 Functions files location : SCI\modules\scicos_blocks\macros\Threshold\.
 232 GENERAL_f  ZCROSS_f  NEGTOPOS_f  POSTONEG_f
 233 ]]></screen>
 234     </refsection>
 235     <para>
 236         <literal>xcos()</literal> must be used to load a simulation diagram:
 237     </para>
 238     <programlisting role="example"><![CDATA[
 239 path = "SCI/modules/xcos/examples/derivative.zcos";
 240 load(path)  // => error
 241 xcos(path)
 242      ]]></programlisting>
 243     <refsection role="see also">
 244         <title>See also</title>
 245         <simplelist type="inline">
 246             <member>
 247                 <link linkend="listvarinfile">listvarinfile</link>
 248             </member>
 249             <member>
 250                 <link linkend="loadGui">loadGui</link>
 251             </member>
 252             <member>
 253                 <link linkend="xload">xload</link>
 254             </member>
 255             <member>
 256                 <link linkend="lib">lib</link>
 257             </member>
 258             <member>
 259                 <link linkend="xcos">xcos</link>
 260             </member>
 261             <member>
 262                 <link linkend="loadmatfile">loadmatfile</link>
 263             </member>
 264             <member>
 265                 <link linkend="save">save</link>
 266             </member>
 267             <member>
 268                 <link linkend="save_format">save_format</link>
 269             </member>
 270             <member>
 271                 <link linkend="exec">exec</link>
 272             </member>
 273         </simplelist>
 274     </refsection>
 275     <refsection>
 276         <title>History</title>
 277         <revhistory>
 278             <revision>
 279                 <revnumber>5.0.0</revnumber>
 280                 <revremark>
 281                     All <link linkend="uimenu">uimenu</link> or
 282                     <link linkend="uicontrol">uicontrol</link> handles are also loaded by this
 283                     function.
 284                 </revremark>
 285             </revision>
 286             <revision>
 287                 <revnumber>5.4.0</revnumber>
 288                 <revremark>
 289                     <itemizedlist>
 290                         <listitem>
 291                             The load function is able to handle both Scilab 5 and SOD (Scilab 6
 292                             format) by default.
 293                         </listitem>
 294                         <listitem>
 295                             The Scilab 5.X format is deprecated.
 296                         </listitem>
 297                         <listitem>
 298                             Using load with a file descriptor as first input argument is deprecated.
 299                         </listitem>
 300                     </itemizedlist>
 301                 </revremark>
 302             </revision>
 303             <revision>
 304                 <revnumber>6.0</revnumber>
 305                 <revremark>
 306                     <itemizedlist>
 307                         <listitem>
 308                             load() is no longer able to handle data files saved with the Scilab
 309                             &lt; 5.4 format.
 310                         </listitem>
 311                         <listitem>
 312                             The syntaxes load(fid) and load(fid, x1,..) with a file id are no
 313                             longer supported.
 314                         </listitem>
 315                     </itemizedlist>
 316                 </revremark>
 317             </revision>
 318         </revhistory>
 319     </refsection>
 320 </refentry>