* Bug #12882 fixed - Some help pages were not clear.
[scilab.git] / scilab / modules / core / help / en_US / variables / predef.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:lang="en" xml:id="predef">
3     <refnamediv>
4         <refname>predef</refname>
5         <refpurpose>variable protection</refpurpose>
6     </refnamediv>
7     <refsynopsisdiv>
8         <title>Calling Sequence</title>
9         <synopsis>n = predef()
10             oldnew = predef(n)
11             oldnew = predef('all')
12             oldnew = predef('clear')
13             variables_name = predef('names')
14         </synopsis>
15     </refsynopsisdiv>
16     <refsection>
17         <title>Description</title>
18         <para>
19             Utility function used for defining "oldest" variables as "protected".
20             Protected variables cannot be killed. They are not saved 
21             by the <function>save</function> command. The "oldest" are those appearing last in
22             the <code>who('get')</code>.
23         </para>
24         <para>
25             <code>predef()</code> gets the number of protected variables.
26         </para>
27         <para>
28             <code>predef('a[ll]')</code> sets all the variables protected, it also return
29             the old and new value of protected variables number.
30         </para>
31         <para>
32             <code>predef('c[lear]')</code> unprotect all but the last 7 variables, it also return
33             the old and new value of protected variables number.
34         </para>
35         <para>
36             <code>predef(n)</code> sets the <code>max(n,7)</code> last defined variables as protected, it also return
37             the old and new value of protected variables number.
38         </para>
39         <para>
40             <code>predef('names')</code> returns a vector of strings with the name of protected variables.
41         </para>
42         <para>
43             <code>predef('clear')</code> removes the predefined variables from the list.
44         </para>
45     </refsection>
46     <refsection>
47         <title>Remarks</title>
48         <para>
49             Variable <literal>ans</literal> created automatically when expressions are not assigned is never protected by <code>predef('all')</code>.
50         </para>
51         <para>
52             A number of protected variables are set in the start-up file <literal>SCI/etc/scilab.start</literal>.
53             User may in particular set its own predefined variables in user's startup files 
54             <literal>SCIHOME/.scilab</literal> or <literal>SCIHOME/scilab.ini</literal>
55         </para>
56         <para>
57             <important>
58                 Note that it is not possible to protect a new defined variable by using <code>predef(1)</code>. 
59                 This means that to protect a variable, Scilab needs to protect all the variables that have been defined before it.
60                 This limitation may disappear with Scilab 6, which will not be stack-designed.
61             </important>
62         </para>
63     </refsection>
64     <refsection>
65         <title>Examples</title>
66         <programlisting role="example"><![CDATA[ 
67 errcatch(13, "continue") // Make sure we continue even when "clear a" will fail
68 a = 1;
69 predef("all");
70 clear a // fails
71 predef("clear")
72 clear a // works
73  ]]></programlisting>
74     </refsection>
75     <refsection role="see also">
76         <title>See Also</title>
77         <simplelist type="inline">
78             <member>
79                 <link linkend="clear">clear</link>
80             </member>
81             <member>
82                 <link linkend="save">save</link>
83             </member>
84             <member>
85                 <link linkend="ans">ans</link>
86             </member>
87             <member>
88                 <link linkend="startup">startup</link>
89             </member>
90         </simplelist>
91     </refsection>
92 </refentry>