4fa4c18987e24e957b2580b575657d1e189a7898
[scilab.git] / scilab / modules / call_scilab / help / en_US / StringManagement.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!--
3  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
4  * Copyright (C) 2009  - DIGITEO - Sylvestre LEDRU
5  * 
6  * Copyright (C) 2012 - 2016 - Scilab Enterprises
7  *
8  * This file is hereby licensed under the terms of the GNU GPL v2.0,
9  * pursuant to article 5.3.4 of the CeCILL v.2.1.
10  * This file was originally licensed under the terms of the CeCILL v2.1,
11  * and continues to be available under such terms.
12  * For more information, see the COPYING file which you should have received
13  * along with this program.
14  *
15  -->
16 <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">
17     <refnamediv>
18         <refname>String management</refname>
19         <refpurpose>How to manage Scilab's String read and write process using
20             call_scilab and api_scilab
21         </refpurpose>
22     </refnamediv>
23     <refsection>
24         <title>Description</title>
25         <para>This help describes how strings and matrix of strings can be handle
26             through the <link linkend="call_scilab">Call Scilab API</link> and <link linkend="api_scilab">api Scilab</link>.
27         </para>
28         <para>There are several functions which can be used to read / write from
29             the memory of Scilab. These functions are described in dedicated
30             pages.
31         </para>
32         <para>
33             <note>
34                 Note: Access to variables is done through <link linkend="api_scilab">api Scilab</link> (named variable).
35             </note>
36         </para>
37     </refsection>
38     <refsection>
39         <title>Examples</title>
40         <programlisting role="example"><![CDATA[ 
41 // This example shows how to write a Scilab string in Scilab engine
42 // It is the equivalent to A="my Message"; in Scilab interpretor
43 // See: modules/call_scilab/examples/basicExamples/readwritestring.c
44
45 // StartScilab
46 int row = 1, col = 1; /* Size of the matrix */
47 /* Declare the string */
48 char **myMatrixOfString = (char**)malloc(sizeof(char*) * row * col);
49 myMatrixOfString[0]="my Message";
50 char variableName[] = "A";
51 SciErr sciErr;
52
53 /* Write it into Scilab's memory */
54 sciErr = createNamedMatrixOfString(pvApiCtx, variableName, row, col, myMatrixOfString);
55 if(sciErr.iErr)
56 {
57         printError(&sciErr, 0);
58 }
59
60 /*
61  * Prior to Scilab 5.2
62  * C2F(cwritechain)(variableName, &sizeOfMyString  , myString, strlen(variableName), sizeOfMyString); 
63 */
64
65 printf("Display from Scilab of A:\n");
66 SendScilabJob("disp(A);"); /* Display A */
67  ]]></programlisting>
68         <programlisting role="example"><![CDATA[ 
69 /* Load the previously set variable A */
70 // See: modules/call_scilab/examples/basicExamples/readwritestring.c
71
72
73 char variableToBeRetrieved[]="A";
74 int iRows       = 0;
75 int iCols       = 0;
76 int i,j;
77 int* piAddr     = NULL;
78 int* piLen      = NULL;
79 char** pstData  = NULL;
80 SciErr sciErr;
81
82 //first call to retrieve dimensions
83 sciErr = readNamedMatrixOfString(pvApiCtx,variableToBeRetrieved,&iRows, &iCols, NULL, NULL);
84 if(sciErr.iErr)
85 {
86         printError(&sciErr, 0);
87 }
88
89 piLen = (int*)malloc(sizeof(int) * iRows * iCols);
90 //second call to retrieve length of each string
91 sciErr = readNamedMatrixOfString(pvApiCtx,variableToBeRetrieved, &iRows, &iCols, piLen, NULL);
92 if(sciErr.iErr)
93 {
94         printError(&sciErr, 0);
95 }
96
97 pstData = (char**)malloc(sizeof(char*) * iRows * iCols);
98 for(i = 0 ; i < iRows * iCols ; i++)
99         {
100                 pstData[i] = (char*)malloc(sizeof(char) * (piLen[i] + 1));//+ 1 for null termination
101         }
102 //third call to retrieve data
103 sciErr = readNamedMatrixOfString(pvApiCtx, variableToBeRetrieved, &iRows, &iCols, piLen, pstData);
104 if(sciErr.iErr)
105 {
106         printError(&sciErr, 0);
107 }
108
109 printf("\n");
110 printf("Load and display of A:\n");
111 for(j = 0 ; j < iCols ; j++)
112 {
113         for(i = 0 ; i < iRows ; i++)
114         {
115                 /* Display the formated matrix with same scilab index */
116                 printf("[%d,%d] = %s\n",j+1,i+1,pstData[j* iRows + i]);
117         }
118 }
119
120 printf("\n");
121 free(piLen);
122 for(i = 0 ; i < iRows * iCols ; i++)
123         {
124                 free(pstData[i]);
125         }
126 free(pstData);
127
128  ]]></programlisting>
129     </refsection>
130     <refsection role="see also">
131         <title>See also</title>
132         <simplelist type="inline">
133             <member>
134                 <link linkend="call_scilab">Call_Scilab</link>
135             </member>
136             <member>
137                 <link linkend="api_scilab_legacy">api Scilab</link>
138             </member>
139             <member>
140                 <link linkend="SendScilabJob">SendScilabJob</link>
141             </member>
142             <member>
143                 <link linkend="StartScilab">StartScilab</link>
144             </member>
145             <member>
146                 <link linkend="BooleanManagement_callscilab">Call_Scilab: Boolean Management</link>
147             </member>
148             <member>
149                 <link linkend="DoubleManagement_callscilab">Call_Scilab: Double Management</link>
150             </member>
151             <member>
152                 <link linkend="boolean_reading_API">API_Scilab: Boolean Reading</link>
153             </member>
154             <member>
155                 <link linkend="boolean_writing_API">API_Scilab: Boolean Writing</link>
156             </member>
157             <member>
158                 <link linkend="Double_management_reading_API">API_Scilab: Double Reading</link>
159             </member>
160             <member>
161                 <link linkend="Double_management_writing_API">API_Scilab: Double Writing</link>
162             </member>
163             <member>
164                 <link linkend="ComplexManagement_callscilab">Complex Management</link>
165             </member>
166         </simplelist>
167     </refsection>
168 </refentry>