Calling Elementary Functions

Elementary Functions

Elementary functions are provided in the form of libraries. The logic of the functions is created in the programming language C and may not be modified in the ST editor.

Functions have no internal states. If the input values are the same, the value at the output is the same for all executions of the function. For example, the addition of two values gives the same result at every execution.

Some elementary functions can be extended to more than 2 inputs.

Elementary functions only have one return value (Output).

Parameters

"Inputs" and one "output" are required to transfer values to or from a function. These are called formal parameters.

The current process states are transferred to the formal parameters. These are called actual parameters.

The following can be used as actual parameters for function inputs:

Variable

Address

Literal

ST Expression

The following can be used as actual parameters for function outputs:

Variable
Address

The data type of the actual parameters must match the data type of the formal parameters. The only exceptions are generic formal parameters whose data type is determined by the actual parameter.

When dealing with generic ANY_BIT formal parameters, actual parameters of the INT or DINT (not UINT and UDINT) data types can be used.

This is a supplement to IEC 61131-3 and must be enabled explicitly.

Example:

Allowed:

AND (AnyBitParam := IntVar1, AnyBitParam2 := IntVar2);

Not allowed:

AND_WORD (WordParam1 := IntVar1, WordParam2 := IntVar2);

(In this case, AND_INT must be used.)

AND_ARRAY_WORD (ArrayInt, ...);

(In this case an explicit type conversion must be carried out using INT_ARR_TO_WORD_ARR (...);.

Not all formal parameters must be assigned with a value. The formal parameter types that must be assigned with a value are in this table:

Parameter type	EDT	STRING	ARRAY	ANY_ARRAY	IODDT	STRUCT	FB	ANY
Input	-	-	-	-	+	-	+	-
VAR_IN_OUT	+	+	+	+	+	+	/	+
Output	-	-	-	-	-	-	/	-
+ Actual parameter required
- Actual parameter not required, it's the general rule, but there are exceptions for some FFBs, for instance when some parameters are used to characterize the information we want to be given by the FFB.
/ not applicable

If no value is allocated to a formal parameter, then the initial value is used for executing the function block. If no initial value has been defined, then the default value (0) is used.

Programming Notes

Attention should be paid to the following:

All generic functions are overloaded. This means the functions can be called with or without entering the data type.

E.g.

i1 := ADD (i2, 3);

is identical to

i1 := ADD_INT (i2, 3);
Functions can be nested.
Functions are only executed if the input EN = 1 or the EN input is not used.
There are two ways of calling a function:
- Formal call (calling a function with formal parameter names)
- Informal call (calling a function without formal parameter names)

Formal Call

With formal calls (calls with formal parameter names), the call consists of the actual parameter of the output, followed by the assignment instruction :=, then the function name and then by a bracketed list of value assignments (actual parameters) to the formal parameter. The order in which the formal parameters are enumerated in a function call is not significant.

EN and ENO can be used for this type of call.

With formal calls it is not necessary to assign a value to all formal parameters.

out:=LIMIT (MN:=0, IN:=var1) ;

Informal Call

With informal calls (calls without formal parameter names), the call consists of the actual parameter of the output, followed by the symbol of the assignment instruction :=, then the function name and then by a bracketed list of the inputs actual parameters. The order that the actual parameters are enumerated in a function call is significant.

EN and ENO cannot be used for this type of call.

With informal calls it is not necessary to assign a value to all formal parameters.

This is a supplement to IEC 61131-3 and must be enabled explicitly.

An empty parameter field is used to skip a parameter.

Call with empty parameter field:

out:=LIMIT ( ,var1, 5 + var) ;

An empty parameter field does not have to be used if formal parameters are omitted at the end.

out:=LIMIT (0, var1) ;

Nesting Functions

A function call can include the call of further functions. The nesting depth is not limited.

Nested call of array function:

out:=LIMIT (MN:=4, IN:=MUL(IN1:=var1, IN2:=var2), MX:=5) ;

Functions that return a value of the ANY_ARRAY data type can not be used within a function call.

ANY_ARRAY is permitted as the return value of the function called or as a parameter of the nested functions.

EN and ENO

With all functions an EN input and an ENO output can be configured.

If the value of EN is equal to "0", when the function is called, the algorithms defined by the function are not executed and ENO is set to "0".

If the value of EN is equal to "1", when the function is called, the algorithms which are defined by the function are executed. After successful execution of these algorithms, the value of ENO is set to "1". If an error occurs during execution of these algorithms, ENO will be set to "0".

If the EN pin is not assigned a value, when the FFB is invoked, the algorithm defined by the FFB is executed (same as if EN equals to "1").

If ENO is set to "0" (caused when EN=0 or an error occurred during executing), the output of the function is set to "0".

The output behavior of the function does not depend on whether the function was called up without EN/ENO or with EN=1.

If EN/ENO are used, the function call must be formal.

out:=LIMIT (EN:=1, MN:=0, IN:=var1, MX:=5, ENO=>var2) ;