Characteristics

CAA_FILENAME which is described in CAA_Types.lib should be usable for library CAA_File.lib in the following way:

• Separators in paths in CAA_FILENAME is the back-slash (“").
• Only absolute paths are allowed to use for file operation: drivename\directory\file.ext
• File and directory names have to be in standard DOS 8.3 notation without \ / : * ? “< > |
• Directory and file names may not contain whitespaces and are not case-sensitive.

Available drives for the use with this library are:

• Userdisk
• SD Memory Card
• Flashdisk – only on PM592-ETH (PLC with internal mass storage)
• SRAM Disk – only PM57x, PM58x, PM59x

Restrictions for the use of the drives are:

• Maximum file names: 8.3 filenames, e.g.: abcdefgh.123
• Maximum total path length: 255 characters
• Maximum file size: 4 GB -1 Byte
• Maximum number of simultaneous user handles (directories + files): 6 (PM55x) or 12 (PM57x,PM58x,PM59x)
• Maximum number of files in the root directory is limited (depends on memory location).

Behavior of CAA_File on Reset

A reset operation is executed if any user calls any online reset command or downloads a new application into the PLC. All file handles which are opened during execution of IEC application using FILE_Open and FILE_DirOpen will be closed after application reset. This assures that all handles opened by the user application will be closed and returned to the system. Please note that the application is not reset in case of a stop or an online change operation, so any file handle in IEC application is kept opened.

If a CAA_File Function Block is in BUSY state at the moment when reset command is executed the behavior of this Function Block is the following:

• If the request to file system which is executed by the Function Block is not yet processed by file system, the Function Block will be aborted. This means that the file operation will not be executed at all.
• If the file operation is already started and the corresponding Function Block does not support an abort command, the file operation will be finished and after that the corresponding file handle will be closed.
• If the file operation is already started and the corresponding Function Block supports an abort command (i.e. FILE_Write, FILE_Read, FILE_Copy) the file operation is aborted and after that the corresponding file handle is closed. Please refer to the description of abort for each Function Block for further details.

Usage of CAA_File Function Blocks and Online Changes

There are 2 Function Blocks in CAA_File.lib which use ADR operator to pass parameter from IEC program to Function Block. During design and maintenance of IEC application which uses these Function Block it is necessary to consider behaviour of these Function Blocks during online changes.

Example of a simple program:

As known during online change variables in IEC program could be relocated to different memory position. In this example, variable byaMessage could be relocated as well. All file operations which are invoked by CAA_File Function Blocks are executed in separate low priority task and pointer to read buffer (byaMessage in this example) is saved in context of this task during all file operation.

It means that if operation FILE_Write is not finished before online change some data could be lost or damaged, because pointer to buffer which is used for execution of file operation is not valid anymore.

The following recommendation could be done how to use FILE_Write and FILE_Read Function Block to avoid any problems after online change:

• Global variable or variable which is declared inside POU Program is only relocated if size of variable is changed. Any variable which is declared in POU Function Block is relocated even if data structure of Function Block is changed, e.g. any new variable is added to Function Block, any variable is deleted etc. So it is recommended to use for read/write buffer global variables and keep their size constant during online change or use variables which are declared in Function Block, but keep the structure of Function Block data unalterable.
• If any variable in application is relocated during online change the following message appears

Please check if any variable in your project which is used as write or read buffer does not present in this list. If variable is nevertheless here please check that xBusy output of appropriate Function Block is set to FALSE. If so, then online change is absolutely safe, otherwise you may meet the problems which are described above and it is recommended to avoid online change and postpone it for a while, till xBusy will not be set to TRUE.

Implementation Notes for CAA_File.lib

• Ensure that the file/directory handle is returned to the system (with FILE_Close/FILE_DirCLose) before discarding the local variable holding it.
• You cannot open a file with write access simultaneously.
• Only a successfully call to FILE_Close or FILE_Flush updates a file’s representation (i.e. size & content) on a device completely and definitely.
• All outputs of all Function Blocks will be invalidated, if xExecute is set to FALSE, thus they have to be read previously.
• Differing from Standard ABB libraries, CAA Function Blocks set EITHER xDone (i.e. FB finished without error) OR xError (i.e. FB finished with error).
• The path separator is a single backslash („\“), not a double backslash („\“) or a forward slash („/“).
• Both pointer and data contents handed over to read/write Function Blocks have to be stable during operation!
• CAA_File.lib works in binary mode, thus it reads and writes byte-wise. There is no automatic null-termination of the data of any kind, i.e. everything is a byte array: You hand over the starting address of the array and the number of bytes you want to have read/written from/to the array with the given starting address. The interpretation of the read data is up to the user application.
• Files and directory handles are only auto-closed in case of a application download or reset. A stop or online change of the IEC application does NOT close any file handles.

Notes on CAA_AsyncMan.lib

CAA_File.lib requires the additional library CAA_AsyncMan.lib. This library provides the means to handle all CAA_File.lib Function Blocks completely asynchronous. For each call to a CAA_File Function Block a so called “job” will be created. One task handles the job requests sent by the IEC application for each file I/O device in the AC500 PLC. These tasks run with a low priority, so the available file throughput depends on the other tasks running on the PLC - i.e. If the PLC is already completely busy doing communication, handling I/O Modules or calculation IEC tasks, the file operations might not be carried out. If a file I/O device is currently busy with an ongoing job request, new requests are queued and executed in a FIFO (“first in, first out”) manner.

Thus to understand the AC500’s file access system behaviour the user has to keep in mind that:

• Every file operation is done asynchronously in a separate worker task.
• There is one worker task per I/O device (e.g. userdisk, sdcard,…).
• The worker tasks have a low priority and thus might be blocked by other PLC processes.
• Each worker task has a FIFO-queue for the incoming jobs (i.e. triggered function blocks) for its I/O device.
• Most jobs cannot be interrupted or aborted once they are started (exceptions see function block descriptions).

These aspects result in the danger of priority inversion:

If a low priority task already triggered a file access job and another task with higher priority tries to access the same I/O device, the task with higher priority still will have to wait for the task with low priority to complete its job, i.e. the task priorities are inverted.

CAA_AsyncMan.lib can handle a maximum of 20 active function blocks in parallel. In this context, “active” means function block instances triggered via a rising edge and not yet reset by a falling edge on their input xExecute. If this limit is exceeded, additional triggered function blocks will return with undefined errors (e.g. “Invalid error 5802”).