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