<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( http://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="StringManagement_callscilab" xml:lang="en">
    <refnamediv>
        <refname>String management</refname>
        <refpurpose>How to manage Scilab's String read and write process using
            call_scilab and api_scilab
        </refpurpose>
    </refnamediv>
    <refsection>
        <title>Description</title>
        <para>This help describes how strings and matrix of strings can be handle
            through the <link linkend="call_scilab">Call Scilab API</link> and <link linkend="api_scilab">api Scilab</link>.
        </para>
        <para>There are several functions which can be used to read / write from
            the memory of Scilab. These functions are described in dedicated
            pages.
        </para>
        <para>
            <note>
                Note: Access to variables is done through <link linkend="api_scilab">api Scilab</link> (named variable).
            </note>
        </para>
    </refsection>
    <refsection>
        <title>Examples</title>
        <programlisting role="example"><![CDATA[
// This example shows how to write a Scilab string in Scilab engine
// It is the equivalent to A="my Message"; in Scilab interpreter
// See: modules/call_scilab/examples/basicExamples/readwritestring.c

// StartScilab
int row = 1, col = 1; /* Size of the matrix */
/* Declare the string */
char **myMatrixOfString = (char**)malloc(sizeof(char*) * row * col);
myMatrixOfString[0]="my Message";
char variableName[] = "A";
SciErr sciErr;

/* Write it into Scilab's memory */
sciErr = createNamedMatrixOfString(pvApiCtx, variableName, row, col, myMatrixOfString);
if(sciErr.iErr)
{
	printError(&sciErr, 0);
}

/*
 * Prior to Scilab 5.2
 * C2F(cwritechain)(variableName, &sizeOfMyString  , myString, strlen(variableName), sizeOfMyString);
*/

printf("Display from Scilab of A:\n");
SendScilabJob("disp(A);"); /* Display A */
 ]]></programlisting>
        <programlisting role="example"><![CDATA[
/* Load the previously set variable A */
// See: modules/call_scilab/examples/basicExamples/readwritestring.c


char variableToBeRetrieved[]="A";
int iRows       = 0;
int iCols       = 0;
int i,j;
int* piAddr     = NULL;
int* piLen      = NULL;
char** pstData  = NULL;
SciErr sciErr;

//first call to retrieve dimensions
sciErr = readNamedMatrixOfString(pvApiCtx,variableToBeRetrieved,&iRows, &iCols, NULL, NULL);
if(sciErr.iErr)
{
	printError(&sciErr, 0);
}

piLen = (int*)malloc(sizeof(int) * iRows * iCols);
//second call to retrieve length of each string
sciErr = readNamedMatrixOfString(pvApiCtx,variableToBeRetrieved, &iRows, &iCols, piLen, NULL);
if(sciErr.iErr)
{
	printError(&sciErr, 0);
}

pstData = (char**)malloc(sizeof(char*) * iRows * iCols);
for(i = 0 ; i < iRows * iCols ; i++)
	{
		pstData[i] = (char*)malloc(sizeof(char) * (piLen[i] + 1));//+ 1 for null termination
	}
//third call to retrieve data
sciErr = readNamedMatrixOfString(pvApiCtx, variableToBeRetrieved, &iRows, &iCols, piLen, pstData);
if(sciErr.iErr)
{
	printError(&sciErr, 0);
}

printf("\n");
printf("Load and display of A:\n");
for(j = 0 ; j < iCols ; j++)
{
	for(i = 0 ; i < iRows ; i++)
	{
		/* Display the formatted matrix with same scilab index */
		printf("[%d,%d] = %s\n",j+1,i+1,pstData[j* iRows + i]);
	}
}

printf("\n");
free(piLen);
for(i = 0 ; i < iRows * iCols ; i++)
	{
		free(pstData[i]);
	}
free(pstData);

 ]]></programlisting>
    </refsection>
    <refsection role="see also">
        <title>See also</title>
        <simplelist type="inline">
            <member>
                <link linkend="call_scilab">Call_Scilab</link>
            </member>
            <member>
                <link linkend="api_scilab_legacy">api Scilab</link>
            </member>
            <member>
                <link linkend="SendScilabJob">SendScilabJob</link>
            </member>
            <member>
                <link linkend="StartScilab">StartScilab</link>
            </member>
            <member>
                <link linkend="BooleanManagement_callscilab">Call_Scilab: Boolean Management</link>
            </member>
            <member>
                <link linkend="DoubleManagement_callscilab">Call_Scilab: Double Management</link>
            </member>
            <member>
                <link linkend="boolean_reading_API">API_Scilab: Boolean Reading</link>
            </member>
            <member>
                <link linkend="boolean_writing_API">API_Scilab: Boolean Writing</link>
            </member>
            <member>
                <link linkend="Double_management_reading_API">API_Scilab: Double Reading</link>
            </member>
            <member>
                <link linkend="Double_management_writing_API">API_Scilab: Double Writing</link>
            </member>
            <member>
                <link linkend="ComplexManagement_callscilab">Complex Management</link>
            </member>
        </simplelist>
    </refsection>
</refentry>
