<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( https://www.scilab.org/ ) - This file is part of Scilab
 * Copyright (C) 2009  - DIGITEO - Sylvestre LEDRU
 *
 * Copyright (C) 2012 - 2016 - Scilab Enterprises
 *
 * This file is hereby licensed under the terms of the GNU GPL v2.0,
 * pursuant to article 5.3.4 of the CeCILL v.2.1.
 * This file was originally licensed under the terms of the CeCILL v2.1,
 * and continues to be available under such terms.
 * For more information, see the COPYING file which you should have received
 * along with this program.
 *
 -->
<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="call_scilab" xml:lang="en">
    <refnamediv>
        <refname>call_scilab</refname>
        <refpurpose>call_scilab is an interface which provides the ability to call
            Scilab engine from C/C++ code
        </refpurpose>
    </refnamediv>
    <refsection>
        <title>Description</title>
        <para>Scilab offers the possibility to be called from a native (C/C++)
            application.
        </para>
        <para>Thanks to this module, it is possible to call Scilab from C/C++ in
            order to interface Scilab's features from another code/application or to
            be able to interface Scilab's features from another language.
        </para>
        <para>Since Scilab 5.2.0, all Scilab datatype can be handle by call_scilab.
            This is done thanks to <link linkend="api_scilab">API_Scilab</link>
        </para>
        <para>This help describes the features of the call_scilab API.</para>
        <para>
            Note: The <link linkend="javasci">javasci</link> module is based
            on call_scilab.
        </para>
        <para>Note: old APIs (stackX.h) will not be available after Scilab 6.0 (included).</para>
    </refsection>
    <refsection>
        <title>Examples</title>
        <programlisting role="c"><![CDATA[
// A simple call_scilab example

#include <stdio.h> /* stderr */

#include "api_scilab.h" /* Provide functions to access to the memory of Scilab */
#include "call_scilab.h" /* Provide functions to call Scilab engine */

// Filename: simple_call_scilab.c

int main(void)
{
/****** INITIALIZATION **********/
#ifdef _MSC_VER
 if ( StartScilab(NULL,NULL,NULL) == FALSE )
#else
 if ( StartScilab(getenv("SCI"),NULL,NULL) == FALSE )
#endif
  {
   fprintf(stderr,"Error while calling StartScilab\n");
   return -1;
  }

/****** ACTUAL Scilab TASKS *******/

 SendScilabJob("myMatrix=['sample','for the help']");
 SendScilabJob("disp(myMatrix);"); // Will display !sample  for the help  !
 SendScilabJob("disp([2,3]+[-44,39]);"); // Will display   - 42.    42.

/****** TERMINATION **********/
 if ( TerminateScilab(NULL) == FALSE ) {
  fprintf(stderr,"Error while calling TerminateScilab\n");
  return -2;
 }
 return 0;
}
 ]]></programlisting>
    </refsection>
    <refsection>
        <title>History</title>
        <revhistory>
            <revision>
                <revnumber>5.4.0</revnumber>
                <revdescription>New methods added:
                    <itemizedlist>
                        <listitem>
                            <literal>CallScilab.h</literal> removed (was deprecated since Scilab 5.2.0). Replaced by <literal>call_scilab.h</literal>
                        </listitem>
                        <listitem>
                            Function <literal>int getLastErrorValue(void);</literal> added. Returns the last error code generated by Scilab
                        </listitem>
                        <listitem>
                            Function <literal>const char* getLastErrorMessageSingle();</literal> added. Returns the last error message generated by Scilab
                        </listitem>
                        <listitem>
                            Remove deprecated functions in call_scilab.h: <literal>C2F(readmat), C2F(creadmat), C2F(creadbmat), C2F(creadcmat), C2F(readchain), C2F(creadchain),  C2F(creadchains), GetLengthStringMatrixByName, C2F(matptr), C2F(cmatptr), C2F(cmatcptr),  C2F(cmatsptr), C2F(cmatbptr), getlengthchain</literal>

                        </listitem>
                    </itemizedlist>
                </revdescription>
            </revision>
        </revhistory>
    </refsection>
    <refsection role="see also">
        <title>See also</title>
        <simplelist type="inline">
            <member>
                <link linkend="api_scilab">API Scilab</link>
            </member>
            <member>
                <link linkend="compile_and_run_call_scilab">Compile and run with call_scilab</link>
            </member>
        </simplelist>
    </refsection>
</refentry>
