FB_FileRingBuffer

FB_FileRingBuffer 1:

The FB_FileRingBuffer function block allows data records of varying lengths to be written into a ring buffer file, or for data records that have previously been written there to be removed from the ring buffer file. The file operates as a FIFO; data records are read from it in the same sequence in which they were first written into the ring buffer file. This means that the oldest entries are the first ones that are read. Opening, closing, writing, and reading the data records is controlled by action calls. The function block features the following tasks:

A_Open (Opens an existing ring buffer file to append the new data records, or to create a new file if it does not already exist. An error is not returned if the file is already open. )
A_Close (Closes an open ring buffer file. An error is not returned if the file is already closed. )
A_Create (Opens a new ring buffer file. If the file already exists, it is overwritten. An error is not returned if the file is already open.)
A_AddTail (Write a new data record into the ring buffer file. )
A_GetHead (Reads the oldest data record from the ring buffer file, but does not remove it – the data pointer is not moved to the next data record. )
A_RemoveHead (Reads and removes the oldest data record from the ring buffer file – the data pointer is moved on to the next data record.)
A_Reset (Deletes all the data records from an open ring buffer file. Only the data pointer and the number of data records are reset; the existing physical file size is not changed, although the oldest data records will be overwritten by new ones.)

When a ring buffer file that already exists is opened, the file header is read first. In a ring buffer file that has previously been closed without error, bit 0 in the header status (Header.status.Bit 0) must be zero. If not, it is assumed that the file was not properly closed beforehand, and the corrupt file is replaced by a new, empty file, while Header.status.Bit 1 is set to 1 (file corrupted). When the file is closed, Header.status.Bit 0 is set to 0, and the complete file header is updated in the file.

VAR_INPUT

VAR_INPUT
    sNetId      : T_AmsNetId := '';    
    sPathName   : T_MaxString := 'c:\Temp\data.dat';  
    ePath       : E_OpenPath := PATH_GENERIC;
    nID         : UDINT := 0; 
    cbBuffer    : UDINT := 16#100000; 
    bOverwrite  : BOOL := FALSE; 
    pWriteBuff  : DWORD; 
    cbWriteLen  : UDINT; 
    pReadBuff   : DWORD; 
    cbReadLen   : UDINT; 
    tTimeout    : TIME := DEFAULT_ADS_TIMEOUT;
END_VAR

sNetId: a string containing the network address of the TwinCAT computer where the buffer file is to be written or read can be given here. If it is to be run on the local computer, an empty string can be entered.

sPathName: contains the path and file name of the buffer file to be opened.

	The path can only point to the local computer’s file system! This means that network paths cannot be used here!

ePath:this input can be used to select a TwinCAT system path on the target device for opening the file.

nID: user-defined 32-bit value. When a new file is opened, this value is saved in the file and can be used, for instance, for checking the version of the buffer file.

cbBuffer: the maximum size, in bytes, of the buffer file that is to be open. This parameter is saved in the file header when the file is created, and is checked when the same file is opened again. You can only reopen files that have been created using the same maximum buffer size. You cannot, in other words, create a file with a smaller buffer size, fill it with data records, and then open it again with a larger buffer size. If the check of the maximum buffer size fails, a new file with the new buffer size is automatically created and opened. Bit 1 (file corrupted) is also set in the file header status.

bOverwrite: write behavior when the maximum file buffer size is reached. If this input is TRUE, the oldest entries are overwritten if the max. file buffer size has already been reached (entries are deleted until the free buffer size is sufficient to store the new entry). If this input is FALSE, a buffer overflow when the maximum file buffer size is reached is reported as an error.

pWriteBuff: the address of the PLC variable or of a buffer variable that contains the value data that is to be written. The address can be determined with the ADR operator. The programmer is himself responsible for dimensioning the buffer variable in such a way that cbWriteLen data bytes can be taken from it.

cbWriteLen: the number of value data bytes that are to be written (in the case of string variables this includes the terminating null).

pReadBuff: the address of the PLC variables or of a buffer variable into which the value data that has been read is to be copied. The address can be determined with the ADR operator. The programmer is himself responsible for dimensioning the buffer variable in such a way that it can accept cbReadLen data bytes. The size of the buffer variables in bytes must be greater than or equal to the size of the data record that is to be read.

cbReadLen: number of value data bytes to read. If the buffer size is too small, no data is copied, the function block reports a buffer underflow error and the required buffer size for the next record to be read is returned at the cbReturn output.

tTimeOut: states the timeout period that must not be exceeded when executing the ADS command.

VAR_OUTPUT

VAR_OUTPUT
    bBusy       :BOOL;
    bError      :BOOL;
    nErrId      :UDINT;
    cbReturn    :UDINT;
    stHeader    :ST_FileRBufferHead;
END_VAR

bBusy: When the function block is activated this output is set. It remains set until feedback is received.

bError: If an ADS error should occur during the transfer of the command, then this output is set once the bBusy output is reset.

nErrId : Supplies the ADS error number or the command-specific error code (table) when the bError output is set.

cbReturn: The number of value data bytes successfully read. If a read buffer underflow error has occurred, this output supplies the necessary read buffer size in bytes.

stHeader: Ring buffer file header/status.

Command-specific error codes	Error descriptions
0x8000	Writing: File buffer is empty. Reading: File buffer overflow.
0x8001	PLC application: read buffer underflow (pReadBuff, cbReadLen) has been dimensioned too small.
0x8002	Ring buffer file is closed and must be opened first.
0x8003	Input parameter has incorrect value.

It is not essential for the PLC application to know the binary structure of the file. The following illustration, however, shows the general structure of the ring buffer file used:

Header (48 bytes)

see the description of ST_FileRBufferHead

Length of data record 1 (4 bytes)

Data record 1

Length of data record 2 (4 bytes)

Data record 2

Length of data record 3 (4 bytes)

Data record 3

An empty ring buffer file only contains the header. The buffer itself follows the header. The variables Header.ptrFirst and Header.ptrLast point to the position immediately behind the header. Writing causes the ptrLast data pointer to be moved onwards. The ptrFirst data pointer follows the ptrLast data pointer during reading. When the maximum buffer size is reached the pointers are returned to the start of the buffer.

Example:

See: Example: File ring FiFo (FB_FileRingBuffer).

Requirements

Development environment	Target system type	PLC libraries to be linked
TwinCAT v2.10.0 Build > 1313	PC or CX (x86, ARM)	TcUtilities.Lib