1 <?xml version="1.0" encoding="UTF-8"?>
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
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.
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">
21 <refname>load</refname>
23 Loads some archived variables, a saved graphic figure, a library of functions
30 load(filename, x1,...,xn)
31 load("path/myfigure.scg")
36 <title>Arguments</title>
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.
51 name(s) -- given as strings -- of Scilab variable(s) to be recovered.
58 <title>Description</title>
60 <title>Archived variables</title>
62 The <literal>load</literal> command can be used to reload in the Scilab session
63 variables previously saved in a file with the
65 <link linkend="save">save</link>
70 <literal>load(filename,'x','y')</literal> loads only variables <literal>x, y</literal>.
74 The list of variables stored in a file can be retrieved with the
75 <link linkend="listvarinfile">listvarinfile</link> function.
80 <literal>load()</literal> loads restores variables in the current scope
81 (not on the global one).
86 If a variable to be loaded is not in the file, an error is generated.
90 If a restored variable has the same name as an existing variable of
91 the current scope, the current variable is silently overwritten.
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.
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.
109 Data files written with Scilab from other operating systems and
110 architectures (little and big endian) are portable and accepted.
117 <title>Graphic figures *.scg</title>
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.
129 Each restored figure gets a new incremented #id, so usually not the original one.
132 Figures including some interactive (uicontrol) components are fully restored.
136 <title>lib files: libraries of functions in Scilab language</title>
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>.
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.
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><scilablib name="..."></literal> tag.
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.
160 Scilab 6 can load data saved with Scilab>=5.4 in SOD format.
163 Data saved in the old Scilab<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.
171 <title>Examples</title>
173 With arrays of regular data types:
175 <programlisting role="example"><![CDATA[
178 i = int8((d-0.5)*100);
182 s = sprand(3,5, 0.3);
183 save("TMPDIR/val.dat", "b", "i", "d", "t", "s", "p", "r");
185 load("TMPDIR/val.dat");
189 Overwriting permanent variables is forbidden when loading:
191 <programlisting role="example"><![CDATA[
192 save("TMPDIR/val.dat", "%e");
193 load("TMPDIR/val.dat");
196 --> load("TMPDIR/val.dat");
197 Redefining permanent variable.
200 With graphic handles:
202 <programlisting role="example"><![CDATA[
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")
209 load(TMPDIR+"/test.scg")
212 --> load("TMPDIR/val.dat");
213 Redefining permanent variable.
216 Loading a library of functions compiled in Scilab language:
218 <programlisting role="example"><![CDATA[
219 path = "SCI/modules/scicos_blocks/macros/Threshold/lib";
221 xmlGetValues("/scilablib", "name", path)
225 --> xmlGetValues("/scilablib", "name", path)
231 Functions files location : SCI\modules\scicos_blocks\macros\Threshold\.
232 GENERAL_f ZCROSS_f NEGTOPOS_f POSTONEG_f
236 <literal>xcos()</literal> must be used to load a simulation diagram:
238 <programlisting role="example"><![CDATA[
239 path = "SCI/modules/xcos/examples/derivative.zcos";
240 load(path) // => error
243 <refsection role="see also">
244 <title>See also</title>
245 <simplelist type="inline">
247 <link linkend="listvarinfile">listvarinfile</link>
250 <link linkend="loadGui">loadGui</link>
253 <link linkend="xload">xload</link>
256 <link linkend="lib">lib</link>
259 <link linkend="xcos">xcos</link>
262 <link linkend="loadmatfile">loadmatfile</link>
265 <link linkend="save">save</link>
268 <link linkend="save_format">save_format</link>
271 <link linkend="exec">exec</link>
276 <title>History</title>
279 <revnumber>5.0.0</revnumber>
281 All <link linkend="uimenu">uimenu</link> or
282 <link linkend="uicontrol">uicontrol</link> handles are also loaded by this
287 <revnumber>5.4.0</revnumber>
291 The load function is able to handle both Scilab 5 and SOD (Scilab 6
295 The Scilab 5.X format is deprecated.
298 Using load with a file descriptor as first input argument is deprecated.
304 <revnumber>6.0</revnumber>
308 load() is no longer able to handle data files saved with the Scilab
312 The syntaxes load(fid) and load(fid, x1,..) with a file id are no