Topic: DMD0386
File System Reference
As of version 2.0, all of the Do-more CPUs include one or more file systems and a suite of instructions that allow users to create new files, read and write data in existing files, setup event-based, and time-based data logging to files, backing up the PLC's contents to a micro-SD Card, and restoring part or all of a PLC's project from a micro-SD card. Do-more PLCs have two file systems; the ones available depend on the family of hardware:
@RamFS All Do-more CPUs will have this file system available.
It is a 1 MB file system that is made from an unused section of the Do-more CPU's system RAM. Because this file system is in RAM, the contents of the @RamFS will be lost any time that power to the Do-more CPU is lost or any time the CPU performs a reboot using the Reboot PLC (REBOOT) instruction or when a firmware update is applied - because it requires a power-cycle.
The RAMFS allows a maximum of 512 files and folders in the root folder, and a maximum of 1500 files and folders in each sub-folder.
@SDCardFS Do-more CPUs that have a micro-SD card slot will use this file system on the removable media in that slot.
This file system is automatically created and mounted when the removable media is inserted into the micro-SD card slot. The $SDCardFS.MediaInstalled and $SDCardFS.MediaMounted bits will be ON if there is a functional file system available in the micro-SD slot.
This file system only uses FAT32 formatted media, which means the micro-SD card must be formatted in a PC before it can be used in a Do-more CPU. This also means you are limited to 32GB micro-SD media; any media larger than that must be reformatted to FAT32. Micro-SD media formatted as NTFS or exFAT will not mount properly and the MEM LED on the CPU will remain RED after inserting the media.
This file system allows a maximum of 1500 files and folders in both the root folder and in each sub-folder.
The Do-more Simulator uses a folder in <Public Documents>\Do-more\DesignerX_Y\Bin\SDCard to simulate media in the SDCard slot. Use Windows Explorer to manage the folders and files created by the Simulator.
Note: Because the Do-more file system supports long file names, any time the filename is longer that 8 characters in the name plus 3 characters in the file extension, the entry in the FAT (file allocation table) for this file will use the long file name format. This format will get the required additional space for the file name from the FAT. The result of using long file names is there wont be space in the FAT for the full complement of files and folders. The exact number of files and folders that can be created in a folder is largely dependent on how long the file and folder names are.
File System Utilities
Do-more Designer includes a utility program called Browse PLC File Systems that can be used to view and change the contents of the two file systems. You can browse the contents of the folders on the file system, copy files from the PLC to the PC running Do-more Designer and from the PC down to the PLC. You can also delete files on the PLC file system. As of now this is the only way to get files onto one of the file systems in the CPUs from a PC.
You can Backup some or all of the contents of the PLC to micro-SD using the BACKUP - System Backup instruction or the Create PLC Image File utility. The image file created by the system backup processed can be restored from a micro-SD card during a reboot. That process is also described in the Backup and Restore using micro-SD Card help topic.
You can also use the EMAIL - Send Email instruction to send a file from either of the file systems as an attachment to an email message.
Instruction Set for File Operations
The Do-more CPUs have a full suite of instructions for managing files and folders on the file systems.
FILECLOSE - Close File - close access to a file that was previously open.
FILECOPY - Copy File - make a copy of the contents of a file on one of the file systems to a second file on one of the file systems.
FILEDEL - Delete File - remove an existing file or an existing directory from one of the file systems.
FILELOG - Log to File - store PLC data in a file at a recurring interval or when triggered by an event.
FILENEWFLDR - Make New Folder - create a folder on one of the existing file systems.
FILEOPEN - Open File - open an existing file or create a new file on one of the existing file systems and create a File Handle that will be used by other FILE instructions.
FILEQUERY - Query File or Folder Information - retrieve status information about the files and folders on a file system.
FILEREAD - Read from File - retrieve data from a file that has been opened with the FILEOPEN - Open File instruction.
FILESEEK - Seek to Position in File - manually move the file pointer forward (toward the end of the file) or backward (toward the beginning of the file).
FILESYSCMD - Perform File System Command - is used to execute system level functions on the RAM and SDCard file systems, for example Format, Eject, Mount, etc.
FILETRUNC - Truncate File - delete the contents of the specified file from the current location of the file pointer to the end of the file.
FILEWRITE - Write to File - send data to a file that has been opened with the FILEOPEN - Open File instruction.
File System Structure
Each file system has an associated structure that contains the following member fields which can be used in the ladder logic to perform system-level operations and to make sure the file system is ready for use before an attempt is execute any of the file instructions.
Each File System structure contains the following member fields which can be used in the ladder logic.
FolderEntryNum (read only) - a 16-bit value that shows the number of files and folders found after scanning the contents of a folder.
StartFolderScan - a boolean value that is set ON to initiate a folder scan operation.
FolderScanDone - a boolean value that will be ON at the completion of a folder scan operation.
Note: the above three structure members are only used by the FILEQUERY - Query File or Folder Information instruction to generate a list of the files and folders contained in a folder on one of the file systems. Refer to the Folder Iteration example program in the help topic for FILEQUERY for instructions on how to properly use them.
RemovableMedia (read only) - a boolean value that will be ON if the file system has a slot for removable media, for example, a slot for a micro-SD card.
MediaInstalled (read only) - a boolean value that will be ON if the file system has file system with removable media has that media installed, for example a micro-SD card is installed.
MediaMounted (read only) - a boolean value that will be ON if the file system with removable media has that media installed and the file system on that media has been successfully mounted and is ready for access by the FILE instructions, for example, a formatted micro-SD card is installed.
FreeSpaceKB (read only ) - a 32-bit value that shows the total amount of unused space (in KB) on the File System.
TotalSpaceKB (read only) - a 32-bit value that shows the total amount of usable space (in KB) on the File System.
File Handle Structure
A File Handle is memory that contains information about the current state of a file on one of the PLC File Systems. Each time a Open File (FILEOPEN) instruction is executed the File Handle structure is initialized. As other File System instructions are used to operate on the file, the contents of the File Handle structure are updated. The contents of the structure's fields will remain valid until a Close File (FILECLOSE) instruction is executed for the File Handle.
Each File Handle structure contains the following member fields which are used by some of the other File System instructions to read and write the contents of the file:
.DeviceID (read only) - an Unsigned Word (16-bit) value that uniquely identifies this file handle.
.Open (read only) - a boolean value that will be ON if the associated file is currently open, and will be OFF if the associated file is not open.
.Success (read only) - not used.
.Error (read only) - not used.
.EndOfFile (read only) - a boolean value that will be ON if the file pointer is at the end of the file, that is, after the last byte of data in the file.
.FileSize (read only) - a Signed DWord (32 bit) value that contains the current number of Bytes in the file.
.FilePointer (read only) - a Signed DWord (32 bit) value that contains the current location (Byte offset from the beginning) of the file pointer.
File System Error Codes:
Improper use of any FILE instruction or any file system hardware problem will generate a warning message at runtime. When any of these warnings are generated, the On Error parameter in the instruction will be ON and the System ERR variable will contain one of the following text messages. You will also be alerted to this condition by yellow "Warning" text displayed in the Status Bar of Do-more Designer. Clicking that text will open the System Status to display the full text of the warning message.
|
Text displayed in the ERR System variable
|
How To Solve / What To Do |
FILE Instructions Affected |
|
SdCard not installed, or has an error
|
On PLC systems that have an SD Card slot, this indicates the SD card is either missing or an error occurred while trying to mount the file system on that media.
|
FILEQUERY - Query File or Folder Information
FILESEEK - Seek to Position in File
FILESYSCMD - Perform File System Command
|
|
File wasn't found
|
The File Name specified could not be located not on the specified File System. It could be spelled wrong, or it could be located in a sub-folder that is not specified, or located on a different File System.
|
FILEQUERY - Query File or Folder Information
|
|
File access denied
|
An attempt to access a file that is marked as either Read-Only or as a System file.
|
FILEQUERY - Query File or Folder Information
|
|
Attempted to use a device that hasn't been opened
|
An attempt was made to truncate a file that is currently open but the file itself has been deleted.
|
FILESEEK - Seek to Position in File
|
|
Attempted to open a device that is already open
|
An attempt was made to open a file that is currently open with a different File Handle or an attempt was made to open a file with a File Handle that is currently in use.
|
FILEQUERY - Query File or Folder Information
|
|
File system is full
|
An attempt was made to add data to an existing file or to create new file but there is insufficient space on the specified File System to perform the operation.
|
FILEQUERY - Query File or Folder Information
|
|
Directory is full
|
An attempt was made to create a new file but there is insufficient space in the FAT of the specified File System to perform the operation.
Note: Because the Do-more file system supports long file names, any time the filename is longer that 8 characters in the name plus 3 characters in the file extension, the entry in the FAT (file allocation table) for this file will use the long file name format. This format will get the required additional space for the file name from the FAT. The result of using long file names is there wont be space in the FAT for the full complement of files and folders. The exact number of files and folders that can be created in a folder is largely dependent on how long the file and folder names are.
|
FILEQUERY - Query File or Folder Information
|
|
Unknown error
|
An attempt to open a file in a folder when that folder does not exist, for example trying to open \MyFolder\MyFile.txt when \MyFolder doesn’t exist.
|
FILEQUERY - Query File or Folder Information
|
See Also
Related Topics
EMAIL - Send Email (with file attachment)
Backup and Restore using micro-SD Card