<?xml version="1.0" encoding="UTF-8"?>
<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="exec">
    <refnamediv>
        <refname>exec</refname>
        <refpurpose>script file execution</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <synopsis>
            exec(path [,mode])
            exec(fun [,mode])
            ierr = exec(path, 'errcatch' [,mode])
            ierr = exec(fun, 'errcatch' [,mode])
            [ierr, errormsg] = exec(..., 'errcatch' [,mode])
            [ierr, errormsg, callstack] = exec(..., 'errcatch' [,mode])
        </synopsis>
    </refsynopsisdiv>
    <refsection>
        <title>Arguments</title>
        <variablelist>
            <varlistentry>
                <term>path</term>
                <listitem>
                    <para>a string, the path of the script file.</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>mode</term>
                <listitem>
                    <para>an integer scalar, the execution mode (see below).</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>fun</term>
                <listitem>
                    <para>a Scilab function.</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>ierr</term>
                <listitem>
                    <para>an integer, 0 or error number.</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>errormsg</term>
                <listitem>
                    <para>
                        error message in case of error and with <literal>'errcatch'</literal> flag.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>callstack</term>
                <listitem>
                    <para>
                        callstack in case of error and with <literal>'errcatch'</literal> flag.
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Description</title>
        <para>
            <code>exec(path [,mode])</code> executes sequentially the Scilab instructions
            contained in the file given by <varname>path</varname>  with an optional
            execution mode <varname>mode</varname>.
        </para>
        <para>
            The different cases for <varname>mode</varname> are :
        </para>
        <variablelist>
            <varlistentry>
                <term>0</term>
                <listitem>
                    <para>
                        the default value.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>-1</term>
                <listitem>
                    <para>
                        nothing is printed.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>1</term>
                <listitem>
                    <para>
                        echo of each command line.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>2</term>
                <listitem>
                    <para>
                        prompt <literal>--&gt;</literal> is printed.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>3</term>
                <listitem>
                    <para>
                        echoes + prompts.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>4</term>
                <listitem>
                    <para>
                        stops before each prompt. Execution resumes after a carriage return.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>7</term>
                <listitem>
                    <para>
                        stops + prompts + echoes : useful mode for demos.
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
        <para>
            <code>exec(fun [,mode])</code> executes function  <varname>fun</varname> as a script: no
            input nor output argument nor specific variable environment. This method for script evaluation allows to store scripts as
            function in libraries.
        </para>
        <para>
            If an error is encountered while executing, if <literal>'errcatch'</literal> flag is
            present <function>exec</function> issues no error message, aborts execution of the
            instructions and resumes with <varname>ierr</varname> equal to the error
            number. If <literal>'errcatch'</literal> flag is not present, standard error handling
            works.
        </para>
    </refsection>
    <refsection>
        <title>Remarks</title>
        <para>
            <function>exec</function> files may now be used to define functions using the inline function definition syntax (see <link linkend="function">function</link>).
        </para>
        <para>
            <function>exec</function> supports files encoded as ANSI/ASCII and UTF-8.
        </para>
        <para>The length of each line in a file is limited to 4096 characters.</para>
    </refsection>
    <refsection>
        <title>Examples</title>
        <programlisting role="example">
    <![CDATA[
// create a script file
mputl('a=1;b=2',TMPDIR+'/myscript')

// execute it
exec(TMPDIR+'/myscript')
whos -name "a "

// create a function
deff('y=foo(x)','a=x+1;y=a^2')
clear a b
// call the function
foo(1)
// a is a variable created in the environment of the function foo
//    it is destroyed when foo returns
whos -name "a "

x=1 //create x to make it known by the script foo
exec(foo)

// a and y are created in the current environment
whos -name "a "
whos -name "y "

//errormsg
mputl('acosd(''d'');', TMPDIR+'/myscript')
[_ b] = exec(TMPDIR+'/myscript', 'errcatch')
]]></programlisting>
    </refsection>
    <refsection role="see also">
        <title>See also</title>
        <simplelist type="inline">
            <member>
                <link linkend="execstr">execstr</link>
            </member>
            <member>
                <link linkend="evstr">evstr</link>
            </member>
            <member>
                <link linkend="mode">mode</link>
            </member>
            <member>
                <link linkend="chdir">chdir</link>
            </member>
            <member>
                <link linkend="pwd">pwd</link>
            </member>
        </simplelist>
    </refsection>
</refentry>
