summaryrefslogtreecommitdiff
path: root/modules/io/help/en_US/save.xml
blob: 983e94081fd39c23ceb9d1ecec99e00b1c573bf3 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
 * Copyright (C) XXXX-2008 - INRIA
 * 
 * This file must be used under the terms of the CeCILL.
 * This source file is licensed as described in the file COPYING, which
 * you should have received as part of this distribution.  The terms
 * are also available at    
 * http://www.cecill.info/licences/Licence_CeCILL_V2.1-en.txt
 *
 -->
<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns4="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="save" xml:lang="en">
    <refnamediv>
        <refname>save</refname>
        <refpurpose>Save a variable or a serie of variables in a binary
            file
        </refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Calling Sequence</title>
        <synopsis>save(filename [,x1,x2,...,xn])
            save(fd [,x1,x2,...,xn])
        </synopsis>
    </refsynopsisdiv>
    <refsection>
        <title>Arguments</title>
        <variablelist>
            <varlistentry>
                <term>filename</term>
                <listitem>
                    <para>Character string containing the path of the file</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>fd</term>
                <listitem>
                    <para>A file descriptor given by a call to mopen</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>xi</term>
                <listitem>
                    <para>Arbitrary Scilab variable(s)</para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Description</title>
        <para>
            The <literal>save</literal> command can be used to save Scilab
            current variables in a binary file. If a variable is a graphic handle, the
            <literal>save</literal> function saves all the corresponding <link linkend="graphics_entities">graphics_entities</link> definition.
        </para>
        <para>The file can be given either by its paths or by its descriptor
            previously given by <literal>mopen</literal>.
        </para>
        <para>
            <literal>save(filename)</literal> saves all current variables in the
            file defined by <literal>filename</literal>.
        </para>
        <para>
            <literal>save(fd)</literal> saves all current variables in the file
            defined by the descriptor <literal>fd</literal>. <emphasis role="bold">This prototype is obsolete and will be removed in Scilab 6.</emphasis>
        </para>
        <para>
            <literal>save(filename,x,y)</literal> or <literal>save(fd,x,y)</literal> (with <literal>x</literal> and <literal>y</literal> variables of your environment) saves only named variables <literal>x</literal> and <literal>y</literal>. <literal>save(fd,x,y)</literal> <emphasis role="bold"> is obsolete and will be removed in Scilab 6.</emphasis>
        </para>
        <para>
            <literal>save(filename,"x","y")</literal> (with <literal>"x"</literal> and <literal>"y"</literal> names of variables of your environment) will save your data using the SOD (Scilab Open Data) format (based on HDF5), format that will be readable by Scilab 6 family.
        </para>
        <para>
            <literal>save(filename,"-append","w", "z")</literal> (with <literal>"w"</literal> and <literal>"z"</literal> names of variables of your environment) will append your data in the existing SOD file called <literal>filename</literal>.
        </para>
        <para>
            The change of format between the family 5 and 6 of Scilab has been decided because the 5 format is undocumented, not specified and hard to read. SOD (Scilab 6 default format) is fully documented and easy to read through HDF5 libraries or applications.
        </para>
        <para>
            Saved variables can be reloaded by the 
            <literal>
                <link linkend="load">load</link>
            </literal>
            command.
        </para>
        <para>Note that the written file is portable to other operating systems and architectures (little and big endian).
        </para>
    </refsection>
    <refsection>
        <title>Examples</title>
        <programlisting role="example"><![CDATA[ 
// Binary format readable up to Scilab 5 family
a=eye(2,2);b=ones(a);
save('val.dat',a,b);
clear a
clear b
load('val.dat','a','b');

// sequential save into a file
fd=mopen('TMPDIR/foo','wb')
for k=1:4, x=k^2;save(fd,x,k),end
mclose(fd)
fd=mopen('TMPDIR/foo','rb')
for i=1:4, load(fd,'x','k');x,k,end
mclose(fd)

// appending variables to an old save file
fd=mopen('TMPDIR/foo','rb+')
mseek(0,fd,'end') 
lst=list(1,2,3)
save(fd,lst)
mclose(fd)

// Binary format readable by Scilab 5.4.X and Scilab 6 family
a=eye(2,2);b=ones(a);
save("val.sod", "a", "b");
clear a
clear b
load("val.sod", "a", "b");
 ]]></programlisting>
    </refsection>
    <refsection role="see also">
        <title>See Also</title>
        <simplelist type="inline">
            <member>
                <link linkend="load">load</link>
            </member>
            <member>
                <link linkend="write">write</link>
            </member>
            <member>
                <link linkend="save_format">save_format</link>
            </member>
            <member>
                <link linkend="mopen">mopen</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 saved by this function.
                </revremark>
            </revision>
            <revision>
                <revnumber>5.4.0</revnumber>
                <revdescription>
                    <itemizedlist>
                        <listitem>When called with variables names (character string) as input, variables are saved in SOD format, format that will be readable by Scilab 6 family.</listitem>
                        <listitem>The Scilab 5.X format is deprecated and will be removed with Scilab 6.</listitem>
                        <listitem>Using save with a file descriptor as first input argument is deprecated and will be removed with Scilab 6.</listitem>
                    </itemizedlist>
                </revdescription>
            </revision>
        </revhistory>
    </refsection>
</refentry>