Merge branch '5.1' of git@git.scilab.org:scilab into 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
93       <listitem>
94         <para>Por re-linkagem "forçosa" ("hard"), escrevendo a rotina dentro
95         da rotina Scilab <literal>default/Ex-fort.f</literal>, adicionando o
96         ponto de entrada no arquivo <literal>default/Flist</literal> e então
97         re-linkando o Scilab com o comando <literal>make bin/scilex</literal>
98         no diretório principal do Scilab.</para>
99       </listitem>
100     </itemizedlist>
101
102     <para>Há duas formas de sintaxe de chamamento, uma curta e uma longa. A
103     curta fornece um código mais rápido e uma sintaxe de chamamento mais
104     fácil, mas deve-se escrever uma pequena interface (C ou FORTRAN) para que
105     esta forma seja possível. A forma longa torna possível uma chamada a uma
106     rotina FORTRAN (ou C) sem modificação do código, mas a sintaxe é mais
107     complexa e o código interpretado mais devagar.</para>
108
109     <para>O significado de cada parâmetro é descrito abaixo: </para>
110
111     <variablelist>
112       <varlistentry>
113         <term>"ident"</term>
114
115         <listitem>
116           <para>é o nome da subrotina chamada. </para>
117         </listitem>
118       </varlistentry>
119
120       <varlistentry>
121         <term>x1,...,xn</term>
122
123         <listitem>
124           <para>são as variáveis de entrada (strings ou matrizes de reais)
125           enviados à rotina</para>
126         </listitem>
127       </varlistentry>
128
129       <varlistentry>
130         <term>px1,...,pxn</term>
131
132         <listitem>
133           <para>são as respectivas posições destas variáveis na seqüência de
134           chamamento da rotina <literal>"ident"</literal> e</para>
135         </listitem>
136       </varlistentry>
137
138       <varlistentry>
139         <term>tx1,...,txn</term>
140
141         <listitem>
142           <para>são seus tipos (<literal>"r"</literal>,
143           <literal>"i"</literal>, <literal>"d"</literal> e
144           <literal>"c"</literal> para ponto flutuante real , inteiro, dupla
145           precisão e strings) </para>
146         </listitem>
147       </varlistentry>
148
149       <varlistentry>
150         <term>"out"</term>
151
152         <listitem>
153           <para>é a palavra-chave usada para separar variáveis de entrada das
154           variáveis de saída. Quando esta palavra-chave está presente, ela
155           indica que a forma longa será usada e quando não está presente,
156           indica que a forma curta será usada. </para>
157         </listitem>
158       </varlistentry>
159
160       <varlistentry>
161         <term>[ny1, my1]</term>
162
163         <listitem>
164           <para>são os tamanhos (número de linhas e colunas. Para argumentos
165           'c',<literal> m1*n1</literal> é o número de caracteres) das
166           variáveis de saída e </para>
167         </listitem>
168       </varlistentry>
169
170       <varlistentry>
171         <term>py1, ...</term>
172
173         <listitem>
174           <para>são as posições das variáveis de saída (possivelmente iguais a
175           <literal>pxi</literal> ) na seqüência de chamamento da rotina. Os
176           inteiros <literal>pyi</literal>'s devem estar em ordem
177           crescente.</para>
178         </listitem>
179       </varlistentry>
180
181       <varlistentry>
182         <term>"ty1", ...</term>
183
184         <listitem>
185           <para>são os tipos FORTRAN das variáveis de saída. As
186           <literal>k</literal> primeiras variáveis de saída são postas em
187           <literal>y1,..., yk</literal>.</para>
188         </listitem>
189       </varlistentry>
190     </variablelist>
191
192     <para>Se uma variável de saída coincide com uma variável de entrada (i.e.,
193     <literal>pyi=pxj</literal> ) pode-se apenas passar sua posição
194     <literal>pyi</literal> . O tamanho e tipo de <literal>yi</literal> são
195     então os mesmos que os de<literal>xi</literal>. Se uma variável de saída
196     coincide com uma variável de entrada e são especificadas as dimensões da
197     variável de saída, <literal>[myl,nyl]</literal> deve satisfazer a condição
198     de compatibilidade <literal>mxk*nxk &gt;= myl*nyl</literal>.</para>
199
200     <para>No caso da sintaxe curta,
201     <literal>[y1,....,yk]=call("ident",x1,...,xn)</literal>, os parâmetros de
202     entrada <literal>xi</literal>'s e o nome <literal>"ident"</literal> são
203     enviados para a rotina de interface <literal>Ex-fort</literal>. Esta
204     rotina de interface é, então, muito semelhante a uma interface (ver código
205     fonte no diretório <literal>SCIDIR/default/Ex-fort.f</literal>).</para>
206   </refsection>
207
208   <refsection>
209     <title>Exemplos</title>
210
211     <programlisting role="example">
212     
213     //Exemplo 1 com um código C simples
214     f1=['#include &lt;math.h&gt;'
215         'void fooc(c,a,b,m,n)'
216          'double a[],*b,c[];'
217          'int *m,*n;'
218          '{'
219          '   int i;'
220          '   for ( i =0 ; i &lt; (*m)*(*n) ; i++) '
221          '     c[i] = sin(a[i]) + *b; '
222          '}'];
223
224     mputl(f1,'fooc.c')
225
226     //criando a biblioteca compartilhada (um gateway (ligação), um Makefile e um loader (carregador) são 
227     //gerados.)  
228
229     ilib_for_link('fooc','fooc.o',[],"c") 
230
231     // carregando a biblioteca compartilhada  
232
233     exec loader.sce 
234
235     //usando a nova primitiva
236     a=[1,2,3;4,5,6];b= %pi;
237     [m,n]=size(a);
238
239     // Entradas:
240     // a está na posição 2 e double
241     // b                3     double
242     // n                4     integer
243     // m                5     integer
244     // Saídas:
245     // c está na posição 1 e double com tamanho [m,n]
246     c=call("fooc",a,2,"d",b,3,"d",m,4,"i",n,5,"i","out",[m,n],1,"d");
247
248     //Exemplo 2 com um código FORTRAN simples
249     f1=['      subroutine foof(c,a,b,n,m)'
250         '      integer n,m'
251         '      double precision a(*),b,c(*)'
252         '      do 10 i=1,m*n '
253         '        c(i) = sin(a(i))+b'
254         '   10 continue'
255         '      end'];
256     mputl(f1,'foof.f')
257
258     //criando a biblioteca compartilhada (um gateway, um Makefile e um loader são  
259     //gerados.)  
260
261     ilib_for_link('foof','foof.o',[],"f") 
262
263     // carrega a biblioteca compartilhada 
264
265     exec loader.sce 
266
267     //usando a nova primitiva
268     a=[1,2,3;4,5,6];b= %pi;
269     [m,n]=size(a);
270     c=call("foof",a,2,"d",b,3,"d",m,4,"i",n,5,"i","out",[m,n],1,"d");
271
272
273  
274   </programlisting>
275   </refsection>
276
277   <refsection>
278     <title>Ver Também</title>
279
280     <simplelist type="inline">
281       <member><link linkend="link">link</link></member>
282
283       <member><link linkend="c_link">c_link</link></member>
284
285       <member><link linkend="intersci">intersci</link></member>
286
287       <member><link linkend="addinter">addinter</link></member>
288     </simplelist>
289   </refsection>
290 </refentry>