Table of Contents

WritePersistentDataUM

Namespace
ZPlatform
Extends
Inherited Properties
Inherited Methods
Implements
FUNCTION_BLOCK WritePersistentDataUM EXTENDS ZPlatform.PlatformAdapterObject IMPLEMENTS ZCore.IWritePersistentData, ZCore.IObject, ZCore.IError (
 [output] State : ObjectState)

In TwinCAT, if persistent variables are defined in the PLC, their current values are normally saved in a .bootdata file in the TwinCAT\Boot folder when the TwinCAT system is stopped, put in config mode or an exception occurs. Before writing the current persistent data to the file, a backup of the old persistent data is made by renaming the system's old .bootdata file to .bootdata-old. A file is created for every PLC that is configured and suffixed with the PLC's port (e.g. Port_851.bootdata) The next time the system starts, the .bootdata file is read and the persistent variables in the runtime system are initialized with the values from the file and the .bootdata file is deleted by TwinCAT.

The backup file (.bootdata-old) of the persistent data is read at system startup if the file (.bootdata) containing the persistent data does not exist. This is an exception, but it can occur, for example, if an IPC without UPS experiences a power failure and TwinCAT could not shut down properly.

Since .bootdata is only written automatically when stopping/shutting down the TwinCAT system and deleted once the data it is out-of-the-box not possible to perform a up-to-date backup of .bootdata. This is where WritePersistentDataUM comes to action. The function allows to save persistents variables of a particular PLC (denotes by its port) to .bootdata by calling SavePersistentDataAsync, which follows the usual conventions of an object task (State transitions, etc.).

The function block doesn't come with a Booting phase and therefore is immediatelly ready to use. Typically this function block should be called when the PLC is performing none-critical tasks (e.g. when idle, after a stop, or error, ...), because when using a large amout of persistent variables in a PLC the saving process may be time consuming and in the worst case even cause a missed cycle.

Per default this function block will save the persistent variables of the PLC with port=851, which is the default port for the first PLC in TwinCAT 3 projects. The port can be overwritten by calling SetAmsPort before saving the data.

This function block is a wrapper for FB_WritePersistentData. In case of any error, the function block uses AdsErrorCodes as ErrorId and uses ConvertTcErrIdToString to yield human-readable ErrorMessages. The timeout that is used for the function block can be controlled by the default-timeout parameter and the persistent mode is set to SPDM_VAR_BOOST, which saves data of individual persistent variables from the same cycle.

Please note, that this function block is "unmanaged" such that its Cycle method has to be called manually. There exists no implementation for a managed derivative of this function block because storing variables is usually performed at very specific occasions and thus, this design decision was made.

Constructor

FB_init 

METHOD FB_init (
 [input] bInitRetains : BOOL,
 [input] bInCopyCode : BOOL) : BOOL

This function block doesn't have a dedicated Booting phase. The constructor is used to initialize this object with its Idle state.

Inputs

bInitRetains BOOL

if TRUE, the retain variables are initialized (warm start / cold start)

bInCopyCode BOOL

if TRUE, the instance afterwards gets moved into the copy code (online change)

Returns

BOOL

Properties

BootDataLoaded 

PROPERTY BootDataLoaded : BOOL

This property returns TRUE if persistent variables were loaded correctly when starting the PLC. The property may return FALSE if no bootdata could be found on the system (typically when commissioning a machine) or if bootdata was not compatible to the PLC due to changes in data structure etc.

Warning

In contrast to SavePersistentDataAsync this property is not affected by the port that has been set with SetAmsPort. This property always considers the PLC where the function block is instantiated in.

Property Value

BOOL

Methods

Cyclic 

METHOD PUBLIC Cyclic ()

This method should be called every cycle to enable this class to operate. The method returns immediatelly if no task of the function block has been started (i.g. SavePersistentDataAsync. In case of errors, the function block transitions to its Error state and the details can be retrieved via the Object Interface. ErrorIds are using AdsErrorCodes. that are specified by Beckhoff.

IsOldBootDataLoaded 

METHOD IsOldBootDataLoaded () : BOOL

This method returns TRUE if .bootdata was invalid and the backup file .bootdata-old was loaded instead. This means that the file .bootdata for the PLC with the port, where this function block is initiated was not present when starting the PLC or the stored data in .bootdata was not compatible to the PLCs data structure, but .bootdata-old fulfilled both of these conditions.

Warning

In contrast to SavePersistentDataAsync this method is not affected by the port that has been set with SetAmsPort. This method always considers the PLC where the function block is instantiated in.

Returns

BOOL

SavePersistentDataAsync 

METHOD SavePersistentDataAsync ()

This method initiates saving of the persistent variables to .bootdata Per default the persistent variables of the PLC with port=851 is considered when saving the variables. However, by calling SetAmsPort the port can be overwritten.

SetAmsPort 

METHOD SetAmsPort (
 [input] amsPort : UINT)

(TwinCAT only) This method controls which PLC's persistent variables are saved when calling SavePersistentDataAsync. The parameter defaults to port=851, which is the default port for the first PLC in a TwinCAT 3 project. Call this method before issueing a save command.

Inputs

amsPort UINT := 851