Short summary

Name	`LoadRetainDataFast`
→POU type	→function
Category	more system blocks, persistence blocks, block with internal error diagnostic
Graphical interface
Available since	version 3.2.2 (for library `Standard`) The block is supported for the platforms `LinuxX86` and `WindowsX86` (incl. the built-in PLC under Windows).

Functionality

The block loads values from a binary file for →retentive variables. Compare LoadRetainData block for an alternative.

Restrictions

This block only loads the values for the retentive variables, if the application has not changed and loaded since the retentive variables have been saved. This means, that the application must have the same →fingerprint.
The values of retentive →function block instances are not loaded.

Recommendation on usage

Use the block only once in a →program and at the beginning of the application cycle (= init state). See example below.
Reason: Depending on the number ob variables and the storage device of the target system, the loading of the values might be rather time consuming. Therefore, if you call this block repeatedly in your application, the execution of the application might take longer with each call.

Inputs, return value

Identifier

→Data type

Description

Inputs:

fileName

STRING

name of the file where the values of the variables are stored
Without any connected value for this input, the file retain.var is used.
By default, the file is searched in the subdirectory PLC of the runtime system installation directory. If you prefer that a different directory is used, contact your system integrator and ask to change the configuration of the system service.

Return value:

–

UDINT

returns the success indicator:

16#00: OK
16#01: memory allocation failed
16#02: missing or invalid data
16#03: IO error
16#04: other error
16#05: no persisted data available
16#ff: system service not loaded on target system

Input EN and output ENO are available when →calling the block. See "Execution control: EN, ENO" for information on input EN and output ENO.

See:

"Blocks for safe logic" whether this block is supported for developing safety-relevant applications.
"Highlighting safe logic in the FBD-editor" for the effects when using the block as a block for safe logic .

Internal error diagnostic for block

The block checks the following error cases:

The system service has not been loaded.
The return value of the function call equates to an error (return value ≠ value 0).

In such an error case, the output ENO of the block is set to value FALSE (or an equivalent).

Example for usage within ST-editor

The values of the variables that are declared in the section VAR RETAIN ... END_VAR are loaded in the initial state (= init state) and saved in the term state by using the RTSCycleInfo block.
Best to see the RTSCycleInfo block to find out at which moments the initial cycle and the term cycle respectively are executed.

PROGRAM ExampleLoadSaveRetainDataFast
  VAR RETAIN
    Test1    : BOOL;
    Test2    : INT;
    Test3    : REAL;
    Test4    : STRING[50];
  END_VAR
  VAR
    init          : BOOL;
    term          : BOOL;
    loadRetainRC  : UDINT;
    loadRetainENO : BOOL;
    saveRetainRC  : UDINT;
    saveRetainENO : BOOL;
  END_VAR
  RTSCycleInfo(
    Init=>init,
    Term=>term
  );
  loadRetainRC := LoadRetainDataFast(EN:=init, ENO=>loadRetainENO);
  saveRetainRC := SaveRetainData(EN:=term, ENO=>saveRetainENO);
END_PROGRAM

When creating your application within the ST-editor, enter a call of a block by typing the text as requested by the syntax or use Content Assist.