Also update the URL to the CeCILL license. Thanks to Paul for noticing that
[scilab.git] / scilab / modules / api_scilab / help / ja_JP / getting_started.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2
3 <!--
4 * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
5 * Copyright (C) 2012 - Scilab Enterprises - Sylvestre LEDRU
6 *
7 * This file must be used under the terms of the CeCILL.
8 * This source file is licensed as described in the file COPYING, which
9 * you should have received as part of this distribution.  The terms
10 * are also available at
11 * http://www.cecill.info/licences/Licence_CeCILL_V2.1-en.txt
12 *
13 -->
14
15 <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">
16     
17     <refnamediv>
18         
19         <refname>API_Scilab入門</refname>
20         
21         <refpurpose>
22             
23             C, C++ またはfortranコードを新しい関数としてScilabエンジンに読み込む方法
24             
25         </refpurpose>
26         
27     </refnamediv>
28     
29     <refsection>
30         
31         <title>説明</title>
32         
33         <para>
34             
35             <link linkend="api_scilab">api_scilabプレゼンテーション</link>
36             
37             で説明されたように,
38             
39             ScilabはC, C++またはFortranコード(ソースまたはライブラリ)で言語を
40             
41             拡張するためのAPIを提供します.
42             
43         </para>
44         
45         <para>
46             
47             Scilabエンジンとアプリケーションコードの間のリンクは
48             
49             <literal>gateway</literal>と呼ばれます.
50             
51         </para>
52         
53         <para>
54             
55             多くの場合, 処理は常に同じで,以下のようになります:
56             
57             <orderedlist>
58                 
59                 <listitem>
60                     
61                     <para>
62                         
63                         ユーザに指定された(入力及び出力)引数の数を調べます.
64                         
65                     </para>
66                     
67                     <para>
68                         
69                         例えば,関数<literal>foo(x)</literal>が <literal>foo()</literal> または <literal>foo(2,3)</literal>のようにコールされ, ユーザが答を得ます.
70                         
71                     </para>
72                     
73                     <para>
74                         
75                         詳細: <link linkend="CheckInputArgument">CheckInputArgument</link> および <link linkend="CheckOutputArgument">CheckOutputArgument</link>
76                         
77                     </para>
78                     
79                 </listitem>
80                 
81                 <listitem>
82                     
83                     <para>入力引数の管理</para>
84                     
85                     <para>
86                         
87                         複数の処理を行います:
88                         
89                         <orderedlist inheritnum="inherit">
90                             
91                             <listitem>
92                                 
93                                 <para>入力引数Xの変数アドレスを取得します</para>
94                                 
95                                 <para>
96                                     
97                                     関数
98                                     
99                                     <literal>
100                                         
101                                         SciErr <link linkend="Common_getvaraddr_API">getVarAddressFromPosition</link>(void* context, int positionOfTheVariable, int** address)
102                                         
103                                     </literal>
104                                     
105                                 </para>
106                                 
107                             </listitem>
108                             
109                             <listitem>
110                                 
111                                 <para>変数の型を調べます: doubleの行列 (複素数または複素数以外), 文字列
112                                     
113                                     , 等
114                                 </para>
115                                 
116                                 <para>
117                                     
118                                     <literal>
119                                         
120                                         SciErr <link linkend="Common_getvartype_API">getVarType</link>(void* context, int* positionOfTheVariable, int* Type)
121                                         
122                                     </literal>
123                                     
124                                 </para>
125                                 
126                                 <para>
127                                     
128                                     他の関数も提供されています:
129                                     
130                                     <itemizedlist>
131                                         
132                                         <listitem>
133                                             
134                                             <para>
135                                                 
136                                                 <literal>int isBooleanType(void* context, int* address)</literal>
137                                                 
138                                             </para>
139                                             
140                                         </listitem>
141                                         
142                                         <listitem>
143                                             
144                                             <para>
145                                                 
146                                                 <literal>int isBooleanSparseType(void* context, int* address)</literal>
147                                                 
148                                             </para>
149                                             
150                                         </listitem>
151                                         
152                                         <listitem>
153                                             
154                                             <para>
155                                                 
156                                                 <literal>int isDoubleType(void* context, int* address)</literal>
157                                                 
158                                             </para>
159                                             
160                                         </listitem>
161                                         
162                                         <listitem>
163                                             
164                                             <para>
165                                                 
166                                                 <literal>int isIntegerType(void* context, int* address)</literal>
167                                                 
168                                             </para>
169                                             
170                                         </listitem>
171                                         
172                                         <listitem>
173                                             
174                                             <para>
175                                                 
176                                                 <literal>int isPointerType(void* context, int* address)</literal>
177                                                 
178                                             </para>
179                                             
180                                         </listitem>
181                                         
182                                         <listitem>
183                                             
184                                             <para>
185                                                 
186                                                 <literal>int isPolyType(void* context, int* address)</literal>
187                                                 
188                                             </para>
189                                             
190                                         </listitem>
191                                         
192                                         <listitem>
193                                             
194                                             <para>
195                                                 
196                                                 <literal>int isSparseType(void* context, int* address)</literal>
197                                                 
198                                             </para>
199                                             
200                                         </listitem>
201                                         
202                                         <listitem>
203                                             
204                                             <para>
205                                                 
206                                                 <literal>int isStringType(void* context, int* address)</literal>
207                                                 
208                                             </para>
209                                             
210                                         </listitem>
211                                         
212                                         <listitem>
213                                             
214                                             <para>
215                                                 
216                                                 <literal>int isListType(void* context, int* address)</literal>
217                                                 
218                                             </para>
219                                             
220                                         </listitem>
221                                         
222                                         <listitem>
223                                             
224                                             <para>
225                                                 
226                                                 <literal>int isTListType(void* context, int* address)</literal>
227                                                 
228                                             </para>
229                                             
230                                         </listitem>
231                                         
232                                         <listitem>
233                                             
234                                             <para>
235                                                 
236                                                 <literal>int isMListType(void* context, int* address)</literal>
237                                                 
238                                             </para>
239                                             
240                                         </listitem>
241                                         
242                                     </itemizedlist>
243                                     
244                                 </para>
245                                 
246                             </listitem>
247                             
248                             <listitem>
249                                 
250                                 <para>
251                                     
252                                     関連する場合, 入力引数かどうかを確認します.
253                                 </para>
254                                 
255                                 <para>
256                                     
257                                     <literal>
258                                         
259                                         int <link linkend="Common_iscomplex_API">isVarComplex</link>(void* context, int* address)
260                                         
261                                     </literal>
262                                     
263                                 </para>
264                                 
265                             </listitem>
266                             
267                             <listitem>
268                                 
269                                 <para>
270                                     
271                                     整数を処理する場合,さらに整数の精度も確認します
272                                 </para>
273                                 
274                                 <para>
275                                     
276                                     <literal>
277                                         
278                                         SciErr <link linkend="int_getmatrixofintegerprecision_API">getMatrixOfIntegerPrecision</link>(void* context, int* address, int* precision)
279                                         
280                                     </literal>
281                                     
282                                 </para>
283                                 
284                             </listitem>
285                             
286                             <listitem>
287                                 
288                                 <para>変数の大きさを確認します: 正方行列, スカラー, 等</para>
289                                 
290                                 <para>
291                                     
292                                     大きさに関する情報を取得する際にも
293                                     
294                                     実際のデータを取得する際に使用するものと同じ関数を使用します.
295                                     
296                                     例えば, double の行列の場合 関数コール
297                                     
298                                     <literal>
299                                         
300                                         SciErr <link linkend="Double_management_reading_API">getMatrixOfDouble</link>(void* context, int* address, int* nbRows, int* nbCols, double** theActualData)
301                                         
302                                     </literal>
303                                     
304                                     により行列の次元を取得できます.
305                                     
306                                 </para>
307                                 
308                                 <para>ほぼ全てのScilabデータ型にはこのような処理を行うための
309                                     
310                                     同様なC関数があります.
311                                     
312                                 </para>
313                                 
314                             </listitem>
315                             
316                             <listitem>
317                                 
318                                 <para>
319                                     
320                                     その他, 特定の値かどうかを調べたり, 最初と2番目の入力引数の間の整合性を
321                                     
322                                     確認したりすること等も可能です.
323                                     
324                                 </para>
325                                 
326                             </listitem>
327                             
328                             <listitem>
329                                 
330                                 <para>データ変換 (オプション).</para>
331                                 
332                                 <para>
333                                     
334                                     使用するコードまたはライブラリによっては,
335                                     
336                                     いくつかの変換をデータに適用することができます.
337                                     
338                                     古典的な例は行列の記録を列形式から線形式に変換するものです.
339                                     
340                                 </para>
341                                 
342                                 <para>
343                                     
344                                     通常,このようにすると性能が低下することに注意してください.
345                                     
346                                 </para>
347                                 
348                             </listitem>
349                             
350                         </orderedlist>
351                         
352                     </para>
353                     
354                 </listitem>
355                 
356                 <listitem>
357                     
358                     <para>アプリケーションコード</para>
359                     
360                     <para>
361                         
362                         確認とデータ取得を行った後,実際の主コードをコールできます.
363                         
364                         実際の情報処理(処理, データ変換, 等)をここで実行します.
365                         
366                     </para>
367                     
368                     <para>
369                         
370                         これは,
371                         
372                         <literal>src/c</literal>, <literal>src/cpp</literal> または
373                         
374                         <literal>src/fortran</literal>に保存,構築した
375                         
376                         サードパーティのコードにより行いますが,
377                         
378                         ライブラリ形式とすることも可能です.
379                         
380                         あらゆるライブラリをScilabにリンクすることができます.
381                         
382                     </para>
383                     
384                 </listitem>
385                 
386                 <listitem>
387                     
388                     <para>Scilabエンジンの出力引数を作成する</para>
389                     
390                     <para>通常,アプリケーションコードの実行後,
391                         
392                         何らかのデータをScilabインタプリタから戻します.
393                         
394                     </para>
395                     
396                     <para>
397                         
398                         例えば, doubleの行列をScilabエンジンに保存する場合,C関数
399                         
400                         <literal>
401                             
402                             SciErr <link linkend="Double_management_writing_API">createMatrixOfDouble</link>(void* context, int position, int nbRows, int nbCols, const double* matrixOfDouble)
403                             
404                         </literal>
405                         
406                         をコールします.
407                         
408                     </para>
409                     
410                     <para>
411                         
412                         通常,位置は
413                         
414                         <literal>nbInputArgument(pvApiCtx) + X</literal>により取得できます. 
415                         
416                         <literal>X</literal> が返す出力引数の位置となります.
417                         
418                         例えば, 関数プロファイル
419                         
420                         <literal>[a, b, c] = foo();</literal> 
421                         
422                         <literal>nbInputArgument(pvApiCtx) + 3</literal> は
423                         
424                         変数<literal>c</literal>となります.
425                         
426                     </para>
427                     
428                     <para>
429                         
430                         作成できる次元はゲートウェイの制約を受けることに注意してください.
431                         
432                     </para>
433                     
434                     <para>
435                         
436                         ほぼ全てのScilabデータ型はこのような処理を行う同様なC関数を有します.
437                         
438                     </para>
439                     
440                 </listitem>
441                 
442                 <listitem>
443                     
444                     <para>Scilabエンジンに出力引数を返す</para>
445                     
446                     <para>以下, タスク4で, 作成した変数を返します.</para>
447                     
448                     <para>
449                         
450                         <literal>a</literal>を返す
451                         
452                         前の例 <literal>[a, b, c] = foo();</literal>の場合,
453                         
454                         以下の宣言を行います: <literal>AssignOutputVariable(pvApiCtx, 1) = nbInputArgument(pvApiCtx) + 1;</literal>
455                         
456                     </para>
457                     
458                     <para>
459                         
460                         Scilabエンジンに新しい変数をコミットするには,
461                         
462                         関数
463                         
464                         <link linkend="ReturnArguments">ReturnArguments(pvApiCtx)</link> をコールします.
465                         
466                     </para>
467                     
468                 </listitem>
469                 
470             </orderedlist>
471             
472             
473             
474         </para>
475         
476         <para>
477             
478             API_Scilab関数
479             
480             
481             
482             Note that almost all the API_Scilab functions returns a C structure called SciErr which contains many information about the error.
483         </para>
484         
485         <para>
486             
487             By default, Scilab numerical values are stored with the C type <literal>double</literal>.
488             
489         </para>
490         
491         <para>
492             
493             As convention, gateways are stored in <literal>sci_gateway/c/</literal> (or <literal>/cpp/</literal>) and are called <literal>sci_functionName.c</literal>.
494             
495         </para>
496         
497         <para>
498             
499             <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.
500             
501         </para>
502         
503     </refsection>
504     
505     <refsection>
506         
507         <title>現実的な例</title>
508         
509         <para>以下のScilab関数を例として示します:</para>
510         
511         <para>
512             
513             <literal>[c,d] = foo(a,b)</literal>
514             
515         </para>
516         
517         <para>
518             
519             <literal>a</literal>はdouble行列,<literal>a</literal>と同じ大きさの
520             
521             <literal>b</literal>は論理値行列,
522             
523             foo は<literal>a</literal>の各要素に2を乗じて,
524             
525             <literal>c</literal>として返します.
526             
527             また,bを要素毎に逆の論理値に変換して返します.
528             
529         </para>
530         
531         <para>
532             
533             Scilabバイナリに含まれるツールボックススケルトンでサンプルを取得できます.
534             
535             パスは
536             
537             <literal>contrib/toolbox_skeleton/sci_gateway/c/sci_foo.c</literal>です.
538             
539         </para>
540         
541         <para>詳細な説明は以下の例のCコメント形式で提供されています.
542             
543         </para>
544         
545         <programlisting role="code_gateway">
546             
547             <![CDATA[ 
548 // 完全なソースはtoolboxスケルトンのsci_gateway/c/ ディレクトリにあります
549
550 // 標準ヘッダ
551 #include "api_scilab.h"
552 #include "BOOL.h"
553
554 // 関数宣言
555 int sci_foo(char *fname, unsigned long fname_len)
556 {
557     // エラー管理変数
558     SciErr sciErr;
559
560     ////////// 変数宣言 //////////
561     int m1 = 0, n1 = 0;
562     int *piAddressVarOne = NULL;
563     double *matrixOfDouble = NULL;
564     double *newMatrixOfDouble = NULL;
565
566     int m2 = 0, n2 = 0;
567     int *piAddressVarTwo = NULL;
568     int *matrixOfBoolean = NULL;
569     int *newMatrixOfBoolean = NULL;
570     int i = 0;
571
572
573     ////////// 入力/出力引数の数を調べる //////////
574     /* --> [c, d] = foo(a, b) */
575     /* 入力引数が2のみであることを調べる */
576     /* 出力引数が2のみであることを調べる */
577     CheckInputArgument(pvApiCtx, 2, 2) ;
578     CheckOutputArgument(pvApiCtx, 2, 2) ;
579
580
581     ////////// 最初の入力引数 (double) を管理 //////////
582     /* 入力アドレスを取得 */
583     sciErr = getVarAddressFromPosition(pvApiCtx, 1, &piAddressVarOne);
584     if (sciErr.iErr)
585     {
586         printError(&sciErr, 0);
587         return 0;
588     }
589
590     /* 最初の入力引数が実数行列(複素数でない)であることを調べる */
591     if ( !isDoubleType(pvApiCtx, piAddressVarOne) ||  isVarComplex(pvApiCtx, piAddressVarOne) )
592     {
593         Scierror(999, "%s: Wrong type for input argument #%d: A real matrix expected.\n", fname, 1);
594         return 0;
595     }
596
597     /* 行列を取得 */
598     sciErr = getMatrixOfDouble(pvApiCtx, piAddressVarOne, &m1, &n1, &matrixOfDouble);
599     if (sciErr.iErr)
600     {
601         printError(&sciErr, 0);
602         return 0;
603     }
604
605     ////////// 2番目の入力引数を管理 (論理値) //////////
606
607     /* 入力アドレスを取得 */
608     sciErr = getVarAddressFromPosition(pvApiCtx, 2, &piAddressVarTwo);
609     if (sciErr.iErr)
610     {
611         printError(&sciErr, 0);
612         return 0;
613     }
614
615     if ( !isBooleanType(pvApiCtx, piAddressVarTwo) )
616     {
617         Scierror(999, "%s: Wrong type for input argument #%d: A boolean matrix expected.\n", fname, 2);
618         return 0;
619     }
620
621     /* 行列を取得 */
622     sciErr = getMatrixOfBoolean(pvApiCtx, piAddressVarTwo, &m2, &n2, &matrixOfBoolean);
623     if (sciErr.iErr)
624     {
625         printError(&sciErr, 0);
626         return 0;
627     }
628
629     ////////// 2つの入力引数の相関を確認 //////////
630
631     if ((m1 != m2) || (n1 != n2))
632     {
633         Scierror(999, "%s: Wrong size for input arguments: Same size expected.\n", fname, 1);
634         return 0;
635     }
636
637
638     newMatrixOfDouble = (double*)malloc(sizeof(double) * m1 * n1);
639     ////////// アプリケーションコード //////////
640     // ライブラリへのコールで置換することができます
641
642     for (i = 0; i < m1 * n1; i++)
643     {
644         /* 行列の各要素を2倍します */
645         newMatrixOfDouble[i] = matrixOfDouble[i] * 2;
646     }
647
648     newMatrixOfBoolean = (int*)malloc(sizeof(BOOL) * m2 * n2);
649     for (i = 0; i < m2 * n2; i++)
650     {
651         /* 行列の各要素について, 値を反転する */
652         newMatrixOfBoolean[i] = ((matrixOfBoolean[i] == TRUE) ? FALSE : TRUE);
653     }
654
655     ////////// 出力引数を作成 //////////
656
657     /* 関数の戻り値として行列を作成 */
658     sciErr = createMatrixOfDouble(pvApiCtx, nbInputArgument(pvApiCtx) + 1, m1, n1, newMatrixOfDouble);
659     free(newMatrixOfDouble); // データをScilabメモリにコピー
660     if (sciErr.iErr)
661     {
662         free(newMatrixOfBoolean); // エラーの際,完全にクリンナップします
663         printError(&sciErr, 0);
664         return 0;
665     }
666
667     /* 関数の戻り値として行列を作成 */
668     sciErr = createMatrixOfBoolean(pvApiCtx, nbInputArgument(pvApiCtx) + 2, m2, n2, newMatrixOfBoolean);
669     free(newMatrixOfBoolean); // データをScilabメモリにコピー
670     if (sciErr.iErr)
671     {
672         printError(&sciErr, 0);
673         return 0;
674     }
675
676
677     ////////// 出力引数をScilabエンジンに戻す //////////
678
679     AssignOutputVariable(pvApiCtx, 1) = nbInputArgument(pvApiCtx) + 1;
680     AssignOutputVariable(pvApiCtx, 2) = nbInputArgument(pvApiCtx) + 2;
681
682     return 0;
683 }
684       ]]>
685             
686         </programlisting>
687         
688         <para>
689             
690             このコードを構築,Scilabにロードする際,
691             
692             Scilabの動的リンク機能を使用します.
693             
694             この組み込み処理はScilabに委任するため,
695             
696             以下のコードはマルチプラットフォームです.
697             
698             <programlisting role="scilab">
699                 
700                 <![CDATA[
701       files=["sci_foo.c"];
702       // TODO: WTF ?
703       WITHOUT_AUTO_PUTLHSVAR = %t;
704       ilib_build('build_lib',['foo','sci_foo'],files,[]);
705       exec loader.sce
706       [c, d] = foo([2,%pi], [%t, %f])
707       ]]>
708                 
709             </programlisting>
710             
711         </para>
712         
713         <para>
714             
715             種々の確認が行われます:
716             
717             <programlisting role="no-scilab-exec">
718                 
719                 <![CDATA[
720 -->[c, d] = foo(2, 2)
721                    !--error 999
722 foo: Wrong type for input argument #2: A boolean matrix expected.
723       ]]>
724                 
725             </programlisting>
726             
727             <programlisting role="no-scilab-exec">
728                 
729                 <![CDATA[
730 -->[c, d] = foo([2,2], %t)
731                         !--error 999
732 foo: Wrong size for input arguments: Same size expected.
733       ]]>
734                 
735             </programlisting>
736             
737             <programlisting role="no-scilab-exec">
738                 
739                 <![CDATA[
740 -->[a,b]=foo(2+%i,%t)
741                    !--error 999
742 foo: Wrong type for input argument #1: A real matrix expected.
743       ]]>
744                 
745             </programlisting>
746             
747             <programlisting role="no-scilab-exec">
748                 
749                 <![CDATA[
750 -->[c, d] = foo([2,%pi], [%t, %f])
751  d  =
752
753   F T
754  c  =
755
756     4.    6.2831853
757       ]]>
758                 
759             </programlisting>
760             
761         </para>
762         
763     </refsection>
764     
765 </refentry>
766