added japanese translation of java external object.
[scilab.git] / scilab / modules / api_scilab / help / ja_JP / getting_started.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) 2012 - Scilab Enterprises - Sylvestre LEDRU
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.1-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" xmlns:scilab="http://www.scilab.org" xml:id="api_scilab_getting_started" xml:lang="ja">
14     <refnamediv>
15         <refname>API_Scilab入門</refname>
16         <refpurpose>
17             C, C++ またはfortranコードを新しい関数としてScilabエンジンに読み込む方法
18         </refpurpose>
19     </refnamediv>
20     <refsection>
21         <title>説明</title>
22         <para>
23             <link linkend="api_scilab">api_scilabプレゼンテーション</link>
24             で説明されたように,
25             ScilabはC, C++またはFortranコード(ソースまたはライブラリ)で言語を
26             拡張するためのAPIを提供します.
27         </para>
28         <para>
29             Scilabエンジンとアプリケーションコードの間のリンクは
30             <literal>gateway</literal>と呼ばれます.
31         </para>
32         <para>
33             多くの場合, 処理は常に同じで,以下のようになります:
34             <orderedlist>
35                 <listitem>
36                     <para>
37                         ユーザに指定された(入力及び出力)引数の数を調べます.
38                     </para>
39                     <para>
40                         例えば,関数<literal>foo(x)</literal>が <literal>foo()</literal> または <literal>foo(2,3)</literal>のようにコールされ, ユーザが答を得ます.
41                     </para>
42                     <para>
43                         詳細: <link linkend="CheckInputArgument">CheckInputArgument</link> および <link linkend="CheckOutputArgument">CheckOutputArgument</link>
44                     </para>
45                 </listitem>
46                 <listitem>
47                     <para>入力引数の管理</para>
48                     <para>
49                         複数の処理を行います:
50                         <orderedlist inheritnum="inherit">
51                             <listitem>
52                                 <para>入力引数Xの変数アドレスを取得します</para>
53                                 <para>
54                                     関数
55                                     <literal>
56                                         SciErr <link linkend="Common_getvaraddr_API">getVarAddressFromPosition</link>(void* context, int positionOfTheVariable, int** address)
57                                     </literal>
58                                 </para>
59                             </listitem>
60                             <listitem>
61                                 <para>変数の型を調べます: doubleの行列 (複素数または複素数以外), 文字列
62                                     , 等
63                                 </para>
64                                 <para>
65                                     <literal>
66                                         SciErr <link linkend="Common_getvartype_API">getVarType</link>(void* context, int* positionOfTheVariable, int* Type)
67                                     </literal>
68                                 </para>
69                                 <para>
70                                     他の関数も提供されています:
71                                     <itemizedlist>
72                                         <listitem>
73                                             <para>
74                                                 <literal>int isBooleanType(void* context, int* address)</literal>
75                                             </para>
76                                         </listitem>
77                                         <listitem>
78                                             <para>
79                                                 <literal>int isBooleanSparseType(void* context, int* address)</literal>
80                                             </para>
81                                         </listitem>
82                                         <listitem>
83                                             <para>
84                                                 <literal>int isDoubleType(void* context, int* address)</literal>
85                                             </para>
86                                         </listitem>
87                                         <listitem>
88                                             <para>
89                                                 <literal>int isIntegerType(void* context, int* address)</literal>
90                                             </para>
91                                         </listitem>
92                                         <listitem>
93                                             <para>
94                                                 <literal>int isPointerType(void* context, int* address)</literal>
95                                             </para>
96                                         </listitem>
97                                         <listitem>
98                                             <para>
99                                                 <literal>int isPolyType(void* context, int* address)</literal>
100                                             </para>
101                                         </listitem>
102                                         <listitem>
103                                             <para>
104                                                 <literal>int isSparseType(void* context, int* address)</literal>
105                                             </para>
106                                         </listitem>
107                                         <listitem>
108                                             <para>
109                                                 <literal>int isStringType(void* context, int* address)</literal>
110                                             </para>
111                                         </listitem>
112                                         <listitem>
113                                             <para>
114                                                 <literal>int isListType(void* context, int* address)</literal>
115                                             </para>
116                                         </listitem>
117                                         <listitem>
118                                             <para>
119                                                 <literal>int isTListType(void* context, int* address)</literal>
120                                             </para>
121                                         </listitem>
122                                         <listitem>
123                                             <para>
124                                                 <literal>int isMListType(void* context, int* address)</literal>
125                                             </para>
126                                         </listitem>
127                                     </itemizedlist>
128                                 </para>
129                             </listitem>
130                             <listitem>
131                                 <para>
132                                     関連する場合, 入力引数かどうかを確認します.
133                                 </para>
134                                 <para>
135                                     <literal>
136                                         int <link linkend="Common_iscomplex_API">isVarComplex</link>(void* context, int* address)
137                                     </literal>
138                                 </para>
139                             </listitem>
140                             <listitem>
141                                 <para>
142                                     整数を処理する場合,さらに整数の精度も確認します
143                                 </para>
144                                 <para>
145                                     <literal>
146                                         SciErr <link linkend="int_getmatrixofintegerprecision_API">getMatrixOfIntegerPrecision</link>(void* context, int* address, int* precision)
147                                     </literal>
148                                 </para>
149                             </listitem>
150                             <listitem>
151                                 <para>変数の大きさを確認します: 正方行列, スカラー, 等</para>
152                                 <para>
153                                     大きさに関する情報を取得する際にも
154                                     実際のデータを取得する際に使用するものと同じ関数を使用します.
155                                     例えば, double の行列の場合 関数コール
156                                     <literal>
157                                         SciErr <link linkend="Double_management_reading_API">getMatrixOfDouble</link>(void* context, int* address, int* nbRows, int* nbCols, double** theActualData)
158                                     </literal>
159                                     により行列の次元を取得できます.
160                                 </para>
161                                 <para>ほぼ全てのScilabデータ型にはこのような処理を行うための
162                                     同様なC関数があります.
163                                 </para>
164                             </listitem>
165                             <listitem>
166                                 <para>
167                                     その他, 特定の値かどうかを調べたり, 最初と2番目の入力引数の間の整合性を
168                                     確認したりすること等も可能です.
169                                 </para>
170                             </listitem>
171                             <listitem>
172                                 <para>データ変換 (オプション).</para>
173                                 <para>
174                                     使用するコードまたはライブラリによっては,
175                                     いくつかの変換をデータに適用することができます.
176                                     古典的な例は行列の記録を列形式から線形式に変換するものです.
177                                 </para>
178                                 <para>
179                                     通常,このようにすると性能が低下することに注意してください.
180                                 </para>
181                             </listitem>
182                         </orderedlist>
183                     </para>
184                 </listitem>
185                 <listitem>
186                     <para>アプリケーションコード</para>
187                     <para>
188                         確認とデータ取得を行った後,実際の主コードをコールできます.
189                         実際の情報処理(処理, データ変換, 等)をここで実行します.
190                     </para>
191                     <para>
192                         これは,
193                         <literal>src/c</literal>, <literal>src/cpp</literal> または
194                         <literal>src/fortran</literal>に保存,構築した
195                         サードパーティのコードにより行いますが,
196                         ライブラリ形式とすることも可能です.
197                         あらゆるライブラリをScilabにリンクすることができます.
198                     </para>
199                 </listitem>
200                 <listitem>
201                     <para>Scilabエンジンの出力引数を作成する</para>
202                     <para>通常,アプリケーションコードの実行後,
203                         何らかのデータをScilabインタプリタから戻します.
204                     </para>
205                     <para>
206                         例えば, doubleの行列をScilabエンジンに保存する場合,C関数
207                         <literal>
208                             SciErr <link linkend="Double_management_writing_API">createMatrixOfDouble</link>(void* context, int position, int nbRows, int nbCols, const double* matrixOfDouble)
209                         </literal>
210                         をコールします.
211                     </para>
212                     <para>
213                         通常,位置は
214                         <literal>nbInputArgument(pvApiCtx) + X</literal>により取得できます. 
215                         <literal>X</literal> が返す出力引数の位置となります.
216                         例えば, 関数プロファイル
217                         <literal>[a, b, c] = foo();</literal> 
218                         <literal>nbInputArgument(pvApiCtx) + 3</literal> は
219                         変数<literal>c</literal>となります.
220                     </para>
221                     <para>
222                         作成できる次元はゲートウェイの制約を受けることに注意してください.
223                     </para>
224                     <para>
225                         ほぼ全てのScilabデータ型はこのような処理を行う同様なC関数を有します.
226                     </para>
227                 </listitem>
228                 <listitem>
229                     <para>Scilabエンジンに出力引数を返す</para>
230                     <para>以下, タスク4で, 作成した変数を返します.</para>
231                     <para>
232                         <literal>a</literal>を返す
233                         前の例 <literal>[a, b, c] = foo();</literal>の場合,
234                         以下の宣言を行います: <literal>AssignOutputVariable(pvApiCtx, 1) = nbInputArgument(pvApiCtx) + 1;</literal>
235                     </para>
236                     <para>
237                         Scilabエンジンに新しい変数をコミットするには,
238                         関数
239                         <link linkend="ReturnArguments">ReturnArguments(pvApiCtx)</link> をコールします.
240                     </para>
241                 </listitem>
242             </orderedlist>
243         </para>
244         <para>
245             API_Scilab関数
246             Note that almost all the API_Scilab functions returns a C structure called SciErr which contains many information about the error.
247         </para>
248         <para>
249             By default, Scilab numerical values are stored with the C type <literal>double</literal>.
250         </para>
251         <para>
252             As convention, gateways are stored in <literal>sci_gateway/c/</literal> (or <literal>/cpp/</literal>) and are called <literal>sci_functionName.c</literal>.
253         </para>
254         <para>
255             <literal>pvApiCtx</literal> is the global context variable. Useless in the 5 family, it has been introduced to manage multithread aspects coming with the version 6 of Scilab.
256         </para>
257     </refsection>
258     <refsection>
259         <title>現実的な例</title>
260         <para>以下のScilab関数を例として示します:</para>
261         <para>
262             <literal>[c,d] = foo(a,b)</literal>
263         </para>
264         <para>
265             <literal>a</literal>はdouble行列,<literal>a</literal>と同じ大きさの
266             <literal>b</literal>は論理値行列,
267             foo は<literal>a</literal>の各要素に2を乗じて,
268             <literal>c</literal>として返します.
269             また,bを要素毎に逆の論理値に変換して返します.
270         </para>
271         <para>
272             Scilabバイナリに含まれるツールボックススケルトンでサンプルを取得できます.
273             パスは
274             <literal>contrib/toolbox_skeleton/sci_gateway/c/sci_foo.c</literal>です.
275         </para>
276         <para>詳細な説明は以下の例のCコメント形式で提供されています.
277         </para>
278         <programlisting role="code_gateway">
279             <![CDATA[ 
280 // 完全なソースはtoolboxスケルトンのsci_gateway/c/ ディレクトリにあります
281 // 標準ヘッダ
282 #include "api_scilab.h"
283 #include "BOOL.h"
284 // 関数宣言
285 int sci_foo(char *fname, unsigned long fname_len)
286 {
287     // エラー管理変数
288     SciErr sciErr;
289     ////////// 変数宣言 //////////
290     int m1 = 0, n1 = 0;
291     int *piAddressVarOne = NULL;
292     double *matrixOfDouble = NULL;
293     double *newMatrixOfDouble = NULL;
294     int m2 = 0, n2 = 0;
295     int *piAddressVarTwo = NULL;
296     int *matrixOfBoolean = NULL;
297     int *newMatrixOfBoolean = NULL;
298     int i = 0;
299     ////////// 入力/出力引数の数を調べる //////////
300     /* --> [c, d] = foo(a, b) */
301     /* 入力引数が2のみであることを調べる */
302     /* 出力引数が2のみであることを調べる */
303     CheckInputArgument(pvApiCtx, 2, 2) ;
304     CheckOutputArgument(pvApiCtx, 2, 2) ;
305     ////////// 最初の入力引数 (double) を管理 //////////
306     /* 入力アドレスを取得 */
307     sciErr = getVarAddressFromPosition(pvApiCtx, 1, &piAddressVarOne);
308     if (sciErr.iErr)
309     {
310         printError(&sciErr, 0);
311         return 0;
312     }
313     /* 最初の入力引数が実数行列(複素数でない)であることを調べる */
314     if ( !isDoubleType(pvApiCtx, piAddressVarOne) ||  isVarComplex(pvApiCtx, piAddressVarOne) )
315     {
316         Scierror(999, "%s: Wrong type for input argument #%d: A real matrix expected.\n", fname, 1);
317         return 0;
318     }
319     /* 行列を取得 */
320     sciErr = getMatrixOfDouble(pvApiCtx, piAddressVarOne, &m1, &n1, &matrixOfDouble);
321     if (sciErr.iErr)
322     {
323         printError(&sciErr, 0);
324         return 0;
325     }
326     ////////// 2番目の入力引数を管理 (論理値) //////////
327     /* 入力アドレスを取得 */
328     sciErr = getVarAddressFromPosition(pvApiCtx, 2, &piAddressVarTwo);
329     if (sciErr.iErr)
330     {
331         printError(&sciErr, 0);
332         return 0;
333     }
334     if ( !isBooleanType(pvApiCtx, piAddressVarTwo) )
335     {
336         Scierror(999, "%s: Wrong type for input argument #%d: A boolean matrix expected.\n", fname, 2);
337         return 0;
338     }
339     /* 行列を取得 */
340     sciErr = getMatrixOfBoolean(pvApiCtx, piAddressVarTwo, &m2, &n2, &matrixOfBoolean);
341     if (sciErr.iErr)
342     {
343         printError(&sciErr, 0);
344         return 0;
345     }
346     ////////// 2つの入力引数の相関を確認 //////////
347     if ((m1 != m2) || (n1 != n2))
348     {
349         Scierror(999, "%s: Wrong size for input arguments: Same size expected.\n", fname, 1);
350         return 0;
351     }
352     newMatrixOfDouble = (double*)malloc(sizeof(double) * m1 * n1);
353     ////////// アプリケーションコード //////////
354     // ライブラリへのコールで置換することができます
355     for (i = 0; i < m1 * n1; i++)
356     {
357         /* 行列の各要素を2倍します */
358         newMatrixOfDouble[i] = matrixOfDouble[i] * 2;
359     }
360     newMatrixOfBoolean = (int*)malloc(sizeof(BOOL) * m2 * n2);
361     for (i = 0; i < m2 * n2; i++)
362     {
363         /* 行列の各要素について, 値を反転する */
364         newMatrixOfBoolean[i] = ((matrixOfBoolean[i] == TRUE) ? FALSE : TRUE);
365     }
366     ////////// 出力引数を作成 //////////
367     /* 関数の戻り値として行列を作成 */
368     sciErr = createMatrixOfDouble(pvApiCtx, nbInputArgument(pvApiCtx) + 1, m1, n1, newMatrixOfDouble);
369     free(newMatrixOfDouble); // データをScilabメモリにコピー
370     if (sciErr.iErr)
371     {
372         free(newMatrixOfBoolean); // エラーの際,完全にクリンナップします
373         printError(&sciErr, 0);
374         return 0;
375     }
376     /* 関数の戻り値として行列を作成 */
377     sciErr = createMatrixOfBoolean(pvApiCtx, nbInputArgument(pvApiCtx) + 2, m2, n2, newMatrixOfBoolean);
378     free(newMatrixOfBoolean); // データをScilabメモリにコピー
379     if (sciErr.iErr)
380     {
381         printError(&sciErr, 0);
382         return 0;
383     }
384     ////////// 出力引数をScilabエンジンに戻す //////////
385     AssignOutputVariable(pvApiCtx, 1) = nbInputArgument(pvApiCtx) + 1;
386     AssignOutputVariable(pvApiCtx, 2) = nbInputArgument(pvApiCtx) + 2;
387     return 0;
388 }
389       ]]>
390         </programlisting>
391         <para>
392             このコードを構築,Scilabにロードする際,
393             Scilabの動的リンク機能を使用します.
394             この組み込み処理はScilabに委任するため,
395             以下のコードはマルチプラットフォームです.
396             <programlisting role="scilab">
397                 <![CDATA[
398       files=["sci_foo.c"];
399       // TODO: WTF ?
400       WITHOUT_AUTO_PUTLHSVAR = %t;
401       ilib_build('build_lib',['foo','sci_foo'],files,[]);
402       exec loader.sce
403       [c, d] = foo([2,%pi], [%t, %f])
404       ]]>
405             </programlisting>
406         </para>
407         <para>
408             種々の確認が行われます:
409             <programlisting role="no-scilab-exec">
410                 <![CDATA[
411 -->[c, d] = foo(2, 2)
412                    !--error 999
413 foo: Wrong type for input argument #2: A boolean matrix expected.
414       ]]>
415             </programlisting>
416             <programlisting role="no-scilab-exec">
417                 <![CDATA[
418 -->[c, d] = foo([2,2], %t)
419                         !--error 999
420 foo: Wrong size for input arguments: Same size expected.
421       ]]>
422             </programlisting>
423             <programlisting role="no-scilab-exec">
424                 <![CDATA[
425 -->[a,b]=foo(2+%i,%t)
426                    !--error 999
427 foo: Wrong type for input argument #1: A real matrix expected.
428       ]]>
429             </programlisting>
430             <programlisting role="no-scilab-exec">
431                 <![CDATA[
432 -->[c, d] = foo([2,%pi], [%t, %f])
433  d  =
434   F T
435  c  =
436     4.    6.2831853
437       ]]>
438             </programlisting>
439         </para>
440     </refsection>
441 </refentry>