update api_scilab documention with changes on pvApiCtx
[scilab.git] / scilab / modules / api_scilab / help / en_US / low_level_functions / boolean_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 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="boolean_reading_API" xml:lang="en">
14   <refnamediv>
15     <refname>Boolean reading (Scilab gateway)</refname>
16     <refpurpose>
17       How to read matrix of boolean.
18     </refpurpose>
19   </refnamediv>
20   <refsynopsisdiv>
21     <title>Calling Sequence</title>
22     <para>Input argument profile:</para>
23     <synopsis>SciErr getMatrixOfBoolean(void* _pvCtx, int* _piAddress, int* _piRows, int* _piCols, int** _piBool)</synopsis>
24     <para>Named variable profile:</para>
25     <synopsis>SciErr readNamedMatrixOfBoolean(void* _pvCtx, const char* _pstName, int* _piRows, int* _piCols, int* _piBool)</synopsis>
26   </refsynopsisdiv>
27   <refsection>
28     <title>Arguments</title>
29     <variablelist>
30       <varlistentry>
31         <term>_pvCtx</term>
32         <listitem>
33           <para>
34             Scilab environment pointer, pass in "pvApiCtx" provided by api_scilab.h.
35           </para>
36         </listitem>
37       </varlistentry>
38       <varlistentry>
39         <term>_piAddress</term>
40         <listitem>
41           <para>
42             Address of the Scilab variable.
43           </para>
44         </listitem>
45       </varlistentry>
46       <varlistentry>
47         <term>_pstName</term>
48         <listitem>
49           <para>
50             Name of the variable for "named" functions.
51           </para>
52         </listitem>
53       </varlistentry>
54       <varlistentry>
55         <term>_piRows</term>
56         <listitem>
57           <para>
58             Return number of rows of the variable.
59           </para>
60         </listitem>
61       </varlistentry>
62       <varlistentry>
63         <term>_piCols</term>
64         <listitem>
65           <para>
66             Return number of columns of the variable.
67           </para>
68         </listitem>
69       </varlistentry>
70       <varlistentry>
71         <term>_piBool</term>
72         <listitem>
73           <para>
74             Return address of data array (size: _iRows * _iCols).
75             For "Named" function, _piBool must be allocated before calling function.
76           </para>
77         </listitem>
78       </varlistentry>
79       <varlistentry>
80         <term>SciErr</term>
81         <listitem>
82           <para>
83             Error structure where is stored errors messages history and first error number.
84           </para>
85         </listitem>
86       </varlistentry>
87     </variablelist>
88   </refsection>
89   <refsection>
90     <title>Description</title>
91     <para>This help describes how to read matrix of boolean.</para>
92   </refsection>
93   <refsection>
94     <!--File_gateway: SCI/modules/api_scilab/tests/unit_tests/read_write_boolean_api.c-->
95     <!--File_scilab: SCI/modules/api_scilab/tests/unit_tests/read_write_boolean_api.tst-->
96     <!--Lib_name: read_write_boolean-->
97     <!--Func_list: read_write_boolean-->
98     <title>Gateway Source</title>
99     <programlisting role="code_gateway"><![CDATA[ 
100 #include "api_scilab.h"
101 int read_write_boolean(char *fname,unsigned long fname_len)
102 {
103     SciErr sciErr;
104     int i;
105     //first variable info : real matrix of double
106     int iRows       = 0;
107     int iCols       = 0;
108     int *piAddr     = NULL;
109     int* piBool     = NULL;
110
111     //check input and output arguments
112     CheckInputArgument(pvApiCtx, 1,1);
113     CheckOutputArgument(pvApiCtx, 1,1);
114
115     //get variable address of the first input argument
116     sciErr = getVarAddressFromPosition(pvApiCtx, 1, &piAddr);
117     if(sciErr.iErr)
118     {
119         printError(&sciErr, 0);
120         return 0;
121     }
122
123     //get size and data from Scilab memory
124     sciErr = getMatrixOfBoolean(pvApiCtx, piAddr, &iRows, &iCols, &piBool);
125     if(sciErr.iErr)
126     {
127         printError(&sciErr, 0);
128         return 0;
129     }
130
131     //Do something with data
132     for(i = 0 ; i < iRows * iCols ; i++)
133     {
134         piBool[i] = piBool[i] == 0 ? 1 : 0;
135     }
136
137     sciErr = createMatrixOfBoolean(pvApiCtx, nbInputArgument(pvApiCtx) + 1, iRows, iCols, piBool);
138     if(sciErr.iErr)
139     {
140         printError(&sciErr, 0);
141         return 0;
142     }
143
144     AssignOutputVariable(pvApiCtx, 1) = nbInputArgument(pvApiCtx) + 1;
145     return 0;
146 }
147  ]]></programlisting>
148   </refsection>
149   <refsection>
150     <title>Scilab test script</title>
151     <programlisting role="code_scilab"><![CDATA[ 
152 a = [%t, %f, %t ; %f, %t, %f ; %t, %f, %t];
153 a_ref = [%f, %t, %f ; %t, %f, %t ; %f, %t, %f];
154 b = read_write_boolean(a);
155
156 if or(b <> a_ref) then error("failed"), end
157  ]]></programlisting>
158   </refsection>
159 </refentry>