<?xml version="1.0" encoding="UTF-8"?>
<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:html="http://www.w3.org/1999/xhtml" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:id="LhsVar">
    <refnamediv>
        <refname>LhsVar (deprecated)</refname>
        <refpurpose>
            a C gateway function which specifies which parameters created
            inside the C gateway will be returned as an output argument into
            Scilab.
            <emphasis role="bold">This function is obsolete.</emphasis>
        </refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <synopsis>LhsVar(RankPos) = RankVar;</synopsis>
    </refsynopsisdiv>
    <refsection>
        <title>Arguments</title>
        <variablelist>
            <varlistentry>
                <term>RankPos</term>
                <listitem>
                    <para>as integer providing the rank of the output argument</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>RankVar</term>
                <listitem>
                    <para>
                        the rank of the parameter created inside the C gateway to be
                        returned as an Scilab output argument
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Description</title>
        <para>
            A C gateway function which specifies which variables created inside
            the C interface will be returned as an output argument into Scilab.
        </para>
        <para>
            WARNING: This API is deprecated from Scilab 5.2.0 and is going to be removed with Scilab 6.0. Please use <link linkend="api_scilab">API Scilab</link> (the new Scilab API).
        </para>
    </refsection>
    <refsection>
        <title>Examples</title>
        <para>This example takes a matrix of doubles as input and returns:</para>
        <itemizedlist>
            <listitem>
                <para>the number of lines (first output argument)</para>
            </listitem>
            <listitem>
                <para>the number of rows (second output argument)</para>
            </listitem>
        </itemizedlist>
        <para>
            We create an intermediate Scilab parameter which will handle an
            integer but will neither be used nor returned as an output
            argument.
        </para>
        <para>TODO: insert an example in the Scilab language</para>
        <programlisting role="example"><![CDATA[

#include "api_scilab.h"
int sci_mysizedouble(char * fname, unsigned long fname_len)
{
    int         m_in_row;
    int         n_in_col;
    int         *piAddr = NULL;
    double      *pdblData = NULL;
    SciErr      sciErr;

    sciErr = getVarAddressFromPosition(pvApiCtx, 1, &piAddr);
    if(sciErr.iErr)
    {
        printError(&sciErr, 0);
        return 0;
    }

    /* get dimensions */
	sciErr = getMatrixOfDouble(pvApiCtx, piAddr, &m_in_row, &n_in_col, &pdblData);
	if(sciErr.iErr)
	{
		printError(&sciErr, 0);
		return 0;
	}

    sciErr = createMatrixOfInteger32(pvApiCtx, 2, 1, 1, &m_in_row); // the out_lines_pos parameter handles the number of lines of the matrix sent as argument
    sciErr = createMatrixOfInteger32(pvApiCtx, 3, 1, 1, &m_in_row); // store a mere value, but will neither be used nor returned to Scilab
    sciErr = createMatrixOfInteger32(pvApiCtx, 4, 1, 1, &n_in_col); // store a mere value, but will neither be used nor returned to Scilab

    LhsVar(1) = 2; // We set the parameter 2 as an output argument
    LhsVar(2) = 4; // We set the parameter 4 as an output argument
    PutLhsVar();
    return 0;
}
 ]]></programlisting>
    </refsection>
    <refsection role="see also">
        <title>See also</title>
        <simplelist type="inline">
            <member>
                <link linkend="AssignOutputVariable">AssignOutputVariable</link>
            </member>
        </simplelist>
    </refsection>
</refentry>
