load Loads some archived variables, a saved graphic figure, a library of functions

## Syntax

                load(filename)
                load(filename, x1,...,xn)
                load("path/myfigure.scg")
                load("libdir/lib")

## Arguments

filename

  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.

xi

  name(s) -- given as strings -- of Scilab variable(s) to be recovered.

## Description

### Archived variables

The `load` command can be used to reload in the Scilab session variables previously saved in a file with the `save` command.

`load(filename,'x','y')` loads only variables `x, y`.

- The list of variables stored in a file can be retrieved with the listvarinfile function.

- `load()` loads restores variables in the current scope (not on the global one).

- If a variable to be loaded is not in the file, an error is generated.

- If a restored variable has the same name as an existing variable of the current scope, the current variable is silently overwritten.

- When a variable to be restored is a graphic handle/identifier, the corresponding graphic entity is drawn with the current graphic driver.

- 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.

- Data files written with Scilab from other operating systems and architectures (little and big endian) are portable and accepted.

### Graphic figures *.scg

Any graphic figure can be saved in its whole either with `save()` through its identifier as a variable (as described hereabove), or with `xsave()` or the File => Save figure's Menu, that do the same. The preferred (but not mandatory) file extension is .scg (for SCilab Graphics). Then, `load(..)` or `xload()` may be used to restore saved figures. When using `save(..)`, several figures may be saved in the same file.

Each restored figure gets a new incremented #id, so usually not the original one.

Figures including some interactive (uicontrol) components are fully restored.

### lib files: libraries of functions in Scilab language

`genlib(..)` allows to compile a set of *.sci files and bundle compiled binaries into a library described in a file always named `lib`.

Then, `load("/path/to/lib")` allows to load the library in the session. All its functions become available at the level where `load(..)` is called.

When loading a library, `load(..)` silently creates a variable representing it. Its name is registered in the lib file (that is XML formatted), in the `<scilablib name="...">` tag.

The library's name can be retrieved with `xmlGetValues("/scilablib", "name", "/path/to/lib")`, where "/path/to/lib" is replaced with the actual pathname of the lib file.

Scilab 6 can load data saved with Scilab>=5.4 in SOD format.

Data saved in the old Scilab<5.4 format can't be directly loaded: 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.

## Examples

With arrays of regular data types:

    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

Overwriting permanent variables is forbidden when loading:

    save("TMPDIR/val.dat", "%e");
    load("TMPDIR/val.dat");

    --> load("TMPDIR/val.dat");
    Redefining permanent variable.

With graphic handles:

    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")

    --> load("TMPDIR/val.dat");
    Redefining permanent variable.

Loading a library of functions compiled in Scilab language:

    path = "SCI/modules/scicos_blocks/macros/Threshold/lib";
    load(path)
    xmlGetValues("/scilablib", "name", path)
    Thresholdlib

    --> 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

`xcos()` must be used to load a simulation diagram:

    path = "SCI/modules/xcos/examples/derivative.zcos";
    load(path)  // => error
    xcos(path)

## See also

- listvarinfile
- loadGui
- xload
- lib
- xcos
- loadmatfile
- save
- save_format
- exec

## History

5.0.0 All uimenu or uicontrol handles are also loaded by this function.
5.4.0

- The load function is able to handle both Scilab 5 and SOD (Scilab 6 format) by default.
- The Scilab 5.X format is deprecated.
- Using load with a file descriptor as first input argument is deprecated.

6.0

- load() is no longer able to handle data files saved with the Scilab < 5.4 format.
- The syntaxes load(fid) and load(fid, x1,..) with a file id are no longer supported.