Massive indent of all codes:
[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-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