Xcos load: use a valid port type value
[scilab.git] / scilab / modules / core / help / en_US / 1_keywords / try.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:ns5="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="try" xml:lang="en">
3     <refnamediv>
4         <refname>try</refname>
5         <refpurpose>beginning of try block in try-catch control
6             instruction
7         </refpurpose>
8     </refnamediv>
9     <refnamediv xml:id="catch">
10         <refname>catch</refname>
11         <refpurpose>beginning of catch block in try-catch control
12             instruction
13         </refpurpose>
14     </refnamediv>
15     <refsynopsisdiv>
16         <title>Syntax</title>
17         <synopsis>
18             try
19             statements
20             catch
21             statements
22             end
23         </synopsis>
24     </refsynopsisdiv>
25     <refsection>
26         <title>Description</title>
27         <para>
28             The <literal>try</literal>-<literal>catch</literal> control
29             instruction can be used to manage codes that could possibly generate
30             errors.
31         </para>
32         <para>
33             When a <literal>try</literal>-<literal>catch</literal> control
34             instruction is executed, normally only the statements between the
35             <literal>try</literal> and <literal>catch</literal> keywords are executed.
36             However, if an error occurs during execution of any of these statements,
37             the error is recorded, the remaining statements up to the
38             <literal>catch</literal> keyword are skipped and the statements between
39             the <literal>catch</literal> and <literal>end</literal> keywords are
40             executed using the default error handling mode.
41         </para>
42         <para>
43             The recorded error can be retrieved using the <link linkend="lasterror">lasterror</link> function.
44         </para>
45         <para>
46             The <literal>catch</literal> statements as well as the
47             <literal>catch</literal> keyword can be omitted if no alternative
48             statements are given.
49         </para>
50         <para>
51             Note that one can also use the <link linkend="execstr">execstr</link> function with
52             <literal>'errcatch'</literal> argument for error handling. This can be
53             particularly useful for handling syntactical errors.
54         </para>
55         <para>
56             Note also that <literal>try-catch</literal> is more or less similar
57             to:
58         </para>
59         <programlisting role=""><![CDATA[ 
60 if execstr("<try instructions>","errcatch")<>0 then
61   <catch instructions>
62 end
63  ]]></programlisting>
64         <para>
65             It uses the same internal mechanism as "errcatch". It is the reason why
66             <emphasis>execstr(...,"errcatch")</emphasis> cannot be included in
67             <literal>try</literal>-<literal>catch</literal> control structures. This
68             context is detected and produces a specific error message (this error is
69             caught and stored like any other error if it is triggered in the
70             <literal>try</literal> block).
71         </para>
72         <para>
73             However, <literal>try</literal>-<literal>catch</literal> control
74             structures can be nested (see example 2 below).
75         </para>
76     </refsection>
77     <refsection>
78         <title>Examples</title>
79         <programlisting role="example"><![CDATA[ 
80 // example 1
81 file_path=TMPDIR+'/wrong'
82 try
83   u=mopen(file_path,'r')
84   x=mget(10,'c',u)
85 catch
86   disp(['file '+file_path+ ' cannot be read','using default values for x'])
87   x=1:10
88 end 
89  [error_message,error_number]=lasterror(%t)
90  ]]></programlisting>
91         <programlisting role="example"><![CDATA[ 
92 // example 2 (nested try/catch structures)
93 function nestedtry(a,b)
94 disp("START")
95 mprintf("\ta is %s\t\tb is %s\n",string(a),string(b))
96 try
97   disp("try 1")
98   try
99     disp("try 2")
100     z=a+1;  // err when string
101   catch
102     disp("catch 2")
103     t=b+1;  // err when string
104   end
105   disp("after try 2")
106 catch
107   disp("catch 1")
108 end
109 disp("after try 1 - THE END")
110 endfunction
111 nestedtry(1,1)
112 nestedtry("a string",1)
113 nestedtry(1,"a string")
114 nestedtry("a string","a string")
115  ]]></programlisting>
116     </refsection>
117     <refsection role="see also">
118         <title>See Also</title>
119         <simplelist type="inline">
120             <member>
121                 <link linkend="error">error</link>
122             </member>
123             <member>
124                 <link linkend="execstr">execstr</link>
125             </member>
126             <member>
127                 <link linkend="if">if</link>
128             </member>
129             <member>
130                 <link linkend="lasterror">lasterror</link>
131             </member>
132         </simplelist>
133     </refsection>
134 </refentry>