japanese translation updated.
[scilab.git] / scilab / modules / api_scilab / help / ja_JP / getting_started.xml
index bb8d948..0a3b0f5 100644 (file)
@@ -1,5 +1,4 @@
 <?xml version="1.0" encoding="UTF-8"?>
-
 <!--
 * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
 * Copyright (C) 2012 - Scilab Enterprises - Sylvestre LEDRU
 * This source file is licensed as described in the file COPYING, which
 * you should have received as part of this distribution.  The terms
 * are also available at
-* http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt
+* http://www.cecill.info/licences/Licence_CeCILL_V2.1-en.txt
 *
 -->
-
 <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">
-    
     <refnamediv>
-        
         <refname>API_Scilab入門</refname>
-        
         <refpurpose>
-            
             C, C++ またはfortranコードを新しい関数としてScilabエンジンに読み込む方法
-            
         </refpurpose>
-        
     </refnamediv>
-    
     <refsection>
-        
         <title>説明</title>
-        
         <para>
-            
             <link linkend="api_scilab">api_scilabプレゼンテーション</link>
-            
             で説明されたように,
-            
             ScilabはC, C++またはFortranコード(ソースまたはライブラリ)で言語を
-            
             拡張するためのAPIを提供します.
-            
         </para>
-        
         <para>
-            
             Scilabエンジンとアプリケーションコードの間のリンクは
-            
             <literal>gateway</literal>と呼ばれます.
-            
         </para>
-        
         <para>
-            
             多くの場合, 処理は常に同じで,以下のようになります:
-            
             <orderedlist>
-                
                 <listitem>
-                    
                     <para>
-                        
                         ユーザに指定された(入力及び出力)引数の数を調べます.
-                        
                     </para>
-                    
                     <para>
-                        
                         例えば,関数<literal>foo(x)</literal>が <literal>foo()</literal> または <literal>foo(2,3)</literal>のようにコールされ, ユーザが答を得ます.
-                        
                     </para>
-                    
                     <para>
-                        
                         詳細: <link linkend="CheckInputArgument">CheckInputArgument</link> および <link linkend="CheckOutputArgument">CheckOutputArgument</link>
-                        
                     </para>
-                    
                 </listitem>
-                
                 <listitem>
-                    
                     <para>入力引数の管理</para>
-                    
                     <para>
-                        
                         複数の処理を行います:
-                        
                         <orderedlist inheritnum="inherit">
-                            
                             <listitem>
-                                
                                 <para>入力引数Xの変数アドレスを取得します</para>
-                                
                                 <para>
-                                    
                                     関数
-                                    
                                     <literal>
-                                        
                                         SciErr <link linkend="Common_getvaraddr_API">getVarAddressFromPosition</link>(void* context, int positionOfTheVariable, int** address)
-                                        
                                     </literal>
-                                    
                                 </para>
-                                
                             </listitem>
-                            
                             <listitem>
-                                
                                 <para>変数の型を調べます: doubleの行列 (複素数または複素数以外), 文字列
-                                    
                                     , 等
                                 </para>
-                                
                                 <para>
-                                    
                                     <literal>
-                                        
                                         SciErr <link linkend="Common_getvartype_API">getVarType</link>(void* context, int* positionOfTheVariable, int* Type)
-                                        
                                     </literal>
-                                    
                                 </para>
-                                
                                 <para>
-                                    
                                     他の関数も提供されています:
-                                    
                                     <itemizedlist>
-                                        
                                         <listitem>
-                                            
                                             <para>
-                                                
                                                 <literal>int isBooleanType(void* context, int* address)</literal>
-                                                
                                             </para>
-                                            
                                         </listitem>
-                                        
                                         <listitem>
-                                            
                                             <para>
-                                                
                                                 <literal>int isBooleanSparseType(void* context, int* address)</literal>
-                                                
                                             </para>
-                                            
                                         </listitem>
-                                        
                                         <listitem>
-                                            
                                             <para>
-                                                
                                                 <literal>int isDoubleType(void* context, int* address)</literal>
-                                                
                                             </para>
-                                            
                                         </listitem>
-                                        
                                         <listitem>
-                                            
                                             <para>
-                                                
                                                 <literal>int isIntegerType(void* context, int* address)</literal>
-                                                
                                             </para>
-                                            
                                         </listitem>
-                                        
                                         <listitem>
-                                            
                                             <para>
-                                                
                                                 <literal>int isPointerType(void* context, int* address)</literal>
-                                                
                                             </para>
-                                            
                                         </listitem>
-                                        
                                         <listitem>
-                                            
                                             <para>
-                                                
                                                 <literal>int isPolyType(void* context, int* address)</literal>
-                                                
                                             </para>
-                                            
                                         </listitem>
-                                        
                                         <listitem>
-                                            
                                             <para>
-                                                
                                                 <literal>int isSparseType(void* context, int* address)</literal>
-                                                
                                             </para>
-                                            
                                         </listitem>
-                                        
                                         <listitem>
-                                            
                                             <para>
-                                                
                                                 <literal>int isStringType(void* context, int* address)</literal>
-                                                
                                             </para>
-                                            
                                         </listitem>
-                                        
                                         <listitem>
-                                            
                                             <para>
-                                                
                                                 <literal>int isListType(void* context, int* address)</literal>
-                                                
                                             </para>
-                                            
                                         </listitem>
-                                        
                                         <listitem>
-                                            
                                             <para>
-                                                
                                                 <literal>int isTListType(void* context, int* address)</literal>
-                                                
                                             </para>
-                                            
                                         </listitem>
-                                        
                                         <listitem>
-                                            
                                             <para>
-                                                
                                                 <literal>int isMListType(void* context, int* address)</literal>
-                                                
                                             </para>
-                                            
                                         </listitem>
-                                        
                                     </itemizedlist>
-                                    
                                 </para>
-                                
                             </listitem>
-                            
                             <listitem>
-                                
                                 <para>
-                                    
                                     関連する場合, 入力引数かどうかを確認します.
                                 </para>
-                                
                                 <para>
-                                    
                                     <literal>
-                                        
                                         int <link linkend="Common_iscomplex_API">isVarComplex</link>(void* context, int* address)
-                                        
                                     </literal>
-                                    
                                 </para>
-                                
                             </listitem>
-                            
                             <listitem>
-                                
                                 <para>
-                                    
                                     整数を処理する場合,さらに整数の精度も確認します
                                 </para>
-                                
                                 <para>
-                                    
                                     <literal>
-                                        
                                         SciErr <link linkend="int_getmatrixofintegerprecision_API">getMatrixOfIntegerPrecision</link>(void* context, int* address, int* precision)
-                                        
                                     </literal>
-                                    
                                 </para>
-                                
                             </listitem>
-                            
                             <listitem>
-                                
                                 <para>変数の大きさを確認します: 正方行列, スカラー, 等</para>
-                                
                                 <para>
-                                    
                                     大きさに関する情報を取得する際にも
-                                    
                                     実際のデータを取得する際に使用するものと同じ関数を使用します.
-                                    
                                     例えば, double の行列の場合 関数コール
-                                    
                                     <literal>
-                                        
                                         SciErr <link linkend="Double_management_reading_API">getMatrixOfDouble</link>(void* context, int* address, int* nbRows, int* nbCols, double** theActualData)
-                                        
                                     </literal>
-                                    
                                     により行列の次元を取得できます.
-                                    
                                 </para>
-                                
                                 <para>ほぼ全てのScilabデータ型にはこのような処理を行うための
-                                    
                                     同様なC関数があります.
-                                    
                                 </para>
-                                
                             </listitem>
-                            
                             <listitem>
-                                
                                 <para>
-                                    
                                     その他, 特定の値かどうかを調べたり, 最初と2番目の入力引数の間の整合性を
-                                    
                                     確認したりすること等も可能です.
-                                    
                                 </para>
-                                
                             </listitem>
-                            
                             <listitem>
-                                
                                 <para>データ変換 (オプション).</para>
-                                
                                 <para>
-                                    
                                     使用するコードまたはライブラリによっては,
-                                    
                                     いくつかの変換をデータに適用することができます.
-                                    
                                     古典的な例は行列の記録を列形式から線形式に変換するものです.
-                                    
                                 </para>
-                                
                                 <para>
-                                    
                                     通常,このようにすると性能が低下することに注意してください.
-                                    
                                 </para>
-                                
                             </listitem>
-                            
                         </orderedlist>
-                        
                     </para>
-                    
                 </listitem>
-                
                 <listitem>
-                    
                     <para>アプリケーションコード</para>
-                    
                     <para>
-                        
                         確認とデータ取得を行った後,実際の主コードをコールできます.
-                        
                         実際の情報処理(処理, データ変換, 等)をここで実行します.
-                        
                     </para>
-                    
                     <para>
-                        
                         これは,
-                        
                         <literal>src/c</literal>, <literal>src/cpp</literal> または
-                        
                         <literal>src/fortran</literal>に保存,構築した
-                        
                         サードパーティのコードにより行いますが,
-                        
                         ライブラリ形式とすることも可能です.
-                        
                         あらゆるライブラリをScilabにリンクすることができます.
-                        
                     </para>
-                    
                 </listitem>
-                
                 <listitem>
-                    
                     <para>Scilabエンジンの出力引数を作成する</para>
-                    
                     <para>通常,アプリケーションコードの実行後,
-                        
                         何らかのデータをScilabインタプリタから戻します.
-                        
                     </para>
-                    
                     <para>
-                        
                         例えば, doubleの行列をScilabエンジンに保存する場合,C関数
-                        
                         <literal>
-                            
                             SciErr <link linkend="Double_management_writing_API">createMatrixOfDouble</link>(void* context, int position, int nbRows, int nbCols, const double* matrixOfDouble)
-                            
                         </literal>
-                        
                         をコールします.
-                        
                     </para>
-                    
                     <para>
-                        
                         通常,位置は
-                        
                         <literal>nbInputArgument(pvApiCtx) + X</literal>により取得できます. 
-                        
                         <literal>X</literal> が返す出力引数の位置となります.
-                        
                         例えば, 関数プロファイル
-                        
                         <literal>[a, b, c] = foo();</literal> 
-                        
                         <literal>nbInputArgument(pvApiCtx) + 3</literal> は
-                        
                         変数<literal>c</literal>となります.
-                        
                     </para>
-                    
                     <para>
-                        
                         作成できる次元はゲートウェイの制約を受けることに注意してください.
-                        
                     </para>
-                    
                     <para>
-                        
                         ほぼ全てのScilabデータ型はこのような処理を行う同様なC関数を有します.
-                        
                     </para>
-                    
                 </listitem>
-                
                 <listitem>
-                    
                     <para>Scilabエンジンに出力引数を返す</para>
-                    
                     <para>以下, タスク4で, 作成した変数を返します.</para>
-                    
                     <para>
-                        
                         <literal>a</literal>を返す
-                        
                         前の例 <literal>[a, b, c] = foo();</literal>の場合,
-                        
                         以下の宣言を行います: <literal>AssignOutputVariable(pvApiCtx, 1) = nbInputArgument(pvApiCtx) + 1;</literal>
-                        
                     </para>
-                    
                     <para>
-                        
                         Scilabエンジンに新しい変数をコミットするには,
-                        
                         関数
-                        
                         <link linkend="ReturnArguments">ReturnArguments(pvApiCtx)</link> をコールします.
-                        
                     </para>
-                    
                 </listitem>
-                
             </orderedlist>
-            
-            
-            
         </para>
-        
         <para>
-            
-            API_Scilab関数
-            
-            
-            
-            Note that almost all the API_Scilab functions returns a C structure called SciErr which contains many information about the error.
+            ほぼ全てのAPI_Scilab関数がエラーに関する多くの情報を含む
+            SciErrと呼ばれるC構造体を返すことに注意してください.
         </para>
-        
         <para>
-            
-            By default, Scilab numerical values are stored with the C type <literal>double</literal>.
-            
+            デフォルトでは, Scilab数値はC言語の<literal>double</literal>型に保存されます.
         </para>
-        
         <para>
-            
-            As convention, gateways are stored in <literal>sci_gateway/c/</literal> (or <literal>/cpp/</literal>) and are called <literal>sci_functionName.c</literal>.
-            
+            習慣的に,
+            ゲートウェイは,<literal>sci_gateway/c/</literal> (または <literal>/cpp/</literal>)
+            に保存され,<literal>sci_functionName.c</literal>という名前が付けられます.
         </para>
-        
         <para>
-            
-            <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.
-            
+            <literal>pvApiCtx</literal> は,グローバルコンテキスト変数です.
+            これは,バージョン5系では使用されていませんが, Scilab バージョン 6で導入される
+            マルチスレッド機能を管理するために導入されています.
         </para>
-        
     </refsection>
-    
     <refsection>
-        
-        <title>現実的な例</title>
-        
+        <title>実用的な例</title>
         <para>以下のScilab関数を例として示します:</para>
-        
         <para>
-            
             <literal>[c,d] = foo(a,b)</literal>
-            
         </para>
-        
         <para>
-            
             <literal>a</literal>はdouble行列,<literal>a</literal>と同じ大きさの
-            
             <literal>b</literal>は論理値行列,
-            
             foo は<literal>a</literal>の各要素に2を乗じて,
-            
             <literal>c</literal>として返します.
-            
             また,bを要素毎に逆の論理値に変換して返します.
-            
         </para>
-        
         <para>
-            
             Scilabバイナリに含まれるツールボックススケルトンでサンプルを取得できます.
-            
             パスは
-            
             <literal>contrib/toolbox_skeleton/sci_gateway/c/sci_foo.c</literal>です.
-            
         </para>
-        
         <para>詳細な説明は以下の例のCコメント形式で提供されています.
-            
         </para>
-        
         <programlisting role="code_gateway">
-            
             <![CDATA[ 
 // 完全なソースはtoolboxスケルトンのsci_gateway/c/ ディレクトリにあります
 
 // 標準ヘッダ
 #include "api_scilab.h"
 #include "BOOL.h"
-
 // 関数宣言
 int sci_foo(char *fname, unsigned long fname_len)
 {
     // エラー管理変数
     SciErr sciErr;
-
     ////////// 変数宣言 //////////
     int m1 = 0, n1 = 0;
     int *piAddressVarOne = NULL;
     double *matrixOfDouble = NULL;
     double *newMatrixOfDouble = NULL;
-
     int m2 = 0, n2 = 0;
     int *piAddressVarTwo = NULL;
     int *matrixOfBoolean = NULL;
     int *newMatrixOfBoolean = NULL;
     int i = 0;
-
-
     ////////// 入力/出力引数の数を調べる //////////
     /* --> [c, d] = foo(a, b) */
     /* 入力引数が2のみであることを調べる */
     /* 出力引数が2のみであることを調べる */
     CheckInputArgument(pvApiCtx, 2, 2) ;
     CheckOutputArgument(pvApiCtx, 2, 2) ;
-
-
     ////////// 最初の入力引数 (double) を管理 //////////
     /* 入力アドレスを取得 */
     sciErr = getVarAddressFromPosition(pvApiCtx, 1, &piAddressVarOne);
@@ -586,14 +315,12 @@ int sci_foo(char *fname, unsigned long fname_len)
         printError(&sciErr, 0);
         return 0;
     }
-
     /* 最初の入力引数が実数行列(複素数でない)であることを調べる */
     if ( !isDoubleType(pvApiCtx, piAddressVarOne) ||  isVarComplex(pvApiCtx, piAddressVarOne) )
     {
         Scierror(999, "%s: Wrong type for input argument #%d: A real matrix expected.\n", fname, 1);
         return 0;
     }
-
     /* 行列を取得 */
     sciErr = getMatrixOfDouble(pvApiCtx, piAddressVarOne, &m1, &n1, &matrixOfDouble);
     if (sciErr.iErr)
@@ -601,9 +328,7 @@ int sci_foo(char *fname, unsigned long fname_len)
         printError(&sciErr, 0);
         return 0;
     }
-
     ////////// 2番目の入力引数を管理 (論理値) //////////
-
     /* 入力アドレスを取得 */
     sciErr = getVarAddressFromPosition(pvApiCtx, 2, &piAddressVarTwo);
     if (sciErr.iErr)
@@ -611,13 +336,11 @@ int sci_foo(char *fname, unsigned long fname_len)
         printError(&sciErr, 0);
         return 0;
     }
-
     if ( !isBooleanType(pvApiCtx, piAddressVarTwo) )
     {
         Scierror(999, "%s: Wrong type for input argument #%d: A boolean matrix expected.\n", fname, 2);
         return 0;
     }
-
     /* 行列を取得 */
     sciErr = getMatrixOfBoolean(pvApiCtx, piAddressVarTwo, &m2, &n2, &matrixOfBoolean);
     if (sciErr.iErr)
@@ -625,35 +348,27 @@ int sci_foo(char *fname, unsigned long fname_len)
         printError(&sciErr, 0);
         return 0;
     }
-
     ////////// 2つの入力引数の相関を確認 //////////
-
     if ((m1 != m2) || (n1 != n2))
     {
         Scierror(999, "%s: Wrong size for input arguments: Same size expected.\n", fname, 1);
         return 0;
     }
-
-
     newMatrixOfDouble = (double*)malloc(sizeof(double) * m1 * n1);
     ////////// アプリケーションコード //////////
     // ライブラリへのコールで置換することができます
-
     for (i = 0; i < m1 * n1; i++)
     {
         /* 行列の各要素を2倍します */
         newMatrixOfDouble[i] = matrixOfDouble[i] * 2;
     }
-
     newMatrixOfBoolean = (int*)malloc(sizeof(BOOL) * m2 * n2);
     for (i = 0; i < m2 * n2; i++)
     {
         /* 行列の各要素について, 値を反転する */
         newMatrixOfBoolean[i] = ((matrixOfBoolean[i] == TRUE) ? FALSE : TRUE);
     }
-
     ////////// 出力引数を作成 //////////
-
     /* 関数の戻り値として行列を作成 */
     sciErr = createMatrixOfDouble(pvApiCtx, nbInputArgument(pvApiCtx) + 1, m1, n1, newMatrixOfDouble);
     free(newMatrixOfDouble); // データをScilabメモリにコピー
@@ -663,7 +378,6 @@ int sci_foo(char *fname, unsigned long fname_len)
         printError(&sciErr, 0);
         return 0;
     }
-
     /* 関数の戻り値として行列を作成 */
     sciErr = createMatrixOfBoolean(pvApiCtx, nbInputArgument(pvApiCtx) + 2, m2, n2, newMatrixOfBoolean);
     free(newMatrixOfBoolean); // データをScilabメモリにコピー
@@ -672,31 +386,17 @@ int sci_foo(char *fname, unsigned long fname_len)
         printError(&sciErr, 0);
         return 0;
     }
-
-
     ////////// 出力引数をScilabエンジンに戻す //////////
-
     AssignOutputVariable(pvApiCtx, 1) = nbInputArgument(pvApiCtx) + 1;
     AssignOutputVariable(pvApiCtx, 2) = nbInputArgument(pvApiCtx) + 2;
-
     return 0;
 }
       ]]>
-            
         </programlisting>
-        
         <para>
-            
-            このコードを構築,Scilabにロードする際,
-            
-            Scilabの動的リンク機能を使用します.
-            
-            この組み込み処理はScilabに委任するため,
-            
-            以下のコードはマルチプラットフォームです.
-            
+            このコードを構築,Scilabにロードする際,Scilabの動的リンク機能を使用します.
+            この組み込み処理はScilabに委任するため,以下のコードはマルチプラットフォーム対応です.
             <programlisting role="scilab">
-                
                 <![CDATA[
       files=["sci_foo.c"];
       // TODO: WTF ?
@@ -705,47 +405,32 @@ int sci_foo(char *fname, unsigned long fname_len)
       exec loader.sce
       [c, d] = foo([2,%pi], [%t, %f])
       ]]>
-                
             </programlisting>
-            
         </para>
-        
         <para>
-            
             種々の確認が行われます:
-            
             <programlisting role="no-scilab-exec">
-                
                 <![CDATA[
 -->[c, d] = foo(2, 2)
                    !--error 999
 foo: Wrong type for input argument #2: A boolean matrix expected.
       ]]>
-                
             </programlisting>
-            
             <programlisting role="no-scilab-exec">
-                
                 <![CDATA[
 -->[c, d] = foo([2,2], %t)
                         !--error 999
 foo: Wrong size for input arguments: Same size expected.
       ]]>
-                
             </programlisting>
-            
             <programlisting role="no-scilab-exec">
-                
                 <![CDATA[
 -->[a,b]=foo(2+%i,%t)
                    !--error 999
 foo: Wrong type for input argument #1: A real matrix expected.
       ]]>
-                
             </programlisting>
-            
             <programlisting role="no-scilab-exec">
-                
                 <![CDATA[
 -->[c, d] = foo([2,%pi], [%t, %f])
  d  =
@@ -755,12 +440,7 @@ foo: Wrong type for input argument #1: A real matrix expected.
 
     4.    6.2831853
       ]]>
-                
             </programlisting>
-            
         </para>
-        
     </refsection>
-    
 </refentry>
-