# Defining a Function

## Introduction

A function is a set of common tasks that can be defined once and called multiple times from within a PGM.

A function is very similar to a subroutine. In many instances, either could be used. A subroutine can be used instead of a function if a value does not need to be returned. If a value does need to be returned then a function will need to be used.

## Syntax

Function functName (argument list)
...statements...
Return value
EndFunct

StrFunction  functName (argument list)
...statements...
Return string value
EndFunct


functName : is an unique name of the function, used to refer to the function.
argument list : optional list of parameters in the following format :

...datatype parameterName, datatype parameterName...etc
• The function declaration must begin with the Function or StrFunction keyword and end with the EndFunct keyword.
• Use StrFunction if the function is going to return a string and Function if the function is going to return a numerical value.
• A function may call itself (ie recursive functions are allowed). However, a true stack of the function variables is not used.
• Every possible execution path must use Return to ensure that the function is exited correctly.
• The parameter list cannot include instance of classes or variables passed by reference.
• Empty parentheses must be inserted, if no parameters are required by the function.
• Local variables can be declared within the function, and their scope is limited to the function. However when a function calls itself recursively a local stack is not used.
• Function definitions cannot be nested (ie functions cannot be defined within functions).

## Examples and Use

Function Examples

Example 1

Function HoursToMinutes(double timeInHours)
Return timeInHours/60
EndFunct


Example 2

Array c5
;this function initialises the array
function SetupArray()
c5.SetLen(Max(c5.GetLen(),3)) ;ensure the array has at least three elements
return 0 ;exit function
endif
c5.SetLen(6) ;set the length of the array
c5.SetAll(1) ;set all the elements of the array to 1
return 0
endfunct


Example 3

;this function places a random number in each element of the array
function RndLoop(byte Cnt)
while (Cnt>0)
Cnt = Cnt - 1
c5.SetAt(Cnt, random(10) - 5) ;set the specified element in the array
endwhile
return 0
endfunct


Example 4

StrFunction MakeTag(Str Prefix, long No)
return StrCat2(Prefix, "_", IntStr(No, 0))
endfunct


Using functions...

if (OnStart or OnLoaded)
SetupArray() ;array gets setup when run is pressed or PGM is reloaded
endif

if (Random(100)<10)
RndLoop(c5.GetLen()) ;a ten percent chance that the function will be called
else
c5.SetAt(0, c5.GetAt(1) * c5.GetAt(2)) ;set c5[0] = c5[1]*c5[2]
endif

Str s1*
s1 = MakeTag("P", 3)