bb57ff2fa4a772859951254ce34c559533268503
[scilab.git] / scilab / modules / api_scilab / help / en_US / double_reading_api.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 - Antoine ELIAS
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 version="5.0-subset Scilab" xml:id="Double_management_reading_API"
14           xml:lang="en" xmlns="http://docbook.org/ns/docbook"
15           xmlns:xlink="http://www.w3.org/1999/xlink"
16           xmlns:svg="http://www.w3.org/2000/svg"
17           xmlns:ns5="http://www.w3.org/1999/xhtml"
18           xmlns:mml="http://www.w3.org/1998/Math/MathML"
19           xmlns:db="http://docbook.org/ns/docbook">
20
21     <refnamediv>
22         <refname>Double reading (Scilab gateway)</refname>
23
24         <refpurpose>
25             How to read matrices of doubles in a gateway.
26         </refpurpose>
27     </refnamediv>
28     <refsynopsisdiv>
29       <title>Calling Sequence</title>
30       <synopsis>
31 int getMatrixOfDouble(int* _piAddress _iVar, int* _piRows, int* _piCols, double** _pdblReal)
32 int getComplexMatrixOfDouble(int* _piAddress, int* _piRows, int* _piCols, double** _pdblReal, double** _pdblImg)
33         </synopsis>
34     </refsynopsisdiv>
35     <refsection>
36         <title>Parameters</title>
37
38         <variablelist>
39             <varlistentry>
40                 <term>_piAddress</term>
41                 <listitem>
42                     <para>
43                         Address of the Scilab variable.
44                     </para>
45                 </listitem>
46             </varlistentry>
47
48             <varlistentry>
49                 <term>_piRows</term>
50                 <listitem>
51                     <para>
52                         Return number of rows.
53                     </para>
54                 </listitem>
55             </varlistentry>
56
57             <varlistentry>
58                 <term>_piCols</term>
59                 <listitem>
60                     <para>
61                         Return number of columns.
62                     </para>
63                 </listitem>
64             </varlistentry>
65
66             <varlistentry>
67                 <term>_pdblReal</term>
68                 <listitem>
69                     <para>
70                         Return address of real data array (size: _iCols * _iRows)
71                     </para>
72                 </listitem>
73             </varlistentry>
74
75             <varlistentry>
76                 <term>_pdblImg</term>
77                 <listitem>
78                     <para>
79                         Return address of imaginary data array (size: _iCols * _iRows)
80                     </para>
81                 </listitem>
82             </varlistentry>
83
84         </variablelist>
85     </refsection>
86     <refsection>
87         <title>Description</title>
88         <para>This help describes how matrix of doubles can be handled through the Scilab API.</para>
89     </refsection>
90     <refsection>
91         <!--File_gateway: SCI/modules/core/tests/unit_tests/double_reading_api.c-->
92         <!--File_scilab: SCI/modules/core/tests/unit_tests/double_reading_api.tst-->
93         <!--Lib_name: double_reading-->
94         <!--Func_list: read_double-->
95         <title>Gateway Source</title>
96         <programlisting role="code_gateway">
97             <![CDATA[
98 int read_double(char *fname,unsigned long fname_len)
99 {
100     int i;
101     int iRet            = 0;
102     //first variable info : real matrix of double
103     int iRows           = 0;
104     int iCols           = 0;
105     int iComplex        = 0;
106     int *piAddr         = NULL;
107     double* pdblReal    = NULL;
108     double* pdblImg     = NULL;
109
110     //check input and output arguments
111     CheckRhs(1,1);
112     CheckLhs(1,1);
113
114     /************************
115     *    First variable    *
116     ************************/
117
118     //get variable address
119     getVarAddressFromPosition(1, &piAddr);
120
121     //check type
122     if(getVarType(piAddr) != sci_matrix)
123     {
124         //Error
125         return 1;
126     }
127     
128     //get complexity
129     iComplex    = isVarComplex(piAddr);
130
131     //check complexity
132     if(iComplex)
133     {
134         //get size and data from Scilab memory
135         iRet = getComplexMatrixOfDouble(piAddr, &iRows, &iCols, &pdblReal, &pdblImg);
136     }
137     else
138     {
139         //get size and data from Scilab memory
140         iRet = getMatrixOfDouble(piAddr, &iRows, &iCols, &pdblReal);
141     }
142
143     if(iRet)
144     {
145         //Error
146         return 1;
147     }
148
149     // Do something with data
150
151
152     //if variable is complex, invert real part and imaginary part otherwise multiply by -1
153     if(iComplex)
154     {
155         createComplexMatrixOfDouble(Rhs + 1, iRows, iCols, pdblImg, pdblReal);
156     }
157     else
158     {
159         for(i = 0 ; i < iRows * iCols ; i++)
160         {
161             pdblReal[i] *= -1;
162         }
163         createMatrixOfDouble(Rhs + 1, iRows, iCols, pdblReal);
164     }
165
166     if(iRet)
167     {
168         //Error
169         return 1;
170     }
171     LhsVar(1) = Rhs + 1;
172     return 0;
173 }
174         ]]>
175         </programlisting>
176     </refsection>
177
178     <refsection>
179         <title>Scilab test script</title>
180         <programlisting role="code_scilab">
181             <![CDATA[
182 a = [   0 1 2 3; ..
183         4 5 6 7; ..
184         8 9 10 11];
185 b = [   23*%i,      1+22*%i,    2+21*%i,    3+20*%i,    4+19*%i,    5+18*%i; ..
186         6+17*%i,    7+16*%i,    8+15*%i,    9+14*%i,     10+13*%i,  11+12*%i; ..
187         12+11*%i,   13+10*%i,   14+9*%i,    15+8*%i,    16+7*%i,    17+6*%i; ..
188         18+5*%i,    19+4*%i,    20+3*%i,    21+2*%i,    22+1*%i,    23];
189
190 a2 = read_double(a);
191 b2 = read_double(b);
192
193 if or(a2 <> a * -1) then error("failed"), end
194 if or(b2 <> (imag(b) + real(b) * %i)) then error("failed"), end
195             ]]>
196         </programlisting>
197     </refsection>
198 </refentry>