5883a2404cad88075e061754a5959b22ed974452
[scilab.git] / scilab / modules / core / help / en_US / 2_control_flow / pause.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="pause">
3     <refnamediv>
4         <refname>pause</refname>
5         <refpurpose>pause mode, invoke keyboard</refpurpose>
6     </refnamediv>
7     <refsynopsisdiv>
8         <title>Syntax</title>
9         <synopsis>
10             pause
11         </synopsis>
12     </refsynopsisdiv>
13     <refsection>
14         <title>Description</title>
15         <para>
16             Switch to the <code>pause</code> mode;
17             inserted in the code of a function, <code>pause</code> interrupts the execution
18             of the function: one receives a prompt symbol which indicates
19             the level of the <code>pause</code> (e.g. <literal>-1-&gt;</literal>). The user is
20             then in a new workspace in which all the lower-level variables
21             (and in particular all the variable of the function) are available.
22             To return to the calling workspace enter <code>return</code>.
23         </para>
24         <para>
25             In this mode, <literal>[...]=return(...) </literal>
26             returns the variables of the argument <literal>(...)</literal> to the calling workspace with
27             names in the output <literal>[...]</literal>. Otherwise, the lower-level variables
28             are protected and cannot be modified.
29         </para>
30         <para>
31             The <literal>pause</literal> is extremely useful for debugging purposes.
32         </para>
33         <para>
34             This mode is killed by the command <code>abort</code>.
35         </para>
36     </refsection>
37     <refsection>
38         <title>Examples</title>
39         <programlisting role="example"><![CDATA[
40     function c=foo(b)
41     a=42+b
42     disp("Thanks to the pause, you can investigate if ''a'' has the right value");
43     disp("Value can be changed too if needed.");
44     pause
45     c=a+2
46     endfunction
47
48     foo(2)
49  ]]></programlisting>
50     </refsection>
51     <refsection role="see also">
52         <title>See also</title>
53         <simplelist type="inline">
54             <member>
55                 <link linkend="halt">halt</link>
56             </member>
57             <member>
58                 <link linkend="return">return</link>
59             </member>
60             <member>
61                 <link linkend="abort">abort</link>
62             </member>
63             <member>
64                 <link linkend="quit">quit</link>
65             </member>
66             <member>
67                 <link linkend="whereami">whereami</link>
68             </member>
69             <member>
70                 <link linkend="where">where</link>
71             </member>
72             <member>
73                 <link linkend="sleep">sleep</link>
74             </member>
75         </simplelist>
76     </refsection>
77 </refentry>