While | Automation | Ytria Documentation

Tag: While

The While function creates a a loop without having to use the mechanics of the LOOP action. In short, no lists are needed.

Detailed Description

The While loop is infinite by default. It must be made to stop with a BREAKLOOP action inside the While block, with a condition directly set at the While level, or with Max.
While is like a LOOP and an IF combined.

Setting conditions at the While level is similar to the conditions for IF.
While has one more attribute, "Max=n", which caps the While at n iterations, with or without a condition: the loop stops when its condition becomes false or after n iterations, whichever comes first. Without Max, the loop has no iteration limit.
Older versions ignored the condition when Max was set: the While always ran n iterations.

Variables from LOOP like {%LoopIndex%} are available with While.

It is easy to create an infinite loop with While. If it happens, the application freezes (Notes apps) or makes it impossible to run any other automation (job or script, sapio365). The only way to break an infinite While loop is to hit the Cancel Automation button on the console. To guard against it, set Max on the While.

Tag Attributes

Attributes	Value Description
Max	Positive number: the maximum number of iterations. Applies with or without a condition: the loop stops at whichever comes first.
Target	"Tree" "Grid" (for default grid) or Grid name "Var" for variables declared with SetVar "List"
Test	What the While is about: "FocusRoot": tree top node "SelectionCount": number of selected entries in the tree or grid set in Target (in grid it counts group rows) "VisibleRowsCount": visible rows in grid set in Target Variable name, e.g. {%MyVar%} or list name
Mode	How to compare: Equals NotEquals GreaterThan GreaterOrEquals LessThan LessOrEquals Begins NotBegins Ends NotEnds Contains NotContains Exists (Target "List") Empty (Target "List") IsIn (colon-separated list text) IsNotIn (colon-separated list text)
Value	True / False - Both values only used for FocusRoot and mode for "Exists" lists), or any integer number (SelectionCount, VisibleRowsCount) as well as any text when testing variables
OnError	Action to take in case of error within While block: "ExitLoop": break loop and continue with script "Next": continue to next loop action item

This example shows three ways of running a 3-iterations loop:

Example Scripts

XML

<If Target="Grid" Test="VisibleRowsCount" Mode="LessThan" Value="5"> 
	<Echo Value="Fewer than 5 visible rows in the grid"/>
</If>

XML

<ytriaAutomation>
	<While Max="3">
		<Echo Value="1. ======> while index: {%loopindex%}"/>
	</While>
	<While>
		<Echo Value="2. ======> while index: {%loopindex%}"/>
			<If Target="var" Test="{%loopindex%}" Mode="equals" Value="3">
				<BreakLoop/>
			</If>
	</While>
	<While Target="var" Test="{%loopindex%}" Mode="LessOrEquals" Value="3">
		<Echo Value="3. ======> while index: {%loopindex%}"/>
	</While>
</ytriaAutomation>

XML

<ytriaAutomation>

	<SetVar MyThings="42"/>
	<While Target="var" Test="{%MyThings%}" Mode="IsIn" Value="312:Georges:42:666" Max="3">
		<MsgBox Message="42"/>
	</While>

	<While Target="var" Test="{%MyThings%}" Mode="IsNotIn" Value="Mugre" Max="3">
		<MsgBox Message="Not Mugre"/>
	</While>

</ytriaAutomation>