Short summary

Name	`LoadRetainData`
→POU type	→function
Category	more system blocks, persistence blocks, block with internal error diagnostic
Graphical interface
Available since	version 1.92.0 (for logi.CAD 3) and version 3.8.2 of the →runtime system version 3.2.2 (for library `Standard`) – enhancement: added return value, data type of `filename` changed from `STRING[50]` to `STRING`, wider interface, new filing in sub-folder `Persistence` The block is supported for the platform `WindowsX86` (incl. the built-in PLC under Windows). Moreover, this block is supported for these target systems: →Raspberry Pi, →Revolution Pi

Functionality

The block loads values from a CSV file for →retentive variables.

Restriction

STRING values are only loaded up to the 254th character. Strings > 254 characters are truncated correspondingly.
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, outputs, 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 `persistence.csv` 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.
Outputs:	`nrNonLoaded`	`INT`	number of variables that could not be loaded
	`nrMoreRetainVars`	`INT`	number of variables marked as `RETAIN` in the application for which no values have been not loaded from the file Values output for `nrMoreRetainVars` will not raise an error.
	`RC`	`UDINT`	return code: `0`: OK `2`: error during file load operation `3`: error during initialization or no variables marked as `RETAIN` `4`: error during file open `6`: no valid file name `7`: values for some variables could not be loaded (see `nrNonLoaded`) `8`: syntax error in file `9`: system service not loaded on the target system
Return value:	–	`UDINT`	returns the return code of `RC`

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

Internal error diagnostic for block

The block checks the following error cases:

The system service has not been loaded.
The return code of the function call equates to an error (output RC ≠ 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 ExampleLoadSaveRetainData
  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;
    nrNonLoaded   : INT;
  END_VAR
  RTSCycleInfo(
    Init=>init,
    Term=>term
  );
  LoadRetainData(
    EN:=init,
    fileName:='Persistent.csv',
    nrNonLoaded=>nrNonLoaded,
    RC=>loadRetainRC,
    ENO=>loadRetainENO
  );
  SaveRetainData(
    EN:=term,
    fileName:='Persistent.csv',
    RC=>saveRetainRC,
    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.