api:call

The api:call keyword is used to call operations. Valid operations are the following:

Built-in operations installed along with driver assemblies located in the bin subfolder of the application
Operations you write yourself in .NET or Java and place in the bin subfolder of the application

Operations take items as input and return feeds as output. The scope of api:call is executed for every item in the feed returned from the call. Within the scope of api:call, you can inspect and modify the attributes in the item returned. You can then provide these attributes as inputs to another operation, thus forming an operation pipeline. Or, you can push out the item to the output.

The Output Item Stack and the Default Item

Each time an api:call is encountered, a new item is pushed onto an internal stack of items. The item on the top of this stack is the default item. This is the item that provides input to api:call when an item name is not explicitly specified in the input to the call.

The called operation writes attributes to the default item, and api:push pushes the default item to the output. When you push an item, only the attributes from the default item, at the top of the stack, are pushed.

The default item is swept clean after an item has been iterated over, and the api:call then works on the next item. This means that you will not be able to read a value set in a previous iteration of an api:call in the next iteration. To retain values across an iteration, copy them to a named item with api:set.

You can refer to the default item as _ or explicitly as _out1, _out2, _out[n], where N is the depth of the stack. This enables you to read all the values available at this point in the execution process; the lookup process starts from the default item and continues through the stack until a value is found.

In the example below, you can see how items are pushed to the top of the stack with each call and how the default item changes within the scope of each call.

<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>

Specify Input to an Operation

There are 3 ways to provide input to a call:

The default item: If an input item is not specified, the called operation reads input values from the default item. You can use the api:set keyword to set values in the default item so that they are processed by the called operation.
```
<api:set attr="mask" value="*.txt"/>
<api:set attr="path" value="C:\\"/>
<api:call op="fileListDir">
... 
</api:call>
```
An explicit input item: Instead of using the default item, you can use the in parameter to explicitly specify the items you want to use as input to the operation. If you choose to do so the default item is no longer used and the input values are read from the input items specified and, as shown below, the query string passed to the operation.
```
<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>
```
Query string parameters: You can also use query string notation to specify input to an operation. The attributes specified as part of the query string are given precedence. Thus, if there is a name clash between attributes specified in the query string and those in the input item, the ones in the query string are preferred. However, the other attributes of the input item are still accessible. The example below shows the syntax to specify input in the query string:
```
<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>
```

Parameters

op: The name of the operation to be called.
in[put]: A list of items used as input when invoking the operation. Attributes are looked up from left to right in the input items specified.
out[put]: The item where the output attributes are placed. Within the api:call scope, the current output item can be retrieved using the item name specified here. You can also use _out[n] or _pipe to refer to the call's results.

Note: Attributes set within a call are not available outside the scope of the call. This is because each iteration of the call deletes the attributes from the previous iteration; at the end of the call nothing is left. To access an attribute outside the scope of a call, use api:set to explicitly copy the attribute to the item you want to use outside the call.
item: The name of the item to be used for both input and output.
sep[arator]: The separator used to separate multiple input items. The default is a comma.
ignoreprefix: A comma-separated list of prefixes that are ignored when found. Some operations return attributes with names of the form "prefix:name" (e.g., api:operation and sql:company). In some situations, you may want to treat both prefix:name and name as the same attribute.
page and pagesize: The subset of items that will be iterated through. Used to enable paging of the operation or feed results. For example, if you specify page="2" and pagesize="5", the api:call keyword iterates only through items 6 to 10 of the resulting feed.

Control Attributes

_index: The index of the item currently being iterated over by api:call.
_op: The name of the operation being called. This is helpful when the operation name is not known until execution.
_separator: The separator used to separate multiple input items.

Examples

Call an operation using the default item as input:

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