IFile

Namespace: ZCore

Extends: ZCore.IObject

ZCore.IError

Inherited Properties: Busy

Done

Error

Error

Inherited Methods: ErrorSource

ErrorId

ErrorMessage

ErrorSource

TraceErrorStack

INTERFACE IFile EXTENDS ZCore.IObject, ZCore.IError

Encapsulation of various platform-dependent systemcalls that are dealing with files. The main purpose of the encapsulation is to make these systemcalls integral to the Zeugwerk Framework by allowing them to be used with Sequence.Await by implementing IObject.

As commonly done, throughout the framework, the actual tasks of this function block are suffixed with Async and follow the usual procedure.

Only 1 task may be active (if not documented differently for very specific tasks)
Starting a task may instantaneously fail (e.g. another task is already running), which can be tested with a StartToken when starting the task.
Task that have been successfully started can be polled for errors and tested for successful completion (see IObject)

The current implementation of this interface by Zeugwerk Framework may vary from platform to platform. For now on TwinCAT platforms there are the following file-actions available:

open a file (text mode and read, write, append access mode)
close a file
write data into a file
read read from a file
read a line from a text file until end of file is reached
retrieve some file info like size, creation time, modification time and access time
delete a file
rename a file

Properties

Eof

PROPERTY Eof : BOOL

Returns TRUE if a file was opened in text mode and all lines are read by ReadLineAsync.

Property Value

BOOL

FileInfo

PROPERTY FileInfo : REFERENCE TO FileInfoData

This property returns meta data for the file that was been passed to FileInfoAsync. The data returned by this property is only valid once the function block is done.

Property Value

REFERENCE TO FileInfoData

Opened

PROPERTY Opened : BOOL

This property can be used to check if a file has been opened and not been closed yet.

Property Value

BOOL

Methods

CloseAsync

METHOD CloseAsync (
 [input] startToken : IStartToken)

This method start a close task for the currently opened file handle. If no file handle is open when starting this method the function block will not get busy, but return instantaneously from this method.

If any task of this function block is already running when calling this method, it returns with an error. The later can be checked for with startToken. If startToken=0 is passed, the call may fail silently.

Inputs

startToken IStartToken

(optional) object to retrieve information about successful operation - may be 0

DeleteAsync

METHOD DeleteAsync (
 [input] startToken : IStartToken,
 [input] filePath : STRING)

This method start a delete task for the file that can be found in filePath. The method may run independently from the file that has been opened with OpenAsync. Keep in mind that a file whose file handle has been opened can not be deleted though.

Inputs

startToken IStartToken

(optional) object to retrieve information about successful operation - may be 0

filePath STRING

Fully qualified pathname including the drive letter (e.g. 'C:\path\logs\file.txt') or on unix based systems starting with \ root

FileInfoAsync

METHOD FileInfoAsync (
 [input] startToken : IStartToken,
 [input] filePath : ZString) : REFERENCE TO FileInfoData

Calling this method starts to read meta data for the file that is passed in filePath. Once the function block is done, said data can be retrieved by the property FileInfo or by the reference that is directly returned by this method, whatever is better to use in the context you are calling this from. When using the return of this method, make sure to store a reference to the returned type, because only when the function block is done it will contain the correct information.

Inputs

startToken IStartToken

(optional) object to retrieve information about successful operation - may be 0

filePath ZString

Fully qualified pathname including the drive letter (e.g. 'C:\path\logs\file.txt') or on unix based systems starting with \ root to the file which should be opened

Returns

REFERENCE TO FileInfoData

OpenAsync

METHOD OpenAsync (
 [input] startToken : IStartToken,
 [input] filePath : ZString,
 [input] access : FileAccessMode,
 [input] mode : FileOpenMode)

This method starts opening a file. If a file handle is already open when starting this method the function block will not get busy or any task of this function block is already running when calling this method, the method will not start any action. If startToken=0 is passed, the call may fail silently in the case of an error.

Inputs

startToken IStartToken

(optional) object to retrieve information about successful operation - may be 0

filePath ZString

Fully qualified pathname including the drive letter (e.g. 'C:\path\logs\file.txt') or on unix based systems starting with \ root to the file which should be opened

access FileAccessMode

Access mode to the file (read, write, append)

mode FileOpenMode

Describes if a file should be opened as textfile or as a binary

ReadAsync

METHOD ReadAsync (
 [input] startToken : IStartToken,
 [input] buffer : ZPointer,
 [input] bufferSize : UDINT,
 [inout] bytesRead : UDINT)

This method starts to read data a previously opened file by OpenAsync. The file must be opened in text mode or binary mode and ReadAsync can be called until Eof signals that the end of the file is reached.

The following code shows an example how to use the object to open a file, read all data in it and finally, close the file

PROGRAM MAIN
VAR
 _file : ZAux.FileUM;
 _step : ZCore.Step(10, 100);
 _text : STRING(2000);
 _bytesRead : UDINT;
END_VAR
=============================================================================================
CASE _step.Index
OF
10:
   IF _step.OnEntry() THEN
     _file.OpenAsync(0, 'C:\temp\file.log', ZCore.FileAccessMode.Read, ZCore.FileOpenMode.Text);   
   END_IF
  
   IF _file.Error THEN
     ;
   ELSIF NOT _file.Busy THEN
     _step.SetNext(20);
	END_IF
  
 20:
   IF _step.OnEntry() THEN
     _file.ReadAsync(0, ADR(_text), 1024, _bytesRead);
   END_IF 

   IF _file.Error THEN
     ;
   ELSIF _file.Eof() THEN
     _step.SetNext(30);
   ELSIF NOT _file.Busy THEN
     _step.RepeatStep();
   END_IF 

 30:
   IF _step.OnEntry() THEN
     _file.CloseAsync(0);   
   END_IF
  
   IF NOT _file.Busy THEN
     _step.SetNext(40);
   END_IF

 40:
   ;   
END_CASE
_file.Cyclic();

Inputs

startToken IStartToken

(optional) object to retrieve information about successful operation - may be 0

buffer ZPointer

address where data is written into

bufferSize UDINT

size of buffer in byte

InOuts

bytesRead UDINT

number of actual bytes that were read

ReadLineAsync

METHOD ReadLineAsync (
 [input] startToken : IStartToken,
 [input] length : UDINT,
 [inout] str : STRING)

This method starts to read a line of a previously opened file by OpenAsync. The file must be opened in text mode and ReadLineAsync can be called until Eof signals that the end of the file is reached.

In order to be sure to get the whole text out of the line at the current position (which starts at the first line after opening a file) it is important to provide a reasonably sized buffer by giving a reference to a string. As standard this is type of STRING(80) but can also be larger (e.g. STRING(1024))

To avoid copying to much data into a too small buffer also provide the size of the given buffer in order to stop copying at the right time. If the buffer size is to small for the read-line, the object will abort and signal an error.

Inputs

startToken IStartToken

(optional) object to retrieve information about successful operation - may be 0

length UDINT

maximum length of characters which should be read from the line, if the line is longer than the given buffer, the object will signal an error

InOuts

str STRING

provide a reasonable stringbuffer in order to have enough space to read the whole line, standard type is String, but also STRING(1024) may be provided here

RenameAsync

METHOD RenameAsync (
 [input] startToken : IStartToken,
 [input] fileNameOld : STRING,
 [input] fileNameNew : STRING)

This method start a rename task of the file in fileNameOld to fileNameNew. The method may run independently from the file that has been opened with OpenAsync. Renaming a file, whose handle is opened may fail, depending on the operating system.

Inputs

startToken IStartToken

(optional) object to retrieve information about successful operation - may be 0

fileNameOld STRING

Fully qualified pathname including the drive letter (e.g. 'C:\path\logs\file.txt') or on unix based systems starting with \ root to the file which should be renamed

fileNameNew STRING

Fully qualified pathname including the drive letter (e.g. 'C:\path\logs\file.txt') or on unix based systems starting with \ root to the new filename

WriteAsync

METHOD WriteAsync (
 [input] startToken : IStartToken,
 [input] bufferSize : UDINT,
 [input] buffer : POINTER TO BYTE)

This method starts writing into the file that has been opened previously with OpenAsync

Inputs

startToken IStartToken

(optional) object to retrieve information about successful operation - may be 0

bufferSize UDINT

Count of bytes which should be written to the previously opened file

buffer POINTER TO BYTE

Pointer to the bytes which should be written

Table of Contents

IFile

Properties

Eof

Property Value

FileInfo

Property Value

Opened

Property Value

Methods

CloseAsync

Inputs

DeleteAsync

Inputs

FileInfoAsync

Inputs

Returns

OpenAsync

Inputs

ReadAsync

Inputs

InOuts

ReadLineAsync

Inputs

InOuts

RenameAsync

Inputs

WriteAsync

Inputs