Pointers

Overview

As an extension to the IEC 61131-3 standard, you can use pointers.

Pointers save addresses while an application program is running. A pointer can point to a variable of any data type or to a function block instance. The possibility of using an implicit pointer monitoring function is described further below in the paragraph CheckPointer function.

Syntax of a Pointer Declaration

<identifier>: POINTER TO <data type>;

Dereferencing a pointer means to obtain the value currently stored at the address to which it is pointing. You can dereference a pointer by adding the content operator ^ (ASCII caret or circumflex symbol) after the pointer identifier. See pt^ in the example below.

You can use the ADR address operator to assign the address of a variable to a pointer.

NOTE: Pointers pointing to an I/O input require write access. This leads to the compiler message '<pointer name >' is not a valid assignment target when the code is generated.

Example: pwInput := ADR(wInput);

To help avoid the compiler detecting such an error, copy the input value (wInput) to a variable with write access.

Example

VAR
  pt:POINTER TO INT;  (* of pointer pt *)
var_int1:INT := 5;  (* declaration of variables var_int1 and var_int2 *)
  var_int2:INT;
END_VAR
pt := ADR(var_int1); (* address of var_int1 is assigned to pointer pt *)
var_int2:= pt^;      (* value 5 of var_int1 gets assigned to var_int2 via dereferencing of pointer pt; *)

In online mode, you can jump from a pointer to the declaration location of the referenced variable by executing the Go To Reference command.

Function Pointers

EcoStruxure Machine Expert also supports function pointers. These pointers can be passed to external libraries, but it is not possible to call a function pointer within an application in the programming system. The runtime function for registration of callback functions (system library function) expects the function pointer, and, depending on the callback for which the registration was requested, the respective function will be called implicitly by the runtime system (for example, at STOP). In order to enable such a system call (runtime system), set the respective properties (by default under View > Properties... > Build) for the function object.

You can use the ADR operator on function names, program names, function block names, and method names. Since functions can move after online change, the result is not the address of the function, but the address of a pointer to the function. This address is valid as long as the function exists on the target.

Executing the Online Change command can change the contents of addresses.

CAUTION
	INVALID POINTER Verify the validity of the pointers when using pointers on addresses and executing the Online Change command. Failure to follow these instructions can result in injury or equipment damage.

Index Access to Pointers

As an extension to the IEC 61131-3 standard, index access [] to variables of type POINTER, STRING and WSTRING is allowed.

[i] returns the base data type.
Index access on pointers is arithmetic:

If the index access is used on a variable of type pointer, the offset pint[i] equates to (pint + i * SIZEOF(base type))^. The index access also performs an implicit dereferencing on the pointer. The result type is the base type of the pointer.

Note that pint[7] does not equate to (pint + 7)^.
If the index access is used on a variable of type STRING, the result is the character at offset index-expr. The result is of type BYTE. [i] will return the i-th character of the string as a SINT (ASCII).
If the index access is used on a variable of type WSTRING, the result is the character at offset index-expr. The result is of type WORD. [i] will return the i-th character of the string as INT (Unicode).

NOTE: You can also use References. In contrast to a pointer, references directly affect a value.

Subtracting Pointers

The result of the difference between two pointers is a value of type DWORD.

`CheckPointer` Function

To monitor pointer access during runtime, you can use the implicit monitoring function CheckPointer. You can adapt it, if required. To achieve this, add the POUs for implicit checks object to the application. Activate the check box related to the category Pointer Checks.

NOTE: You have to implement the CheckPointer function during machine commissioning to verify whether the passed pointer refers to a valid memory address and whether the alignment of the referenced memory area fits to the data type of the variable that the pointer points to.

CheckPointer monitors variables of type REFERENCE TO in a similar way.

NOTE: There is no implicit call of the check function for the THIS pointer.

Template:

Declaration part:

// Implicitly generated code : DO NOT EDIT
FUNCTION CheckPointer : POINTER TO BYTE
VAR_INPUT
ptToTest : POINTER TO BYTE;
iSize : DINT;
iGran : DINT;
bWrite: BOOL;
END_VAR

When called, the following input parameters are provided to the function:

ptToTest: Target address of the pointer
iSize: Size of referenced variable; the data type of iSize has to be integer-compatible and has to cover the maximum potential data size stored at the pointer address.
iGran: Granularity of the access that is the largest non-structured data type used in the referenced variable; the data type of iGran has to be integer-compatible
bWrite: Type of access (TRUE= write access, FALSE= read access); the data type of bWrite has to be BOOL.

Implementation of the `CheckPointer` Function for PacDrive Controllers

The implementation of the CheckPointer function for PacDrive controllers (PacDrive LMC Eco / PacDrive LMC Pro/Pro2) is to generate a system runtime exception and to write a call stack to the message logger when the memory address or the alignment is invalid.

Implementation part:

CheckPointer := ptToTest;
IF ptToTest = 0 THEN
        FC_DiagMsgWrite(4, 'CP = 0');
        FC_SysUserCallStack(0);
ELSE
        CheckPointer := ptToTest;
END_IF

Implementation of the `CheckPointer` Function for Optimized Controllers

The implementation of the CheckPointer function for Optimized Controllers (for example, Modicon M241 Logic Controller) is to return the passed pointer.

Implementation part (incomplete):

// No standard way of implementation. Fill your own code here
CheckPointer := ptToTest;

In case of a positive result of the check, the unmodified input pointer will be returned (ptToTest).