Version 23.0.9145

• The Output Item Stack and the Default Item
• Specify Input to an Operation
• Parameters
• Control Attributes
• Examples
• See Also

Use the api:call keyword to call operations. Valid operations are:

• Built-in operations installed along with application assemblies located in the bin application subfolder
• Operations you write yourself in .NET or Java and place in the bin application subfolder
• Calls to other scripts on the same machine
• Scripts on a remote machine called over HTTP

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 returned item. You can then provide these attributes as inputs to another operation, forming an operation pipeline. Alternatively, you can push 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 api:call works on the next item. This means that you cannot 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 following example, 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

You have three ways to provide input to a call:

• The default item: If no input item is 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 do this, the default item is not used and the input values are read from the specified input items and, as shown in the following example, 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 a query string are given precedence. Therefore, if there is a name clash between attributes specified in the query string and those in the input item, those in the query string are preferred. However, the other attributes of the input item are still accessible. The following example 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 specified input items.

• out[put]: The item where the output attributes are placed. Within the api:call scope, you can retrieve the current output item using the item name specified here. You can also use _out[n] or _pipe to refer to the call’s results.

  Note: Attributes set in 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 use 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 in the form prefix:name (suce as api:operation and sql:company). In some situations, you might want to treat prefix:name and name as the same attribute.
• page and pagesize: The subset of items to iterate through. Used to enable paging of the operation or feed results. For example, if you specify page="2" and pagesize="5", api:call only iterates only items 6 to 10 of the resulting feed.
• httpmethod: The HTTP method used by the operation.
• authtype: The authentication type required by a feed accessed over HTTP. For example, basic or digest.
• authtoken: The authtoken to be used to authenticate to a feed accessed over HTTP.
• user: The username used to authenticate to a feed accessed over HTTP.
• password: The password used to authenticate to a feed accessed over HTTP.
• http_headers: Other HTTP headers required by a feed accessed over HTTP.
• proxyhost: The address of the proxy where the HTTP request is sent.
• proxyport: The TCP port that the HTTP proxy is running on.
• proxyuser: The username used to authenticate to the HTTP proxy.
• proxypassword: The password used to authenticate to the HTTP proxy.
• proxyauthtype: The HTTP authentication type required by the proxy. For example, basic or digest.
• proxyssltype: The SSL type to use when connecting to the proxy server. Valid values are AUTO, ALWAYS, NEVER, or TUNNEL. The default is AUTO.

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>

Call a script on a remote machine. As in the previous example, the script is nested:

<api:call op="http://someplace.com/customerList.rsb">
  <api:push/>
</api:call>

See Also

• api:first: Write elements to be executed only in the first iteration of the call.
• api:catch: Catch errors in a call.
• api:continue: Continue to the next iteration.