Function: declare a function | Automation

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.
DoNotReturnError	True: all errors that may have been generated during the function execution are ignored when the function ends, and removed from the error stack False: no error is cleared Default (value not set): False

Example Scripts

<?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"/>
</ytriaAutomation>