====== Functions ======

A function is a stateless POU, in other words, if called with the same parameters, the result is always the same; a function has no inner state variables that would keep values between the calls. A function returns one result only (however, the results may be of different types). A function which returns no result should not be called in an expression. The norm describes standard functions, and user-defined functions. Standard functions are e.g. ADD for adding, ABS for absolute value, SQRT for square root, SIN for sine function. New user defined functions may be used repeatedly.

Note: Parameters of functions, e.g. when multiplying an input value by a constant at the MUL function, are declared as constants in the code. They can not be changed online. A constant can only be changed by editing the source program and uploading the project. If these parameters shall be changed online, the function inputs must be visible in the program, and connected to global variables. 

A function consists of two parts: declarative and executive. In the declarative part, all variables necessary for the operation of the function are defined. The executive part contains the commands which produce the function's result.

==== Function declaration ====

<code st-iec>
FUNCTION name: data_type ... 
END_FUNCTION  //data type is not compulsory for a function not returning a value
</code>

==== Variables declaration ====

The declarative part of a function contains definitions of variables which a function needs for its activity. The variables are used for storage of information. Each variable is defined by a variable name, and data type. The data type is specifying the size of the occupied place in the memory, and determines the way the variable is processed (to a certain extent). For variables definition, standard data types are available (BOOL, BYTE, INT, …). Usage of these types depends on what information is going to be stored in the variable (e.g. BOOL for yes/no information, INT for signed integer numbers, etc.). User is allowed to define his/her own data types. The location of variables in memory is managed by the IDE automatically. If necessary, the location in memory may be user-defined, too.

Input variables

<code st-iec>
VAR_INPUT 
    ... 
END_VAR
</code>

Output variables

<code st-iec>
VAR_OUTPUT 
    ... 
END_VAR
</code>

Input/output variables

<code st-iec>
VAR_IN_OUT 
    ... 
END_VAR
</code>

Local variables

<code st-iec>
VAR 
    ... 
END_VAR
</code>

External variables

<code st-iec>
VAR_EXTERNAL 
    ... 
END_VAR
</code>

Assignment of initial values to the variables

<code st-iec>
VAR 
    I : INT := 1; 
END_VAR;
</code>

==== Executive part ====

The executive part follows the declarative part. It contains commands and instructions. In exceptional cases, the function definition may not contain the declarative part, and the executive part is right behind the definition of function beginning. As an example, it may be a function which works with global variables only - this is not an ideal solution, although it may exist. The executive part of a function may contain calls of other functions. Parameters for the called functions or function blocks may be handed over at the call.

<code st-iec>
MY_FUNC := Value;  //function's result
</code>

==== Function call ====

Formal, complete

<code st-iec>
A := MY_FUNC(First_Index := 1, Last_Index := 5);
</code>

Informal

<code st-iec>
A := MY_FUNC(1, 5);
</code>


----

Example of a function (MY_FUNC):

<code st-iec>
VAR_GLOBAL             //external interface
    Data_Array: ARRAY[0..100] OF INT;
END_VAR

FUNCTION MY_FUNC: INT           //function name "MY_FUNC", returns a result of type INT
    VAR_INPUT             //input variables
        First_Index, Last_Index: INT;
    END_VAR

    VAR_EXTERNAL              //external variables
        Data_Array: ARRAY[0..100] OF INT;
    END_VAR

    VAR                  //local variables
        Sum, I: INT;
    END_VAR

    (* Function body *)
    Sum := 0;
    FOR I := First_Index TO Last_Index DO 
        Sum := Sum + Data_Array[I];
    END_FOR;
    MY_FUNC := Sum;         //function result
END_FUNCTION
</code>

{{:en:mervis-ide:35-help:func1.png}}

{{:en:mervis-ide:35-help:func2.png}}

A user-defined function inserted in a FUPLA program.

==== Calculation blocking ====

The input variable en is used for concatenation and blocking of subsequent calculations. The variable "eno" copies the state of the input variable "en".