update api_scilab documention with changes on pvApiCtx
[scilab.git] / scilab / modules / api_scilab / help / en_US / low_level_functions / sparse_writing_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 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="Sparse_management_writing_API" xml:lang="en">
14   <refnamediv>
15     <refname>Sparse writing (Scilab gateway)</refname>
16     <refpurpose>
17       How to write sparse matrix in a gateway.
18     </refpurpose>
19   </refnamediv>
20   <refsynopsisdiv>
21     <refsection>
22       Create from existing data.
23     </refsection>
24     <title>Calling Sequence</title>
25     <para>Input argument profile:</para>
26     <synopsis>SciErr createSparseMatrix(void* _pvCtx, int _iVar, int _iRows, int _iCols, int _iNbItem, const int* _piNbItemRow, const int* _piColPos, const double* _pdblReal)</synopsis>
27     <synopsis>SciErr createComplexSparseMatrix(void* _pvCtx, int _iVar, int _iRows, int _iCols, int _iNbItem, const int* _piNbItemRow, const int* _piColPos, const double* _pdblReal, const double* _pdblImg)</synopsis>
28     <para>Named variable profile:</para>
29     <synopsis>SciErr createNamedSparseMatrix(void* _pvCtx, const char* _pstName, int _iRows, int _iCols, int _iNbItem, const int* _piNbItemRow, const int* _piColPos, const double* _pdblReal)</synopsis>
30     <synopsis>SciErr createNamedComplexSparseMatrix(void* _pvCtx, const char* _pstName, int _iRows, int _iCols, int _iNbItem, const int* _piNbItemRow, const int* _piColPos, const double* _pdblReal, const double* _pdblImg)</synopsis>
31   </refsynopsisdiv>
32   <refsection>
33     <title>Arguments</title>
34     <variablelist>
35       <varlistentry>
36         <term>_pvCtx</term>
37         <listitem>
38           <para>
39             Scilab environment pointer, pass in "pvApiCtx" provided by api_scilab.h
40           </para>
41         </listitem>
42       </varlistentry>
43       <varlistentry>
44         <term>_iVar</term>
45         <listitem>
46           <para>
47             Position in the Scilab memory where you want to put the variable.
48           </para>
49         </listitem>
50       </varlistentry>
51       <varlistentry>
52         <term>_pstName</term>
53         <listitem>
54           <para>
55             Name of the variable for "named" functions.
56           </para>
57         </listitem>
58       </varlistentry>
59       <varlistentry>
60         <term>_iRows</term>
61         <listitem>
62           <para>
63             Number of rows of the new variable.
64           </para>
65         </listitem>
66       </varlistentry>
67       <varlistentry>
68         <term>_iCols</term>
69         <listitem>
70           <para>
71             Number of columns of the new variable.
72           </para>
73         </listitem>
74       </varlistentry>
75       <varlistentry>
76         <term>_iNbItem</term>
77         <listitem>
78           <para>
79             Number of non zero itmes in the sparse.
80           </para>
81         </listitem>
82       </varlistentry>
83       <varlistentry>
84         <term>_piNbItemRow</term>
85         <listitem>
86           <para>
87             Number of item in each rows (size: _iRows).
88           </para>
89         </listitem>
90       </varlistentry>
91       <varlistentry>
92         <term>_piColPos</term>
93         <listitem>
94           <para>
95             Column position for each item (size: _iNbItem).
96           </para>
97         </listitem>
98       </varlistentry>
99       <varlistentry>
100         <term>_pdblReal</term>
101         <listitem>
102           <para>
103             Address of real data array (size: _iNbItem).
104           </para>
105         </listitem>
106       </varlistentry>
107       <varlistentry>
108         <term>_pdblImg</term>
109         <listitem>
110           <para>
111             Address of imaginary data array (size: _iNbItem).
112           </para>
113           <para>
114             This argument does not exist with createSparseMatrix and createNamedSparseMatrix.
115           </para>
116         </listitem>
117       </varlistentry>
118       <varlistentry>
119         <term>SciErr</term>
120         <listitem>
121           <para>
122             Error structure where is stored errors messages history and first error number.
123           </para>
124         </listitem>
125       </varlistentry>
126     </variablelist>
127   </refsection>
128   <refsynopsisdiv>
129     <refsection>
130       Write directly in Scilab memory.
131     </refsection>
132     <title>Calling Sequence</title>
133     <para>Input argument profile:</para>
134     <synopsis>SciErr allocSparseMatrix(void* _pvCtx, int _iVar, int _iRows, int _iCols, int _iNbItem, int** _piNbItemRow, int** _piColPos, double** _pdblReal)</synopsis>
135     <synopsis>SciErr allocComplexSparseMatrix(void* _pvCtx, int _iVar, int _iRows, int _iCols, int _iNbItem, int** _piNbItemRow, int** _piColPos, double** _pdblReal, double** _pdblImg)</synopsis>
136   </refsynopsisdiv>
137   <refsection>
138     <title>Arguments</title>
139     <variablelist>
140       <varlistentry>
141         <term>_pvCtx</term>
142         <listitem>
143           <para>
144             Scilab environment pointer, pass in "pvApiCtx" provided by api_scilab.h.
145           </para>
146         </listitem>
147       </varlistentry>
148       <varlistentry>
149         <term>_iVar</term>
150         <listitem>
151           <para>
152             Position in the Scilab memory where you want to put the variable.
153           </para>
154         </listitem>
155       </varlistentry>
156       <varlistentry>
157         <term>_iRows</term>
158         <listitem>
159           <para>
160             Number of rows of the new variable.
161           </para>
162         </listitem>
163       </varlistentry>
164       <varlistentry>
165         <term>_iCols</term>
166         <listitem>
167           <para>
168             Number of columns of the new variable.
169           </para>
170         </listitem>
171       </varlistentry>
172       <varlistentry>
173         <term>_iNbItem</term>
174         <listitem>
175           <para>
176             Number of non zero itmes in the sparse.
177           </para>
178         </listitem>
179       </varlistentry>
180       <varlistentry>
181         <term>_piNbItemRow</term>
182         <listitem>
183           <para>
184             Return address of number of item in each rows (size: _iRows).
185           </para>
186         </listitem>
187       </varlistentry>
188       <varlistentry>
189         <term>_piColPos</term>
190         <listitem>
191           <para>
192             Return address of column position for each item (size: _iNbItem).
193           </para>
194         </listitem>
195       </varlistentry>
196       <varlistentry>
197         <term>_pdblReal</term>
198         <listitem>
199           <para>
200             Address of real data array (size: _iNbItem).
201           </para>
202         </listitem>
203       </varlistentry>
204       <varlistentry>
205         <term>_pdblImg</term>
206         <listitem>
207           <para>
208             Address of imaginary data array (size: _iNbItem).
209           </para>
210           <para>
211             This argument does not exist with allocSparseMatrix.
212           </para>
213         </listitem>
214       </varlistentry>
215       <varlistentry>
216         <term>SciErr</term>
217         <listitem>
218           <para>
219             Error structure where is stored errors messages history and first error number.
220           </para>
221         </listitem>
222       </varlistentry>
223     </variablelist>
224   </refsection>
225   <refsection>
226     <title>Description</title>
227     <para>This help describes how to add sparse matrix.</para>
228     <para>Two types of functions can be used to write in the memory of Scilab.</para>
229   </refsection>
230   <refsection>
231     <!--File_gateway: SCI/modules/api_scilab/tests/unit_tests/sparse_writing_api.c-->
232     <!--File_scilab: SCI/modules/api_scilab/tests/unit_tests/sparse_writing_api.tst-->
233     <!--Lib_name: sparse_writing-->
234     <!--Func_list: write_sparse-->
235     <title>Gateway Source</title>
236     <programlisting role="code_gateway"><![CDATA[ 
237 #include "api_scilab.h"
238 int write_sparse(char *fname,unsigned long fname_len)
239 {
240         SciErr sciErr;
241         int piNbItemRow[]       = {1,2,1};
242         int piColPos[]          = {8,4,7,2};
243         double pdblSReal[]      = {1,2,3,4};
244         double pdblSImg[]       = {4,3,2,1};
245         int iNbItem                     = 4;
246
247         sciErr = createComplexSparseMatrix(pvApiCtx, nbInputArgument(pvApiCtx) + 1, 3, 10, iNbItem, piNbItemRow, piColPos, pdblSReal, pdblSImg);
248         if(sciErr.iErr)
249         {
250                 printError(&sciErr, 0);
251                 return 0;
252         }
253
254         AssignOutputVariable(pvApiCtx, 1) = nbInputArgument(pvApiCtx) + 1;
255         return 0;
256 }
257  ]]></programlisting>
258   </refsection>
259   <refsection>
260     <title>Scilab test script</title>
261     <programlisting role="code_scilab"><![CDATA[ 
262 sp_ref = sparse([1,8;2,4;2,7;3,2],[1+4*%i,2+3*%i,3+2*%i,4+%i], [3,10]);
263 sp = write_sparse();
264 if or(sp <> sp_ref) then error("failed"), end
265  ]]></programlisting>
266   </refsection>
267 </refentry>