japanese translation updated.
[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             SciErrと呼ばれるC構造体を返すことに注意してください.
247         </para>
248         <para>
249             デフォルトでは, Scilab数値はC言語の<literal>double</literal>型に保存されます.
250         </para>
251         <para>
252             習慣的に,
253             ゲートウェイは,<literal>sci_gateway/c/</literal> (または <literal>/cpp/</literal>)
254             に保存され,<literal>sci_functionName.c</literal>という名前が付けられます.
255         </para>
256         <para>
257             <literal>pvApiCtx</literal> は,グローバルコンテキスト変数です.
258             これは,バージョン5系では使用されていませんが, Scilab バージョン 6で導入される
259             マルチスレッド機能を管理するために導入されています.
260         </para>
261     </refsection>
262     <refsection>
263         <title>実用的な例</title>
264         <para>以下のScilab関数を例として示します:</para>
265         <para>
266             <literal>[c,d] = foo(a,b)</literal>
267         </para>
268         <para>
269             <literal>a</literal>はdouble行列,<literal>a</literal>と同じ大きさの
270             <literal>b</literal>は論理値行列,
271             foo は<literal>a</literal>の各要素に2を乗じて,
272             <literal>c</literal>として返します.
273             また,bを要素毎に逆の論理値に変換して返します.
274         </para>
275         <para>
276             Scilabバイナリに含まれるツールボックススケルトンでサンプルを取得できます.
277             パスは
278             <literal>contrib/toolbox_skeleton/sci_gateway/c/sci_foo.c</literal>です.
279         </para>
280         <para>詳細な説明は以下の例のCコメント形式で提供されています.
281         </para>
282         <programlisting role="code_gateway">
283             <![CDATA[ 
284 // 完全なソースはtoolboxスケルトンのsci_gateway/c/ ディレクトリにあります
285
286 // 標準ヘッダ
287 #include "api_scilab.h"
288 #include "BOOL.h"
289 // 関数宣言
290 int sci_foo(char *fname, unsigned long fname_len)
291 {
292     // エラー管理変数
293     SciErr sciErr;
294     ////////// 変数宣言 //////////
295     int m1 = 0, n1 = 0;
296     int *piAddressVarOne = NULL;
297     double *matrixOfDouble = NULL;
298     double *newMatrixOfDouble = NULL;
299     int m2 = 0, n2 = 0;
300     int *piAddressVarTwo = NULL;
301     int *matrixOfBoolean = NULL;
302     int *newMatrixOfBoolean = NULL;
303     int i = 0;
304     ////////// 入力/出力引数の数を調べる //////////
305     /* --> [c, d] = foo(a, b) */
306     /* 入力引数が2のみであることを調べる */
307     /* 出力引数が2のみであることを調べる */
308     CheckInputArgument(pvApiCtx, 2, 2) ;
309     CheckOutputArgument(pvApiCtx, 2, 2) ;
310     ////////// 最初の入力引数 (double) を管理 //////////
311     /* 入力アドレスを取得 */
312     sciErr = getVarAddressFromPosition(pvApiCtx, 1, &piAddressVarOne);
313     if (sciErr.iErr)
314     {
315         printError(&sciErr, 0);
316         return 0;
317     }
318     /* 最初の入力引数が実数行列(複素数でない)であることを調べる */
319     if ( !isDoubleType(pvApiCtx, piAddressVarOne) ||  isVarComplex(pvApiCtx, piAddressVarOne) )
320     {
321         Scierror(999, "%s: Wrong type for input argument #%d: A real matrix expected.\n", fname, 1);
322         return 0;
323     }
324     /* 行列を取得 */
325     sciErr = getMatrixOfDouble(pvApiCtx, piAddressVarOne, &m1, &n1, &matrixOfDouble);
326     if (sciErr.iErr)
327     {
328         printError(&sciErr, 0);
329         return 0;
330     }
331     ////////// 2番目の入力引数を管理 (論理値) //////////
332     /* 入力アドレスを取得 */
333     sciErr = getVarAddressFromPosition(pvApiCtx, 2, &piAddressVarTwo);
334     if (sciErr.iErr)
335     {
336         printError(&sciErr, 0);
337         return 0;
338     }
339     if ( !isBooleanType(pvApiCtx, piAddressVarTwo) )
340     {
341         Scierror(999, "%s: Wrong type for input argument #%d: A boolean matrix expected.\n", fname, 2);
342         return 0;
343     }
344     /* 行列を取得 */
345     sciErr = getMatrixOfBoolean(pvApiCtx, piAddressVarTwo, &m2, &n2, &matrixOfBoolean);
346     if (sciErr.iErr)
347     {
348         printError(&sciErr, 0);
349         return 0;
350     }
351     ////////// 2つの入力引数の相関を確認 //////////
352     if ((m1 != m2) || (n1 != n2))
353     {
354         Scierror(999, "%s: Wrong size for input arguments: Same size expected.\n", fname, 1);
355         return 0;
356     }
357     newMatrixOfDouble = (double*)malloc(sizeof(double) * m1 * n1);
358     ////////// アプリケーションコード //////////
359     // ライブラリへのコールで置換することができます
360     for (i = 0; i < m1 * n1; i++)
361     {
362         /* 行列の各要素を2倍します */
363         newMatrixOfDouble[i] = matrixOfDouble[i] * 2;
364     }
365     newMatrixOfBoolean = (int*)malloc(sizeof(BOOL) * m2 * n2);
366     for (i = 0; i < m2 * n2; i++)
367     {
368         /* 行列の各要素について, 値を反転する */
369         newMatrixOfBoolean[i] = ((matrixOfBoolean[i] == TRUE) ? FALSE : TRUE);
370     }
371     ////////// 出力引数を作成 //////////
372     /* 関数の戻り値として行列を作成 */
373     sciErr = createMatrixOfDouble(pvApiCtx, nbInputArgument(pvApiCtx) + 1, m1, n1, newMatrixOfDouble);
374     free(newMatrixOfDouble); // データをScilabメモリにコピー
375     if (sciErr.iErr)
376     {
377         free(newMatrixOfBoolean); // エラーの際,完全にクリンナップします
378         printError(&sciErr, 0);
379         return 0;
380     }
381     /* 関数の戻り値として行列を作成 */
382     sciErr = createMatrixOfBoolean(pvApiCtx, nbInputArgument(pvApiCtx) + 2, m2, n2, newMatrixOfBoolean);
383     free(newMatrixOfBoolean); // データをScilabメモリにコピー
384     if (sciErr.iErr)
385     {
386         printError(&sciErr, 0);
387         return 0;
388     }
389     ////////// 出力引数をScilabエンジンに戻す //////////
390     AssignOutputVariable(pvApiCtx, 1) = nbInputArgument(pvApiCtx) + 1;
391     AssignOutputVariable(pvApiCtx, 2) = nbInputArgument(pvApiCtx) + 2;
392     return 0;
393 }
394       ]]>
395         </programlisting>
396         <para>
397             このコードを構築,Scilabにロードする際,Scilabの動的リンク機能を使用します.
398             この組み込み処理はScilabに委任するため,以下のコードはマルチプラットフォーム対応です.
399             <programlisting role="scilab">
400                 <![CDATA[
401       files=["sci_foo.c"];
402       // TODO: WTF ?
403       WITHOUT_AUTO_PUTLHSVAR = %t;
404       ilib_build('build_lib',['foo','sci_foo'],files,[]);
405       exec loader.sce
406       [c, d] = foo([2,%pi], [%t, %f])
407       ]]>
408             </programlisting>
409         </para>
410         <para>
411             種々の確認が行われます:
412             <programlisting role="no-scilab-exec">
413                 <![CDATA[
414 -->[c, d] = foo(2, 2)
415                    !--error 999
416 foo: Wrong type for input argument #2: A boolean matrix expected.
417       ]]>
418             </programlisting>
419             <programlisting role="no-scilab-exec">
420                 <![CDATA[
421 -->[c, d] = foo([2,2], %t)
422                         !--error 999
423 foo: Wrong size for input arguments: Same size expected.
424       ]]>
425             </programlisting>
426             <programlisting role="no-scilab-exec">
427                 <![CDATA[
428 -->[a,b]=foo(2+%i,%t)
429                    !--error 999
430 foo: Wrong type for input argument #1: A real matrix expected.
431       ]]>
432             </programlisting>
433             <programlisting role="no-scilab-exec">
434                 <![CDATA[
435 -->[c, d] = foo([2,%pi], [%t, %f])
436  d  =
437
438   F T
439  c  =
440
441     4.    6.2831853
442       ]]>
443             </programlisting>
444         </para>
445     </refsection>
446 </refentry>