Function: declare a function

The Function tag allows to declare a function, a block of code that can be executed by invoking its name.

Detailed Description

Creates a unit of execution that can be run at will by invoking it s name. Once declared, a function is global and can be called from any other part of the script, including Execute with subscripts, ExecuteVar etc.

Variables and lists declared inside a function are local (values not visible after function completion).

Global variables and lists are accessible for read/write and remain modified after function completion.

NB: if a function contains a UserInput, generating a job preset makes the variables from the UserInput global when the job runs.

Tag Attributes

Attributes

Value Description

Name

Any unreserved name valid in XML. Reserved names are listed on: Variables

Required

Echo

True: turn echo on

False: turn echo off

Default (value not set): current script setting

OnError

Local: bypass script OnError setting and use default OnError settings; <OnError …/> tags inside the function remain local and do not alter the main script

Global: use main script current OnError setting

Default: Global

NB: if Global and an <OnError …/> action tag appears inside the function, it sets the main script error management.

Example Scripts

CODE

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<ytriaAutomation Console="True">

<list name="ListGlobal" Action="setVar" Dname="L1"/>
<list name="ListGlobal" Action="setVar" Dname="L2"/>
<list name="ListGlobal" Action="setVar" Dname="L3"/>

<SetVar GlobalVar="Top level var"/>
<SetVar FirstFunction="F1"/>

Declare function Local OnError and no trace:
<function name="{%FirstFunction%}" OnError="Local" echo="false">

    local error mgt:
	<OnError continue="true" MsgBox="Function error!"/>
	
	<echo value="+++++++++ Let us run {%FirstFunction%}"/>
	<echo value="global var: {%GlobalVar%}"/>
	<echo value ="Size of ListGlobal in {%FirstFunction%} = {%lSize%}"/>
	
	error:
	<Unselect/>
	
	<list name="ListLocal" Action="setVar" Dname="O1"/>
	<list name="ListLocal" Action="setVar" Dname="O2"/>
	<SetVarListSize localSize='ListLocal'/>
	<echo value ="Size of ListLocal in {%FirstFunction%} = {%localSize%}"/>
	
	<echo value="Before set local var: {%LocalVar%}"/>
	<SetVar LocalVar="LocalVar"/>
	<echo value="After set local var: {%LocalVar%}"/>
	
	<list name="ListGlobal" Action="setVar" Dname="L4 added in {%FirstFunction%}"/>
	<SetVar GlobalVar="This text was set in {%FirstFunction%}"/>
	<breakLoop/>
	<echo value="After break, should not display"/>
</function>

<SetVarListSize lSize='ListGlobal'/>
<echo value ="MAIN size of ListGlobal {%lSize%}"/>
<echo value ="MAIN GlobalVar = '{%GlobalVar%}'"/>

<echo value="About to run function {%FirstFunction%} with default echo off/local OnError"/>
run function:
<executeFunction name="{%FirstFunction%}"/>

<SetVarListSize lSize='ListGlobal'/>
<echo value ="MAIN size of ListGlobal {%lSize%}"/>
<echo value ="MAIN GlobalVar in Main = '{%GlobalVar%}'"/>

Check if variables set in function are visible:
<echo value="MAIN ********* local var: '{%LocalVar%}' * should be empty"/>
<echo value="MAIN ********* Size of ListLocal: '{%localSize%}' * should be empty"/>
NB: these variables are now global, next function call will not erase them

error:
<Unselect/>

<echo value="After error in main, should not display"/>