Functions & Function Blocks

In addition to simple statements like PRINT or IF, Coldwave Script also provides reusable components. These come in two forms: functions and function blocks. The distinction is essential: functions are stateless and return a value, while blocks hold internal state and operate through inputs and outputs.

Difference: Function vs. Block

Aspect	Function	Function Block
State	none	internal state (e.g. timer value, counter)
Invocation	by name + arguments	by instantiation (DIM)
Return	exactly one value	multiple outputs (Q, ET, CV, …)
Example	ABS(-5) → 5	TON: T(IN:=TRUE,PT:=T#1000ms)

Parameter Passing (IN/OUT) and the Operator =

Functions and blocks accept parameters differently.

Functions

• Parameters are passed positionally.
• They only have inputs (IN) and exactly one return value.
• The return value has the same name as the function.
• To return a value, assign it to the function's name.
• Assignments inside a program use the operator =.

FUNCTION ADD2(A AS DINT, B AS DINT) AS DINT
    ADD2 = A + B
END FUNCTION

PROGRAM
    DIM result AS DINT
    result = ADD2(2, 3)      ' assignment using =
    PRINT result             ' Output: 5
END PROGRAM

Function Blocks

• Blocks have named inputs and outputs.
• When invoked, inputs are typically wired once in the declaration using the connection operator :=.
• Inputs can be overridden in a block call when passed as named parameters (e.g. T (IN = TRUE)).
• Outputs are read via fields such as .Q, .CV, etc.

Recommended structure:

ALIAS %IX0.0 AS StartButton
ALIAS %QX0.1 AS MotorRelay

' Static wiring – declared once
DIM T AS TON (IN := StartButton)
' Alteratively after the declaration as
T.PT := T#1000ms

PROGRAM
    ' Cyclic execution happens automatically, using the wiring defined above
    ' but the block can be invoked any time like this
    T()
    ' or with overridden inputs for that single invocation
    T(IN = FALSE)

    IF T.Q THEN
        MotorRelay = TRUE
    END IF
END PROGRAM

• Block instances should be declared above PROGRAM and wired using :=.
• The PROGRAM block contains the runtime logic (=, IF, calls to T()).

Summary:

• = assigns values to variables, function or block parameters in calls, or receives function return values.
• := creates signal connections, typically outside PROGRAM.
  Technically := is allowed inside PROGRAM, but stylistically it is recommended to define wiring outside and keep logic clean.

Return Values

Functions return a single value, which can be used directly in expressions. The return value is a variable by the name of the function. (e.g. FUNCTION F -> assign to F) To return a value, simply assign to it

Blocks expose outputs via instance fields (e.g., T.Q, C.CV).
Blocks retain their state across cycles — a TON continues running even if not referenced in every line.

Examples

Custom function:

FUNCTION ADD2(A AS DINT, B AS DINT) AS DINT  
    ADD2 = A + B  
END FUNCTION  

PROGRAM  
    PRINT ADD2(2,3) ' Output: 5  
END PROGRAM

Built‑in function:

PROGRAM  
    DIM v AS INT = -42  
    PRINT ABS(v) ' Output: 42  
END PROGRAM

Function block TON:

PROGRAM  
    DIM T AS TON (IN := TRUE, PT := T#500ms)  
    IF T.Q THEN  
        PRINT "Timeout"  
    END IF  
END PROGRAM

Practical example: Blinking pattern

PROGRAM  
    DIM T AS TON
    DIM state AS BOOL = FALSE 
    ' TON produces a trigger every 500ms
    IF NOT T.Q THEN  
        T(IN = TRUE, PT = T#500ms)  
    END IF  
    IF T.Q THEN  
        state = NOT state  
        T(IN = FALSE, PT = T#500ms) ' reset timer  
    END IF  
    PRINT state  
END PROGRAM

Defining Custom Function Blocks

In addition to built‑in blocks (TON, TOF, CTU, …), Coldwave Script allows defining custom blocks. A block encapsulates inputs, outputs, and internal state — similar to IEC function blocks.

Definition

BLOCK HYSTERESIS
  INPUTS
    IN   AS REAL,
    LOW  AS REAL,
    HIGH AS REAL
  
  OUTPUTS
    Q    AS BOOL

  BEGIN
    DIM state AS BOOL

    IF (NOT state) AND (IN >= HIGH) THEN
        state = TRUE
    END IF

    IF state AND (IN <= LOW) THEN
        state = FALSE
    END IF

    Q = state
END BLOCK

• BLOCK <Name> starts the definition.
• INPUT and OUTPUT declare ports. multiple ports need to be comma-separated.
• BEGIN starts the block body
• Internal state variables are declared using DIM inside the block body.
• END BLOCK closes the definition.

Instantiation and Invocation

PROGRAM
    DIM H AS HYSTERESIS

    H(IN = tempSensor, LOW  = 18.0, HIGH = 22.0)
    heaterOutput = H.Q
END PROGRAM

• DIM H AS HYSTERESIS creates an instance.
• Calling H(...) updates outputs based on current inputs.
• The internal state persists across cycles.

Summary

• Functions are stateless and return a single value.
• Blocks have state, inputs/outputs, and are suited for timers, counters, and logic modules.
• Parameter passing differs: positional (functions) vs. named wiring (blocks).
• Examples demonstrate typical usage patterns.