api:call

api:call キーワードは、オペレーションを呼び出すことに使われます。有効なオペレーションは次のとおり：

アプリケーションのbin サブフォルダに位置する、connector アセンブリとともにインストールされているビルトインオペレーション
.NET、またはJava で独自に書き、アプリケーションのbin サブフォルダに置かれたオペレーション

オペレーションは、アイテムをインプットに取り、フィードをアウトプットします。api:call のスコープは、呼び出しから返されたフィード内のすべてのアイテムに対し実行されます。api:call のスコープ内では、返されたアイテムのアトリビュートを調べ、変更することができます。そして、それらのアトリビュートを他のオペレーションのインプットとして提供することができます。このようにオペレーションパイプラインが形成されます。もしくは、アイテムをアウトプットに追加することもできます。

Output Item Stack およびDefault Item

api:call が起こるたびに、内部のアイテムスタックに新しいアイテムが追加されます。スタックの一番上のアイテムがデフォルトアイテムです。アイテム名が呼び出しのインプットで明示的に指定されていない場合には、このアイテムがapi:call にインプットを提供します。

呼び出されたオペレーションはアトリビュートにデフォルトアイテムを書き込み、api:push がデフォルトアイテムをアウトプットに追加します。アイテムを追加する際に、スタックの一番上のデフォルトアイテムからのアトリビュートだけが追加されます。

デフォルトアイテムは、アイテムが反復されると消され、api:call は次のアイテムに働きます。つまり、次の反復では、api:callの前の反復のvalue セットを読むことはできません。反復に渡って値を残すには、api:set を使って、名前を明示したアイテムにコピーします。

デフォルトのアイテムは_ もしくは明示的に_out1、_out2、_out[n]、（N はスタックの深さです）と示すことができます。これにより、実行処理におけるすべての有効な値を読むことができます。ルックアップ処理はデフォルトアイテムからはじまり、値が見つかるまでスタック内を読みます。

下の例では、それぞれの呼び出しでアイテムがスタックの一番上に追加されること、およびデフォルトアイテムがそれぞれの呼び出しスコープ内で変化することを確認できます。

<api:call op="operation1"> 
The default item here is _out1 
A push here would push the attributes from _out1 
The input item used to call operation2 is also _out1 
<api:call op="operation2"> 
The default item here is _out2 
A push here will push the attributes from _out2 
If there was another api:call here the input item used would be _out2 
_out2 is swept clean here for the next iteration 
</api:call> 
The default item here is again _out1 
A push here would again push the attributes from _out1 
The input item at this level is again _out1 
_out1 is swept clean here for the next iteration 
</api:call>

オペレーションにインプットを指定する

インプットを呼び出しに提供する3つの方法があります：

デフォルトアイテム：インプットアイテムが指定されない場合には、呼び出されたオペレーションはデフォルトアイテムのインプット値を読みます。呼び出された処理で使われるように、デフォルトアイテムの値の設定にはapi:set キーワードを使うことができます。
```
<api:set attr="mask" value="*.txt"/>
<api:set attr="path" value="C:\\"/>
<api:call op="fileListDir">
... 
</api:call>
```
明示的なインプットアイテム：デフォルトアイテムを使う代わりに、オペレーションのインプットアイテムとして使いたいアイテムを明示的にパラメータ内で指定することができます。そうすると、デフォルトアイテムは使われず、次のように、指定されたインプットアイテムからインプット値が読まれ、オペレーションにクエリ文字列が渡されます。
```
<api:set attr="mask" value="*.* -- Will be ignored --"/>
<api:set attr="myinput.mask" value="*.txt"/>
<api:set attr="myinput.path" value="C:\\"/>
<api:call op="fileListDir" in="myinput">
... 
</api:call>
```
クエリ文字列パラメータ：クエリ文字列表記を使って、オペレーションのインプットを特定することができます。クエリ文字列の一部として指定されたアトリビュートが優先されます。つまり、クエリ文字列で指定されたアトリビュートとインプットアイテムで指定されたアトリビュート名に差異がある場合、クエリ文字列のほうが優先されます。ただし、インプットアイテムの他のアトリビュートは、引き続きアクセス可能です。次の例では、クエリ文字列においてインプットを指定するシンタックスが説明されています：
```
<api:set attr="myinput.mask" value="*.txt -- will be overridden --"/> 
<api:set attr="myinput.path" value="C:\\"/> 
<api:call op="fileListDir?mask=*.rsb" in="myinput">
...
</api:call>
```

パラメータ

op:呼び出されるオペレーションの名前。
in[put]:オペレーションを起こす際にインプットとして使われるアイテムのリスト。指定されたインプットアイテムの中でアトリビュートは左から右へルックアップされます。
out[put]:アウトプットアトリビュートが位置するアイテム。api:call のスコープで、指定されたアイテム名を使って、現在のアウトプットアイテムを取得することができます。_out[n]、または _pipe を使って、呼び出し結果を参照することができます。

Note：呼び出しのスコープ外では、呼び出し内のアトリビュートセットは使用できません。これは、呼び出しのそれぞれの反復は、前の反復のアトリビュートを削除するためで、呼び出しの最後にはなにも残りません。呼び出しのスコープ外のアトリビュートにアクセスするためには、api:set を使って呼び出しの外で使いたいアイテムにアトリビュートを明示的にコピーします。
item:インプットとアウトプット双方で使われるアイテムの名前。
sep[arator]:マルチインプットアイテムを区切るためのセパレータ。デフォルトはカンマです。
ignoreprefix:見つけられたときに無視される接頭辞のカンマ区切りのリスト。いくつかのオペレーションでは、"prefix:name" （例えば、api:operation and sql:company）のような名前のアトリビュートを返します。いくつかのシチュエーションでは、prefix:name および name を同じアトリビュートとして扱います。
page およびpagesize：反復されるアイテムのサブセット。オペレーション、もしくはフィード結果のページングを有効化するために使われます。例えば、page-"2"、およびpagesize="5" を指定した場合に、api:call キーワードは結果フィードの6から10 のみを反復します。

アトリビュートの制御

_index:api:call によって現在反復されているアイテムのインデックス。
_op:呼び出されているオペレーションの名前。実行までオペレーション名が知られていない場合に役立ちます。
_separator:マルチインプットアイテムを区切るための区切り。

サンプル

デフォルトアイテムをインプットとしてオペレーションを呼び出します：

<api:set attr="path" value="C:\myfiles"/>
<api:call op="fileListDir">
  <api:push/>
</api:call>