6d01c69564fcdde63338b80bb9011a31efd780b7
[scilab.git] / scilab / modules / core / help / en_US / debugging / where.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="where">
3     <refnamediv>
4         <refname>where</refname>
5         <refpurpose>get current instruction calling tree</refpurpose>
6     </refnamediv>
7     <refsynopsisdiv>
8         <title>Syntax</title>
9         <synopsis>[linenum, callername] = where()</synopsis>
10     </refsynopsisdiv>
11     <refsection>
12         <title>Arguments</title>
13         <variablelist>
14             <varlistentry>
15                 <term>linenum</term>
16                 <listitem>
17                     <para>a column vector of integers</para>
18                 </listitem>
19             </varlistentry>
20             <varlistentry>
21                 <term>callername</term>
22                 <listitem>
23                     <para>a column vector of strings</para>
24                 </listitem>
25             </varlistentry>
26         </variablelist>
27     </refsection>
28     <refsection>
29         <title>Description</title>
30         <para>
31             <code>[linenum, callername] = where()</code> returns <varname>linenum</varname> and
32             <varname>callername</varname> such as current instruction has been
33             called by the <code>linenum(1)</code> line of function
34             <code>callername(1)</code>, <code>callername(1)</code> has been called by the
35             <code>linenum(2)</code> line of function <code>callername(2)</code>
36             and so on.
37         </para>
38         <para>
39             <code>callername(i)</code> is in general the name of a function but it may also be
40             <literal>"exec"</literal> or <literal>"execstr"</literal> if instruction lies in an
41             exec file or an execstr instruction.
42         </para>
43     </refsection>
44     <refsection>
45         <title>Examples</title>
46         <programlisting role="example"><![CDATA[
47 function foo()
48          [a,b] = where()
49          disp("Line:")
50          disp(a);
51          disp("Function:")
52          disp(b);
53 endfunction
54
55 function bar()
56          function beer()
57                   foo()
58          endfunction
59          beer()
60 endfunction
61
62 bar()
63
64  ]]></programlisting>
65     </refsection>
66
67     <refsection role="see also">
68         <title>See also</title>
69         <simplelist type="inline">
70             <member>
71                 <link linkend="whereami">whereami</link>
72             </member>
73             <member>
74                 <link linkend="pause">pause</link>
75             </member>
76         </simplelist>
77     </refsection>
78 </refentry>