Add also the examples in core help pages in the russian help page (port of modificati...
[scilab.git] / scilab / modules / core / help / en_US / error_handling / errcatch.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="errcatch">
3     <refnamediv>
4         <refname>errcatch</refname>
5         <refpurpose>error trapping</refpurpose>
6     </refnamediv>
7     <refsynopsisdiv>
8         <title>Calling Sequence</title>
9         <synopsis>errcatch(n [,'action'] [,'option'])
10             errcatch()
11         </synopsis>
12     </refsynopsisdiv>
13     <refsection>
14         <title>Arguments</title>
15         <variablelist>
16             <varlistentry>
17                 <term>n</term>
18                 <listitem>
19                     <para>integer</para>
20                 </listitem>
21             </varlistentry>
22             <varlistentry>
23                 <term>action, option</term>
24                 <listitem>
25                     <para>strings</para>
26                 </listitem>
27             </varlistentry>
28         </variablelist>
29     </refsection>
30     <refsection>
31         <title>Description</title>
32         <para>
33             <function>errcatch</function> gives an "action" (error-handler)  to be
34             performed when an error of type <varname>n</varname> occurs.
35         </para>
36         <para>
37             <varname>n</varname> has the following meanings:
38         </para>
39         <para>
40             if <varname>n</varname><literal>&gt;0</literal>, <varname>n</varname> is the error number to trap;
41         </para>
42         <para>
43             if <varname>n</varname><literal>&lt;0</literal> all errors are to be trapped.
44         </para>
45         <para>
46             <varname>action</varname> is one of the following character strings:
47         </para>
48         <variablelist>
49             <varlistentry>
50                 <term>"pause"</term>
51                 <listitem>
52                     <para>a pause is executed when trapping the error. This option is
53                         useful for debugging purposes. Use <code>whereami()</code> to get information
54                         on the current context.
55                     </para>
56                 </listitem>
57             </varlistentry>
58             <varlistentry>
59                 <term>"continue"</term>
60                 <listitem>
61                     <para>next instruction in the function or exec files is executed,
62                         current instruction is ignored. It is possible to check if an error has occurred
63                         using the <link linkend="iserror">iserror</link> function. Do not forget to clear the  
64                         error using the <link linkend="errclear">errclear</link> function as soon as possible.  
65                         This option is useful for error recovery. In many cases, usage of 
66                         <literal> errcatch(n,"continue",..)</literal> can be replaced by the use of
67                         <link linkend="execstr">execstr</link> function or <link linkend="try">try</link> 
68                         control structure.
69                     </para>
70                 </listitem>
71             </varlistentry>
72             <varlistentry>
73                 <term>"kill"</term>
74                 <listitem>
75                     <para>default mode, all intermediate functions are killed, Scilab goes
76                         back to the level 0 prompt.
77                     </para>
78                 </listitem>
79             </varlistentry>
80             <varlistentry>
81                 <term>"stop"</term>
82                 <listitem>
83                     <para>interrupts the current Scilab session (useful when Scilab is called from an external program).</para>
84                 </listitem>
85             </varlistentry>
86         </variablelist>
87         <para>
88             <varname>option</varname> is the character string <literal>'nomessage'</literal> for killing
89             error message.
90         </para>
91         <para>
92             To set back default mode, enter <code>errcatch(-1,"kill")</code> or similarly
93             <code>errcatch(-1)</code>. <code>errcatch()</code> is an obsolete equivalent of <code>errcatch(-1)</code>.
94         </para>
95         <para/>
96         <para>
97             The <function>errcatch</function> actions apply to the current evaluation
98             context (<literal>function</literal>, <literal>exec</literal>, <literal>pause</literal>) and all the sub-levels. A  second <function>errcatch</function> call in a sub-level hides the initial one for this sub-level. If a second <function>errcatch</function> call is made at the
99             same level, the effect of the first one is removed.
100         </para>
101         <para>
102             When called in the context of  a Scilab function or exec the <function>errcatch</function> is automatically reset  when the function returns.
103         </para>
104     </refsection>
105     <refsection>
106         <title>Examples</title>
107         <programlisting role="example"><![CDATA[ 
108 errcatch(144,"continue")
109 2/"foo"
110 disp(a) // Without the errcatch, this line would not be executed
111
112 errcatch(-1,"kill") // Come back in the normal mode
113 errcatch(144,"pause")
114 2/"foo" // Enter in "pause" mode
115
116 errcatch(27,'continue','nomessage')
117 b=2/0 // No error message but b will not exist
118  ]]></programlisting>
119     </refsection>
120     <refsection role="see also">
121         <title>See Also</title>
122         <simplelist type="inline">
123             <member>
124                 <link linkend="try">try</link>
125             </member>
126             <member>
127                 <link linkend="errclear">errclear</link>
128             </member>
129             <member>
130                 <link linkend="iserror">iserror</link>
131             </member>
132             <member>
133                 <link linkend="whereami">whereami</link>
134             </member>
135             <member>
136                 <link linkend="execstr">execstr</link>
137             </member>
138             <member>
139                 <link linkend="exec">exec</link>
140             </member>
141             <member>
142                 <link linkend="pause">pause</link>
143             </member>
144         </simplelist>
145     </refsection>
146 </refentry>