Table of Contents

LoggerFile7FF

Namespace
ZAux
Extends
Inherited Properties
Inherited Methods
Implements

Implements a rolling-file logger that outputs every entered log message as Ascii Text into a *.log file at a desired location on the local harddisk. For Beckhoff Twincat systems it is also possible (if there is a route configured) to log to a remote target somewhere else in your environment.

During instantiation of this class one has to provide

  • a datetime class, otherwise the timestamp property of every log message is 0
  • a filepath which is writeable for the Logger-instance (usually System user under which the plc-runtime is working)
  • a target on which the file will be created (if empty it is the local file system)
  • a parent which is calling the internal cyclic method cyclically to keep the logger working

While writing Files, the Logger is rolling the files if the desired file size set by MaxBytes setting in RolloverPolicy is reached.

Performance hints: This Logger is doing well on a normal industrial PC and can write about 1-5 mbyte/second, of course always depending on the usual load of your system and your configured hard drive (ssd, or normal hard drive). However, if your PLC is running at a very low pace (e.g. smaller than 1 Millisecond), try not to make too many log messages per cycle because string operations on a PLC system (usually real-time system) are always very expensive on a performance perspective. For more information here, please dont mind and contact us on how to deal with logs properly.

FUNCTION_BLOCK LoggerFile7FF EXTENDS ZAux.Logger IMPLEMENTS ZCore.ILogger, ZCore.ILoggerBase, ZCore.ILoggerImperativeApi, ZCore.ILoggerFluentApi

Constructor

FB_init

The initialisation of the LoggerFile7FF class is very easy because all necessary buffers and other needed FB's are stored internally. Here the most important properties are given through FB_init. Additionally to the LoggerFile7FFUM class, here one has to provide a parent which is then responsible for calling the cyclic method to keep the logger active.

Note

Construction of a function block is executed before actually starting the PLC and therefore only done once at startup. It is also not possible to set a breakpoint here. If there is any parameter changed by logging in to the PLC with an Online Change these parameters are not changed anymore. For changing parameters during an active PLC runtime, please use the according methods like SetFilePath or SetTarget

METHOD FB_init (
 bInitRetains : BOOL,
 bInCopyCode : BOOL,
 parent : ZCore.IManagedObject,
 datetime : ZCore.IDateTime,
 filePath : ZCore.ZString,
 target : ZCore.ZString) : BOOL

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)

parent IManagedObject

Interface to the ManagedObject that is the parent of this object

datetime IDateTime

See SetDateTime

filePath ZString

See SetFilePath

target ZString

If supported a file target other than the local hard drive (e.g. for TwinCAT-Systems, AMS-Net-Id string (as an example: 200.200.210.4.1.1)).

Returns

BOOL

Properties

Diagnostics

If a problem on exporting messages is present (indicated by the Operational property), the error message is shown in this variable. (eg. For Beckhoff systems most errors are ADS-Error-Messages like Device has a timeout.

PROPERTY Diagnostics : ZCore.ZString

Property Value

ZString

LostEntries

If the logger cannot export all messages fast enough to make the buffer empty, this counter will be increased. This usually happens if there are log messages entered in every PLC cycle. In most cases this can be avoided by using a rising or falling trigger to enter a logmessage.

PROPERTY LostEntries : UDINT

Property Value

UDINT

Operational

This Property gets TRUE when the Datetime implementation is initialized and logger is ready for operation. Log messages can be entered before Datetime is initialized, but then the saved timestamp for this message is not correct and therefore 0. Use this method to wait in your applications initialization sequence until the logger is ready and then move on with your initialization

PROPERTY Operational : BOOL

Property Value

BOOL

RolloverPolicy

This property allows to set when the appender is rolling over to the next file.

Calculation of rollover times is done only when rollover occurs, and rollover occurs only when emitting output. If this is not kept in mind, it might lead to some confusion. For example, if an interval “every minute” is set in the time-based policy, that does not mean you will always see log files with times (in the filename) separated by a minute; if, during application execution, logging output is generated more frequently than once a minute, then you can expect to see log files with times separated by a minute. If, on the other hand, logging messages are only output once every five minutes (say), then there will be gaps in the file times corresponding to the minutes where no output (and hence no rollover) occurred.

PROPERTY RolloverPolicy : REFERENCE TO LoggerRollingFileAppenderRolloverPolicy

Property Value

REFERENCE TO LoggerRollingFileAppenderRolloverPolicy

UtcOffset

This method can be used to influence the timezone that the logger appender uses when writing entries to a file. By default, the file appender logs messages with the localtime zone, which means that UtcOffset = -_datetime.Bias, e.g. for CEST UtcOffset=7200000 ms. Use UtcOffset=0 to let the appender log to a file with the UTC timezone. The unit of this property is milliseconds.

PROPERTY UtcOffset : LINT

Property Value

LINT

Methods

DoRollover

Calling this method ensures that the appender is rolling over to the next file before writing the next message to the logfile. This by-passes the settings of the rollover policy.

METHOD DoRollover ()

SetDateTime

Sets a Zeugwerk compatible DateTime function block that is used by the predefined logging-methods to automatically fill the timestamp property of a log message. If intrf=0 the timestamp of every message that is logged is 0.

METHOD FINAL SetDateTime (
 intrf : ZCore.IDateTime)

Inputs

intrf IDateTime

Interface to an instantiated Zeugwerk Framework compatible DateTime function block

SetFilePath

This method can be used to overwrite the path that is set when constructing an instance of this object. The filepath considers the remote target of this logger.

filepath should contain the absolute path to the file that should be logged to. The rolling-file mechanism appends a number to this path, if the file size exceeds the maximum size per file.

If file rolling is activated, the old files get a .<fileno> extension right before the log file extension. For instance, if the logger uses 10 rotated files, and filePath=C:\logs\messages.log, the latest logs are actually written to C:\logs\messages.log, however, the oldest log messages can be found in C:\logs\messages.10.log, provided that all 10 files are utilized already. If there is no log file extension provided, the old-file-number will be added as suffix to the filename like C:\logs\messages.10.log.

The file logger will automatically create the file path and the file including all folders on the hard drive if possible (all necessary access rights have to be provided). However, logging to Windows or Unix compatible targets will need to give different file paths. For example on a Codesys-Raspberry-Pi target the file path has to be \home\pi\logs\messages.log where as an a Windows machine it has to be C:\temp\messages.log.

METHOD FINAL SetFilePath (
 filePath : ZCore.ZString)

Inputs

filePath ZString

File path to the actual log file on the target harddrive or memory. For Windows systems the drive has to be provided, for linux systems the absolute path has to be provided

SetTarget

Target system where the log files should be written to. For Beckhoff Twincat specific PLC-Runtimes this should be given as a AMS-Net-Id string (e.g. '200.200.210.4.1.1'). On Codesys targets there is unfortunately no easy way to log to external targets.

METHOD FINAL SetTarget (
 target : ZCore.ZString)

Inputs

target ZString

target machine on which the log files should be created; For Beckhoff Twincat targets provide the AMS-Net-ID here.

SetTimeout

Sets the timeout for unresponsive targets. This is usually relevant if the target is not the local PLC or if an external file is blocking a file that the Logger tries to access.

METHOD SetTimeout (
 timeout : LREAL)

Inputs

timeout LREAL

Timeout in seconds for alle system relevant function blocks