<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( https://www.scilab.org/ ) - This file is part of Scilab
 * Copyright (C) XXXX-2008 - INRIA
 * Copyright (C) 2012 - 2016 - Scilab Enterprises
 * Copyright (C) 2018 - Samuel GOUGEON
 *
 * This file is hereby licensed under the terms of the GNU GPL v2.0,
 * pursuant to article 5.3.4 of the CeCILL v.2.1.
 * This file was originally licensed under the terms of the CeCILL v2.1,
 * and continues to be available under such terms.
 * For more information, see the COPYING file which you should have received
 * along with this program.
 *
 -->
<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
        xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns3="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="load" xml:lang="en">
    <refnamediv>
        <refname>load</refname>
        <refpurpose>
            Loads some archived variables, a saved graphic figure, a library of functions
        </refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <synopsis>
            load(filename)
            load(filename, x1,...,xn)
            load("path/myfigure.scg")
            load("libdir/lib")
        </synopsis>
    </refsynopsisdiv>
    <refsection>
        <title>Arguments</title>
        <variablelist>
            <varlistentry>
                <term>filename</term>
                <listitem>
                    <para>path and name of the single file where archived variables are stored.
                        Any prepended "SCI", "TMPDIR", "SCIHOME" or "home" word being a predefined
                        Scilab variable is expanded into its value.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>xi</term>
                <listitem>
                    <para>
                        name(s) -- given as strings -- of Scilab variable(s) to be recovered.
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Description</title>
        <refsect3>
            <title>Archived variables</title>
            <para>
                The <literal>load</literal> command can be used to reload in the Scilab session
                variables previously saved in a file with the
                <literal>
                    <link linkend="save">save</link>
                </literal>
                command.
            </para>
            <para>
                <literal>load(filename,'x','y')</literal> loads only variables <literal>x, y</literal>.
                <itemizedlist>
                    <listitem>
                        <para>
                            The list of variables stored in a file can be retrieved with the
                            <link linkend="listvarinfile">listvarinfile</link> function.
                        </para>
                    </listitem>
                    <listitem>
                        <para>
                            <literal>load()</literal> loads restores variables in the current scope
                            (not on the global one).
                        </para>
                    </listitem>
                    <listitem>
                        <para>
                            If a variable to be loaded is not in the file, an error is generated.
                        </para>
                    </listitem>
                    <listitem>
                        If a restored variable has the same name as an existing variable of
                        the current scope, the current variable is silently overwritten.
                    </listitem>
                    <listitem>
                        <para>
                            When a variable to be restored is a graphic handle/identifier, the
                            corresponding <link linkend="graphics_entities">graphic entity</link>
                            is drawn with the current graphic driver.
                        </para>
                    </listitem>
                    <listitem>
                        <para>
                            The SOD binary format used by Scilab 6 to save (and load) variables is
                            based on the HDF5 format. It is fully documented and easy to read
                            through HDF5 libraries or applications.
                        </para>
                    </listitem>
                    <listitem>
                        <para>
                            Data files written with Scilab from other operating systems and
                            architectures (little and big endian) are portable and accepted.
                        </para>
                    </listitem>
                </itemizedlist>
            </para>
        </refsect3>
        <refsect3>
            <title>Graphic figures *.scg</title>
            <para>
                Any graphic figure can be saved in its whole either with <literal>save()</literal>
                through its identifier as a variable (as described hereabove), or with
                <literal>xsave()</literal> or the <emphasis>File => Save</emphasis> figure's Menu,
                that do the same. The preferred (but not mandatory) file extension is
                <emphasis role="bold">.scg</emphasis> (for SCilab Graphics).
                Then, <literal>load(..)</literal> or <literal>xload()</literal>
                may be used to restore saved figures. When using <literal>save(..)</literal>,
                several figures may be saved in the same file.
            </para>
            <para>
                Each restored figure gets a new incremented #id, so usually not the original one.
            </para>
            <para>
                Figures including some interactive (uicontrol) components are fully restored.
            </para>
        </refsect3>
        <refsect3>
            <title>lib files: libraries of functions in Scilab language</title>
            <para>
                <literal>genlib(..)</literal> allows to compile a set of *.sci files and bundle
                compiled binaries into a library described in a file always named
                <literal>lib</literal>.
            </para>
            <para>
                Then, <literal>load("/path/to/lib")</literal> allows to load the library in the
                session. All its functions become available at the level where
                <literal>load(..)</literal> is called.
            </para>
            <para>
                When loading a library, <literal>load(..)</literal> silently creates a variable
                representing it. Its name is registered in the lib file (that is XML formatted),
                in the <literal>&lt;scilablib name="..."></literal> tag.
            </para>
            <para>
                The library's name can be retrieved with
                <literal>xmlGetValues("/scilablib", "name", "/path/to/lib")</literal>,
                where "/path/to/lib" is replaced with the actual pathname of the lib file.
            </para>
        </refsect3>
        <warning>
            <para>
                Scilab 6 can load data saved with Scilab>=5.4 in SOD format.
            </para>
            <para>
                Data saved in the old Scilab&lt;5.4 format
                <ulink url="https://gitlab.com/scilab/scilab/-/issues/14840">can't be directly loaded</ulink>:
                Scilab 5.5.2 must be used as an intermediate to load them from the old format
                and save them to the SOD format, which can be loaded in Scilab 6.
            </para>
        </warning>
    </refsection>
    <refsection>
        <title>Examples</title>
        <para>
            With arrays of regular data types:
        </para>
        <programlisting role="example"><![CDATA[
d = rand(3,4,2);
b = d < 0.5;
i = int8((d-0.5)*100);
t = string(i);
p = (1-%z).^0:2;
r = p./%z;
s = sprand(3,5, 0.3);
save("TMPDIR/val.dat", "b", "i", "d", "t", "s", "p", "r");
clear d i b t s p r
load("TMPDIR/val.dat");
d, i, b, t, s, p, r
     ]]></programlisting>
        <para>
            Overwriting permanent variables is forbidden when loading:
        </para>
        <programlisting role="example"><![CDATA[
save("TMPDIR/val.dat", "%e");
load("TMPDIR/val.dat");
     ]]></programlisting>
        <screen><![CDATA[
--> load("TMPDIR/val.dat");
Redefining permanent variable.
]]></screen>
        <para>
            With graphic handles:
        </para>
        <programlisting role="example"><![CDATA[
clf reset
subplot(1,3,1), plot2d(), a1 = gca();
subplot(1,3,2), bar3d()
subplot(1,3,3), plot3d(), a3 = gca();
save(TMPDIR+"/test.scg", "a3", "a1")
clf reset
load(TMPDIR+"/test.scg")
     ]]></programlisting>
        <screen><![CDATA[
--> load("TMPDIR/val.dat");
Redefining permanent variable.
]]></screen>
        <para>
            Loading a library of functions compiled in Scilab language:
        </para>
        <programlisting role="example"><![CDATA[
path = "SCI/modules/scicos_blocks/macros/Threshold/lib";
load(path)
xmlGetValues("/scilablib", "name", path)
Thresholdlib
     ]]></programlisting>
        <screen><![CDATA[
--> xmlGetValues("/scilablib", "name", path)
 ans  =
 Thresholdlib

 --> Thresholdlib
 Thresholdlib  =
Functions files location : SCI\modules\scicos_blocks\macros\Threshold\.
GENERAL_f  ZCROSS_f  NEGTOPOS_f  POSTONEG_f
]]></screen>
    </refsection>
    <para>
        <literal>xcos()</literal> must be used to load a simulation diagram:
    </para>
    <programlisting role="example"><![CDATA[
path = "SCI/modules/xcos/examples/derivative.zcos";
load(path)  // => error
xcos(path)
     ]]></programlisting>
    <refsection role="see also">
        <title>See also</title>
        <simplelist type="inline">
            <member>
                <link linkend="listvarinfile">listvarinfile</link>
            </member>
            <member>
                <link linkend="loadGui">loadGui</link>
            </member>
            <member>
                <link linkend="xload">xload</link>
            </member>
            <member>
                <link linkend="lib">lib</link>
            </member>
            <member>
                <link linkend="xcos">xcos</link>
            </member>
            <member>
                <link linkend="loadmatfile">loadmatfile</link>
            </member>
            <member>
                <link linkend="save">save</link>
            </member>
            <member>
                <link linkend="save_format">save_format</link>
            </member>
            <member>
                <link linkend="exec">exec</link>
            </member>
        </simplelist>
    </refsection>
    <refsection>
        <title>History</title>
        <revhistory>
            <revision>
                <revnumber>5.0.0</revnumber>
                <revremark>
                    All <link linkend="uimenu">uimenu</link> or
                    <link linkend="uicontrol">uicontrol</link> handles are also loaded by this
                    function.
                </revremark>
            </revision>
            <revision>
                <revnumber>5.4.0</revnumber>
                <revremark>
                    <itemizedlist>
                        <listitem>
                            The load function is able to handle both Scilab 5 and SOD (Scilab 6
                            format) by default.
                        </listitem>
                        <listitem>
                            The Scilab 5.X format is deprecated.
                        </listitem>
                        <listitem>
                            Using load with a file descriptor as first input argument is deprecated.
                        </listitem>
                    </itemizedlist>
                </revremark>
            </revision>
            <revision>
                <revnumber>6.0</revnumber>
                <revremark>
                    <itemizedlist>
                        <listitem>
                            load() is no longer able to handle data files saved with the Scilab
                            &lt; 5.4 format.
                        </listitem>
                        <listitem>
                            The syntaxes load(fid) and load(fid, x1,..) with a file id are no
                            longer supported.
                        </listitem>
                    </itemizedlist>
                </revremark>
            </revision>
        </revhistory>
    </refsection>
</refentry>
