Iterator Object Properties

Reference: Attachment Iterator Properties

Property Name	Allowable Value	Description
Handling Option	A literal, variable, or XPath that evaluates to "leave unchanged" or "delete", or "replace."	Determines handling options based on the following criteria: delete removes each attachment from the current document after processing, replace replaces the original attachment with the modified document, leave leaves the original attachments unchanged.
Start Index	A numeric expression, constant, XPath, or variable.	Index of first attachment to process in the mail object. The first attachment to the main document has index 0.
Header Namespace	A literal, variable, or XPath expression.	Special register namespace where MIME headers for the current attachment will be stored. If replace handling option is selected, registers in this namespace will be added to the replaced attachment.
Main Body Part Header Namespace	A literal, variable, or XPath expression.	If the current attachment is itself a Multipart, this is the special register namespace where the MIME headers for the main body part will be stored.
Keep Document Flat	A literal (true/false), variable or XPath expression.	Keeps the body of the document as an array of bytes

Reference: Chunk Iterator Properties

Property Name	Allowable Value	Description
Chunk Size in Bytes	A numeric expression, constant, XPath, or variable.	Size of the chunk in bytes.

Reference: Condition Iterator Properties

Property Name	Allowable Value	Description
Conditional Expression	A literal, variable, or XPath expression.	This is the expression controlling the termination of the loop
Iterate Rule	A literal, variable, XPath expression, ‘do-while’, or ‘do-until’.	Determines the loop logic between do-while or do-until
Interim Document	A literal, variable, XPath expression, ‘transient’, or ‘original’.	Determines if the document emitted at each iteration is the original document or the result of the previous iteration
Output Document	A literal, variable, or XPath that evaluates to "original" or "transient", or "status."	Determines whether the document passed out of the Iterator object upon completion of the loop is the original unparsed document or the result status.

Reference: COUNTER Iterator Properties

Property Name	Allowable Value	Description
Iterations	A numeric expression, constant, XPath, or variable.	Number of times this iterator loop is to be repeated.
Interim document type	A literal, variable, or XPath that evaluates to "original" or "transient."	Determines whether the document passed out of the Iterator object into the loop is the original or the result of the previous iteration (transient).
Output document type	A literal, variable, or XPath that evaluates to "original" or "transient", or "status."	Determines whether the document passed out of the Iterator object upon completion of the loop is the original or the result of the previous iteration (transient).

Example: Counter Iterator Type

The com.ibi.agents.XDIterCount operator repeats the body of the loop a specified number of times. The number can be constant or computed at run time, for instance, with an XPath expression, as in this example. The inner part of the loop can be used to generate multiple outputs, read multiple inputs from a source, or perform any other operation repeatedly. The count iterator can also be used with conditional logic to add retry functionality to an adapter that does not natively support retry. The number of iterations of the loop is not dependent on the structure of the input document, nor does the count iterator parse the document before injecting it into the loop.

The Iterator object in this example passes the input document into the loop the number of times specified by the <count> XML tag in the input document. The following sections show the process flow, the Iterator object parameters, and the input and output documents of this example.

Process Flow Diagram

Iterator Object Parameters

Input Document

<IterCountTest>
   <count>3</count>
</IterCountTest>

Output Document(s)

Three documents are output by the FileWrite object: IterCount01.xml, IterCount02.xml, and IterCount03.xml.

<?xml version="1.0" encoding="UTF-16"?>
<IterCountTest>
   <count>3</count>
</IterCountTest>

Reference: FTP Iterator Properties

Property Name	Allowable Value	Description
Host Name	A string expression, constant, XPath, or variable.	DNS name (or IP address) of the FTP server that you want to connect to. Use host : port if not standard port 21.
Remote Port	A numeric expression, constant, XPath, or variable.	Port to connect to on the FTP site, blank for default port 21.
User Name	A string expression, constant, XPath, or variable.	The valid user ID on the FTP server.
Password	A string expression, constant, XPath, or variable.	The valid password for the FTP server.
Account Name	A string expression, constant, XPath, or variable.	Account name which is the valid account for the FTP server.
User Passive Command	A literal (true/false), variable or XPath expression.	Uses PASV command if true, otherwise uses PORT command.
Timeout	A numeric expression, constant, XPath, or variable.	Timeout interval, in seconds, for socket.
Retry Interval	A string expression, constant, XPath, or variable.	Retry interval in seconds (allows for xxhxxmxxs format). Omit or use 0 for no retry.
Connection Retry	A string expression, constant, XPath, or variable.	Number of retry attempts after failed connection to FTP server.

Reference: Island Iterator Properties

Property Name	Allowable Value	Description
Island identifier	A string expression, constant, XPath, or variable.	Name of the XML tag that identifies the Island command string.
Remove Identifier	A Boolean literal, variable, or XPath.	Determines whether the Island tag and text will be removed or preserved in the final document.

Example: Island Iterator Type

The {com.ibi.agents.XDIterIsland} iterator is designed to perform document enhancement, that is, to replace parts of the input XML document with the results of a call to an agent or adapter. Any external data source can be targeted (Web Services, SQL data, and so on), but in this example embedded file names are replaced with the content of the named disk file. The replacement would behave identical regardless of the source, although the replacement data must be in XML format. Island replacement is iterated for as many tags as are present in the input document. The tags to be replaced may be homogeneous, as in this example, or heterogeneous by using multiple sequential Island iterators targeting different sources.

The following sections show the process flow, the Iterator object parameters, and the input and output documents of this example.

Process Flow Diagram

Iterator Parameters

Input Document

The primary input document is the document that contains the Islands to be replaced. In this example, they are identified by the XML tag <file>.

<mydoc>
   <file>file1.txt</file>
   <file>file2.txt</file>
   <file>file3.txt</file>
</mydoc>

file1.txt

<content>Contents of file 1</content>

file2.txt

<content>
<line>Contents of file 2</line>
<line>There are 2 lines</line>
</content>

file3.txt

<content>Contents of file 3</content>

Output Document(s)

The input document and the island documents are combined according to the behavior of the iterator.

<?xml version="1.0" encoding="UTF-8" ?>
<mydoc>
   <content>Contents of file 1</content>
   <content>
      <line>Contents of file 2</line>
      <line>There are 2 lines</line>
   </content>
   <content>Contents of file 3</content>
</mydoc>

Reference: Iter RVI Iterator Properties

Property Name	Allowable Value	Description
Service Name	A literal, variable, or XPath expression.	The name of the service to execute the current message.
Tolerance	A string expression, constant, XPath, or variable.	Determines the time, seconds, to await circuit availability to access the names service.
Timeout	A string expression, constant, XPath, or variable.	Time, in seconds, to await response from the gateway.
Attempt Retry	A literal (true/false), variable or XPath expression.	If true, a retry exception is thrown when no gateway connections are available, message cannot be written to the gateway, or this service times out while awaiting response. The retry exception will activate the channel’s pending system, when available. If false, this service will attempt to acquire a new connection if message cannot be written to the gateway, and if a connection is available, it will retry automatically. If no connections are available, or if the service times out or otherwise fails while reading the response, the service will return a failure edge.
Method of compression to use	A literal, variable, XPath expression, none, smallest, fastest, standard, or Huffman.	Describes the form of compression that should be used on the output.

Reference: Line Iterator Properties

Property Name	Allowable Value	Description
Keep blanks	A literal (true/false), variable or XPath expression that evaluates to a Boolean result.	Determines whether blank lines will be passed into the loop for processing.
Output	A literal, variable, or XPath that evaluates to "original" or "status".	Determines whether the document passed out of the Iterator object upon completion of the loop is the original unparsed document or the result status.

Example: Line Iterator Type

The {com.ibi.agents.XDIterLine} operator repeats the body of the loop once for each line in the document, as defined by standard end-of-line delimiters. The inner part of the loop can be used to generate multiple outputs, read multiple inputs from a source, or perform any other operation repeatedly. When using this iterator, the number of times through the loop and how the input is parsed is directly related to the structure of the input document, in particular, how many lines are present. We recommend that non-XML, line-oriented input be read into the process flow with a File object rather than being passed through the Start node.

The following sections show the process flow, the Iterator object parameters, and the input and output documents of this example.

Process Flow Diagram

Iterator Object Parameters

Input Document

This is the first line
This is line 2
Line 3

Output Document(s)

Three documents are output: IterLine01.txt, IterLine02.txt, and IterLine03.txt.

This is the first line
This is line 2
Line 3

Reference: SQL Batch Iterator Properties

Property Name	Allowable Value	Description
Input Provider	A literal, variable, or XPath expression.	Name of the provider for accessing input
Select SQL	A literal, variable, or XPath expression.	The SQL Select statement to get rows to pass into the flow
Transaction Isolation Level	A literal, variable, XPath expression, As Is, Read Committed, Read Uncommitted, Repeatable Read or Serializable.	Transaction isolation level to be set if possible
Base 64 if Needed	A literal (true/false), variable, or XPath expression.	If set, all fields are checked for base 64 (this is expensive)
Input Encoding	A literal, variable, XPath expression, Leave, Platform, US-ASCII, CP-037/EBCDIC, ISO-8859-1, UTF-8, UTF16-BE, UTF16-LE, UTF16.	The IANA character set to be used for the input data base. Select from the standard list or enter an encoding name.
Format as SQL Agent	A literal (true/false), variable, or XPath expression.	If true, the generated rows are formatted according to SQLAgent field schema.
Three Part Name	A literal (true/false), variable, or XPath expression.	If true, names will be presented a full three part names if supported by the data base.

Reference: SQL Select Iterator Properties

Property Name	Allowable Value	Description
Input Provider	A literal, variable, or XPath expression.	Name of the provider for accessing input
Select SQL	A literal, variable, or XPath expression.	The SQL Select statement to get rows to pass into the flow
Transaction Isolation Level	A literal, variable, XPath expression, As Is, Read Committed, Read Uncommitted, Repeatable Read or Serializable.	Transaction isolation level to be set if possible
Base 64 if Needed	A literal (true/false), variable, or XPath expression.	If set, all fields are checked for base 64 (this is expensive)
Input Encoding	A literal, variable, XPath expression, Leave, Platform, US-ASCII, CP-037/EBCDIC, ISO-8859-1, UTF-8, UTF16-BE, UTF16-LE, UTF16.	The IANA character set to be used for the input data base. Select from the standard list or enter an encoding name.
Output Document Type	A literal, variable, or XPath that evaluates to "original" or "status."	Determines whether the document passed out of the Iterator object upon completion of the loop is the original or the result status. By definition, the Interim document type is always the next sibling (that is, transient), never the original.
Format as SQL Agent	A literal (true/false), variable, or XPath expression.	If true, the generated rows are formatted according to SQLAgent field schema.
Three Part Name	A literal (true/false), variable, or XPath expression.	If true, names will be presented a full three part names if supported by the data base.

Reference: Sibling Iterator Properties

Property Name	Allowable Value	Description
Output document type	A literal, variable, or XPath that evaluates to "original" or "status."	Determines whether the document passed out of the Iterator object upon completion of the loop is the original or the result status. By definition, the Interim document type is always the next sibling (that is, transient), never the original.

Example: Sibling Iterator Type

The {com.ibi.agents.XDIterSibSplit} construct is used to contain the output of multi-row SQL queries. By bundling sets of rows, siblings makes the handling of very large result sets more practical. When used with the IterSibSplit operator, the logic inside the loop is executed once for each sibling document. One result row per sibling document is recommended for this iterator. Because the entire answer set is fetched prior to executing the loop, flows using this technique may have high memory requirements.

The following sections show the process flow, the Iterator object parameters, and the input and output documents of this example.

Process Flow Diagram

Iterator Object Parameters

In this case, the Iterator object parameters are not material, and the parameters of the SQL object that generates the internal document are significant. Note that the properties are set to produce siblings (which are internal, non-XML iWay constructs), with one SQL row for each sibling.

Reference: Test Iterator Properties

Property Name	Allowable Value	Description
Operand One	A literal, variable, or XPath that evaluates to a value.	The first of two operands to compare.
Operation	The comparison to apply to the two operands, or a null test predicate on Operand One.	Used to compare Operand One and Operand Two, producing a Boolean result.
Operand Two	A literal, variable, or XPath that evaluates to a value.	The second of two operands to compare. In the case of a null/not null test, this parameter is optional.
Iterate Rule	A literal (true/false), variable, or XPath expression that evaluates to a Boolean result.	Used to invert the logic of the Iteration test from do‑while to do-until. Using a non‑constant expression can simplify the flow logic by reversing the sense of the test dynamically.
Interim document type	A literal, variable, or XPath that evaluates to "original" or "transient."	Determines whether the document passed out of the Iterator object into the loop is the original or the result of the previous iteration (transient).
Output document type	A literal, variable, or XPath that evaluates to "original" or "transient", or "status."	Determines whether the document passed out of the Iterator object upon completion of the loop is the original or the result of the previous iteration (transient).

Example: Test Iterator Type

The {com.ibi.agents.XDIterTest} operator repeats the body of the loop while a specified logical comparison evaluates to True. The predicate is reevaluated each time through the loop. The inner part of the loop can be used to generate multiple outputs, read input multiple times from a source, or perform any other operation repeatedly. Similar to the count iterator, the test iterator can be used to retry an operation until it is successful or other criteria are met.

The following sections show the process flow, the Iterator object parameters, and the input and output documents of this example.

Process Flow Diagram

Iterator Object Parameters

Reference: XML SPLIT Iterator Properties

Property Name	Allowable Value	Description
Snip Levels	A literal, variable, or XPath that evaluates to an integer that is zero or greater.	Determines how many tag levels to trim off of the new XML document, starting from the top (root) node. Zero equals preserve all levels, one equals cut off the root, two equals cut off the root and immediate child, and so on, down to the XPath location being iterated. The default is zero, which will return all parent tags up to the root. Note: Cross Section data may be lost depending on the snip level setting.
Expression	An XPath string, derived from a constant, XPath, or variable.	An XPath that indicated where in the document to begin processing.
Cross Section	A literal, variable, or XPath that evaluates to true or false.	When set to false, only the direct parent tags of the iterated section are present in the split document. When set to true, all sibling sub‑trees of parent tags are preserved.
Output document type	A literal, variable, or XPath that evaluates to "original" or "status."	Determines whether the document passed out of the Iterator object upon completion of the loop is the original, or the result status. By definition, the Interim document type is always the split document (that is, transient), never the original.

When you are finished entering the properties, click Finish. The Iterator object appears in the workspace.

The following examples show an implementation of each iterator type.

Example: XML SPLIT Iterator Type

Often, a single transaction document contains repeating groups of data, in this example, a simplified invoice with multiple line items. The {com.ibi.agents.XDIterXMLSplit} iterator extracts the repeating group specified by the XPath expression. The parsed document contains the indicated group and preserves its direct parental lineage of XML nodes. If the logic inside your loop needs data from a parallel XML path (the invoice number in this example), then you can set Cross Section to true. Cross Section will preserve the entire document above the node that is the target of Expression.

The body of the loop is repeated once for each occurrence of the indicated group. The inner part of the loop can be used to process the repeating groups, call a Web service, insert the data into an SQL database, and so on. When using this iterator, the number of times through the loop and how the input is parsed depends on the structure of the input document and the XPath expression.

The following sections show the process flow, the Iterator object parameters, and the input and output documents of this example.

Process Flow Diagram

Iterator Object Parameters

Input Document

<invoice>
   <invoice-number>1001</invoice-number>
   <line-item>
      <item-number>1</item-number>
      <item-desc>Red Widget</item-desc>
   </line-item>
   <line-item>
      <item-number>2</item-number>
      <item-desc>Blue Widget</item-desc>
   </line-item>
   <line-item>
      <item-number>3</item-number>
      <item-desc>Green Do-dad</item-desc>
   </line-item>
</invoice>

Output Document(s)

Three documents are output by the FileWrite object: IterXmlSplit01.xml, IterXmlSplit02.xml, and IterXmlSplit03.xml.

<?xml version="1.0" encoding="UTF-16" ?>
<invoice>
   <line-item>
      <item-number>1</item-number>
      <item-desc>Red Widget</item-desc>
   </line-item>
</invoice>
<?xml version="1.0" encoding="UTF-16" ?>
<invoice>
   <line-item>
      <item-number>2</item-number>
      <item-desc>Blue Widget</item-desc>
   </line-item>
</invoice>
<?xml version="1.0" encoding="UTF-16" ?>
<invoice>
   <line-item>
      <item-number>3</item-number>
      <item-desc>Green Do-dad</item-desc>
   </line-item>
</invoice>

The following is an output document with Cross Section set to true.

<?xml version=”1.0” encoding=”UTF-16” ?>
<invoice>
   <invoice-number>1001</invoice-number>
   <line-item>
      <item-number>1</item-number>
      <item-desc>Red Widget</item-desc>
   </line-item>
</invoice>

The following is an output document with Snips Level set to 1.

<?xml> version=”1.0” encoding=”UTF-16” ?>
<line-item>
   <item-number>1</item-number>
   <item-desc>Red Widget</item-desc>
</line-item