Table of Contents

LoggerFile7FFUM

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)

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

As the LoggerFile7FF this class has cyclic behavior and therefore has to be called cyclically. However, here is no parent which does the actual work by calling the cyclic method and so it needs to be called every PLC-cycle manually somewhere in your application. Please make sure to do this really every PLC cycle otherwise the Logger wont perform well. The usual way is to call this cyclic somewhere in the MAIN Program on top or at the end.

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.

The following example can be used to easily instantiate a logger and use it in an application for first steps and tests

PROGRAM MAIN
VAR
  DateTime : ZAux.DateTimeUM;
  Logger : ZAux.LoggerFile7FFUM(datetime:=DateTime, filePath:='C:\temp\logfile.log', target:='');
  Step : ZCore.Step(0, 100);
END_VAR
-------------------
DateTime.Cyclic();
Logger.Cyclic();

CASE Step.Index OF
  0:
    IF Logger.Operational
    THEN
      Logger.Info('Appliation started');
      Step.SetNext(10);
    END_IF

  10:
    ;
END_CASE

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

Constructor

FB_init

The initialization 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. Here no parent has to be provided because the cyclic methode has to be called somewhere in the application manually every PLC-cycle.

Note

Construction of a Functionblock 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 here are not changed anymore. For changing parameters during an active PLC runtime, please use the according methods.

METHOD FB_init (
 bInitRetains : BOOL,
 bInCopyCode : BOOL,
 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)

datetime IDateTime

See SetDateTime

filePath ZString

See SetFilePath

target ZString

For TwinCAT, AMS-Net-Id string (e.g. 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

Cyclic

This method has to be called every PLC cycle, it performs all the work that is needed to write into a logfile.

METHOD Cyclic ()

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