Merge commit 'refs/remotes/origin/5.1'
[scilab.git] / scilab / modules / dynamic_link / help / pt_BR / call.xml
1 <?xml version="1.0" encoding="ISO-8859-1"?>
2 <!--
3  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
4  * Copyright (C) INRIA - 
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="call" xml:lang="en"
14           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:ns4="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   <info>
21     <pubdate>$LastChangedDate$</pubdate>
22   </info>
23
24   <refnamediv>
25     <refname>call</refname>
26
27     <refpurpose>chamada a rotinas de usuário FORTRAN ou C</refpurpose>
28   </refnamediv>
29
30   <refsynopsisdiv>
31     <title>Seqüência de Chamamento</title>
32
33     <synopsis>// forma longa: 'out' está presente  
34 [y1,...,yk]=call("ident",x1,px1,"tx1",...,xn,pxn,"txn", 
35 "out",[ny1,my1],py1,"ty1",...,[nyl,myl],pyl,"tyl") 
36 // forma curta : nenhum parâmetro 'out' 
37 [y1,....,yk]=call("ident",x1,...,xn) </synopsis>
38   </refsynopsisdiv>
39
40   <refsection>
41     <title>Parâmetros</title>
42
43     <variablelist>
44       <varlistentry>
45         <term>"ident"</term>
46
47         <listitem>
48           <para>string.</para>
49         </listitem>
50       </varlistentry>
51
52       <varlistentry>
53         <term>xi</term>
54
55         <listitem>
56           <para>real matrix or string</para>
57         </listitem>
58       </varlistentry>
59
60       <varlistentry>
61         <term>pxi, pyi</term>
62
63         <listitem>
64           <para>inteiro</para>
65         </listitem>
66       </varlistentry>
67
68       <varlistentry>
69         <term>txi, tyi</term>
70
71         <listitem>
72           <para>string <literal>"d"</literal>, <literal>"r"</literal>,
73           <literal>"i"</literal> ou <literal>"c"</literal>.</para>
74         </listitem>
75       </varlistentry>
76     </variablelist>
77   </refsection>
78
79   <refsection>
80     <title>Descrição</title>
81
82     <para>Chamada interativa ao programa do usuário FORTRAN (ou C) do Scilab.
83     A rotina deve estar previamente linkada ("ligada") ao Scilab. Este link
84     pode ser feito:</para>
85
86     <itemizedlist>
87       <listitem>
88         <para>Com o comando "<literal>link</literal>" do Scilab (linkagem
89         "suave" ("soft") incremental) durante a sessão Scilab. (ver
90         <literal>link</literal>)</para>
91       </listitem>
92     </itemizedlist>
93
94     <para>Há duas formas de sintaxe de chamamento, uma curta e uma longa. A
95     curta fornece um código mais rápido e uma sintaxe de chamamento mais
96     fácil, mas deve-se escrever uma pequena interface (C ou FORTRAN) para que
97     esta forma seja possível. A forma longa torna possível uma chamada a uma
98     rotina FORTRAN (ou C) sem modificação do código, mas a sintaxe é mais
99     complexa e o código interpretado mais devagar.</para>
100
101     <para>O significado de cada parâmetro é descrito abaixo: </para>
102
103     <variablelist>
104       <varlistentry>
105         <term>"ident"</term>
106
107         <listitem>
108           <para>é o nome da subrotina chamada. </para>
109         </listitem>
110       </varlistentry>
111
112       <varlistentry>
113         <term>x1,...,xn</term>
114
115         <listitem>
116           <para>são as variáveis de entrada (strings ou matrizes de reais)
117           enviados à rotina</para>
118         </listitem>
119       </varlistentry>
120
121       <varlistentry>
122         <term>px1,...,pxn</term>
123
124         <listitem>
125           <para>são as respectivas posições destas variáveis na seqüência de
126           chamamento da rotina <literal>"ident"</literal> e</para>
127         </listitem>
128       </varlistentry>
129
130       <varlistentry>
131         <term>tx1,...,txn</term>
132
133         <listitem>
134           <para>são seus tipos (<literal>"r"</literal>,
135           <literal>"i"</literal>, <literal>"d"</literal> e
136           <literal>"c"</literal> para ponto flutuante real , inteiro, dupla
137           precisão e strings) </para>
138         </listitem>
139       </varlistentry>
140
141       <varlistentry>
142         <term>"out"</term>
143
144         <listitem>
145           <para>é a palavra-chave usada para separar variáveis de entrada das
146           variáveis de saída. Quando esta palavra-chave está presente, ela
147           indica que a forma longa será usada e quando não está presente,
148           indica que a forma curta será usada. </para>
149         </listitem>
150       </varlistentry>
151
152       <varlistentry>
153         <term>[ny1, my1]</term>
154
155         <listitem>
156           <para>são os tamanhos (número de linhas e colunas. Para argumentos
157           'c',<literal> m1*n1</literal> é o número de caracteres) das
158           variáveis de saída e </para>
159         </listitem>
160       </varlistentry>
161
162       <varlistentry>
163         <term>py1, ...</term>
164
165         <listitem>
166           <para>são as posições das variáveis de saída (possivelmente iguais a
167           <literal>pxi</literal> ) na seqüência de chamamento da rotina. Os
168           inteiros <literal>pyi</literal>'s devem estar em ordem
169           crescente.</para>
170         </listitem>
171       </varlistentry>
172
173       <varlistentry>
174         <term>"ty1", ...</term>
175
176         <listitem>
177           <para>são os tipos FORTRAN das variáveis de saída. As
178           <literal>k</literal> primeiras variáveis de saída são postas em
179           <literal>y1,..., yk</literal>.</para>
180         </listitem>
181       </varlistentry>
182     </variablelist>
183
184     <para>Se uma variável de saída coincide com uma variável de entrada (i.e.,
185     <literal>pyi=pxj</literal> ) pode-se apenas passar sua posição
186     <literal>pyi</literal> . O tamanho e tipo de <literal>yi</literal> são
187     então os mesmos que os de<literal>xi</literal>. Se uma variável de saída
188     coincide com uma variável de entrada e são especificadas as dimensões da
189     variável de saída, <literal>[myl,nyl]</literal> deve satisfazer a condição
190     de compatibilidade <literal>mxk*nxk &gt;= myl*nyl</literal>.</para>
191   </refsection>
192
193   <refsection>
194     <title>Exemplos</title>
195
196     <programlisting role="example">
197     
198     //Exemplo 1 com um código C simples
199     f1=['#include &lt;math.h&gt;'
200         'void fooc(c,a,b,m,n)'
201          'double a[],*b,c[];'
202          'int *m,*n;'
203          '{'
204          '   int i;'
205          '   for ( i =0 ; i &lt; (*m)*(*n) ; i++) '
206          '     c[i] = sin(a[i]) + *b; '
207          '}'];
208
209     mputl(f1,'fooc.c')
210
211     //criando a biblioteca compartilhada (um gateway (ligação), um Makefile e um loader (carregador) são 
212     //gerados.)  
213
214     ilib_for_link('fooc','fooc.o',[],"c") 
215
216     // carregando a biblioteca compartilhada  
217
218     exec loader.sce 
219
220     //usando a nova primitiva
221     a=[1,2,3;4,5,6];b= %pi;
222     [m,n]=size(a);
223
224     // Entradas:
225     // a está na posição 2 e double
226     // b                3     double
227     // n                4     integer
228     // m                5     integer
229     // Saídas:
230     // c está na posição 1 e double com tamanho [m,n]
231     c=call("fooc",a,2,"d",b,3,"d",m,4,"i",n,5,"i","out",[m,n],1,"d");
232
233     //Exemplo 2 com um código FORTRAN simples
234     f1=['      subroutine foof(c,a,b,n,m)'
235         '      integer n,m'
236         '      double precision a(*),b,c(*)'
237         '      do 10 i=1,m*n '
238         '        c(i) = sin(a(i))+b'
239         '   10 continue'
240         '      end'];
241     mputl(f1,'foof.f')
242
243     //criando a biblioteca compartilhada (um gateway, um Makefile e um loader são  
244     //gerados.)  
245
246     ilib_for_link('foof','foof.o',[],"f") 
247
248     // carrega a biblioteca compartilhada 
249
250     exec loader.sce 
251
252     //usando a nova primitiva
253     a=[1,2,3;4,5,6];b= %pi;
254     [m,n]=size(a);
255     c=call("foof",a,2,"d",b,3,"d",m,4,"i",n,5,"i","out",[m,n],1,"d");  </programlisting>
256   </refsection>
257
258   <refsection>
259     <title>Ver Também</title>
260
261     <simplelist type="inline">
262       <member><link linkend="link">link</link></member>
263
264       <member><link linkend="c_link">c_link</link></member>
265
266       <member><link linkend="intersci">intersci</link></member>
267
268       <member><link linkend="addinter">addinter</link></member>
269     </simplelist>
270   </refsection>
271 </refentry>