Command FILE
 
Description File handling commands for SD/SDHC Card and NAND Flash - v49.16.

These commands support the file input/output operations, such as file open, file read, file write, file close, file delete, etc. File and path names can be supplied either as immediate strings or via text variable entities. More complicated file names can be constructed with concatenation of text, strings, pointers, numbers etc using the file "MKFN" command. Details on directory name and file name construction can be found below in File and Directory Names.

Also the use of the file object, used to maintain an association with an open "stream" when reading from and writing to the SD/SDHC card can be found below in File Object Variable. Data is read from and written to files in multiples of bytes. The order the data bytes are read/written and the conversion of the bytes (eg ASCII or binary) can be specified during setting up of the File Object Variable.

To allow the user to manage file error conditions without causing a system error, every FILE() command returns an optional file result (fileRes) of the file action, eg "File Not Found" or "Access Denied". This is returned as an error number or a configurable text string. See more about fileRes below.

Each command is explained along with a simple example. More in-depth examples using combinations of FILE() commands can be found below in File Examples.

File and Directory Names

SD/SDHC card
Supports long file names and unlimited directories with the following limitations:
  Maximum file name length is 256 characters,
  Maximum path name length is 8191 characters (including the SDHC/),
  Directory depth is unlimited but must fit in pathname length.
  The pound '£' symbol is not supported.
File names take the format:
  "SDHC/dir1/dir2/longFileName.ext"

NAND
Supports 8.3 file names only. Subdirectories are not supported in the NAND.
File names take the format:
  "NAND/filename.ext" for automatic placement in NAND (menu files in NANDMNU, others in NANDLIB).
  "NANDLIB/filename.ext" for placement in NANDLIB area (where files are expected to be rarely updated).
  "NANDMNU/filename.ext" for placement in NANDMNU area (where files are expected to be frequently updated). 

File Object Variable
When a file is to opened, read or modified in stages and then closed, the file system associates these actions with a "stream" that can identified in future actions by a file object. The user must create a unique file object variable for each open file, though the variable can be reused once a file has been closed.
You can create a file object variable with built in data styles FILEASC or FILEBIN.

  VAR( name, 0, FILEASC ); // name is a file object variable with data read/write as ASCII
  VAR( name, 0, FILEBIN ); // name is a file object variable with data read/write as binary (raw)

You can also create your own file styles to alter the way data bytes are read/written. The encode property determines how this data is managed. Refer to the data styles for the VAR() command for the options. The predefined styles are:

  STYLE( FILEASC, data ) { type=file; encode=sr; } // This will store a varU8 = 12 as two bytes \\31\\32
  STYLE( FILEBIN, data ) { type=file; encode=sd; } // This will store a varU8 = 12 as one byte \\0C

The visibility property can be checked to see if the file object variable is currently assigned to a file stream. An assigned variable is "visible", and unassigned variable is not "visible".

  CALC( res, varFileObj, "EVIS" ); // res is 1 if varFileObj is in use. 
 
Syntax/Parameters FILE(....)
 
Options Click "Function" to see more details on the selected file function
  
"APPEND" - Append data to 'filename'.
"CLOSE" - Close an open file on SD/SDHC.
"COPY" - Copy a file.
"DATE" - Get file time and date.
"DELETE" - Delete a file.
"EXISTS" - Check whether a file or directory exists.
"FREE" - Check Free bytes on SD card
"GETPOS" - Get current read/write position in the file.
"MKDIR" - Make a directory on SD/SDHC.
"MKFN" - Make a file name from a list of entities and strings.
"OPEN" - Open a file on SD/SDHC for read/write/append/overwrite.
"READ" - Read data from an open file on SD/SDHC.
"READALL" - Read data from 'filename'.
"RENAME" - Rename/Move a file.
"SAVE" - Save media (eg image) to a file.
"SETPOS" - Set new read/write position in the file.
"SIZE" - Get file size.
"WRITE" - Write data to an open file on SD/SDHC.
"WRITEALL" - Write data to 'filename'.


File Result (fileRes)

Every FILE() command returns an optional file result (fileRes) of the file action. This allows the user to manage file error conditions without causing a system error. System errors will still occur for syntax errors and file system unrelated errors.
If fileRes is specified and is a numeric variable then an error number is returned. If fileRes is a text entity or text variable entity then a text string for the error is returned. These strings are preconfigured in text variable entities but can be changed by the user (eg to support different languages). The following table summarises the file results.
Number Default Text String Entity Name File Result Description
0 "OK" FILERES0 OK. No error - the function succeeded
1 "Disk I/O Layer Error" FILERES1 Disk Error. An unrecoverable error occurred in the lower layer (disk I/O functions)
2 "Assertion Failed" FILERES2 Internal Error. Assertion failed
3 "Physical Drive Error" FILERES3 Not Ready. The physical drive cannot work
4 "File Not Found" FILERES4 File Not Found. Could not find the file
5 "Path Not Found" FILERES5 Path Not Found. Could not find the path
6 "Invalid Path Name" FILERES6 Filename Error. The path name format is invalid
7 "Access Denied" FILERES7 Access Denied. Access denied due to prohibited access or directory is full
8 "File Already Exists" FILERES8 File Exists. Any object that has the same name is already existing
9 "Invalid File Object" FILERES9 Not Object. The file/directory object is invalid
10 "Write Protected" FILERES10 Write Protected. The physical drive is write protected
11 "Invalid Drive" FILERES11 Invalid Drive. The logical drive number is invalid
12 "No Work Area" FILERES12 Not Enabled. The volume has no work area
13 "No FAT Filesystem" FILERES13 Not FAT. There is no valid FAT volume
14 "Make Filesystem Failed" FILERES14 MKFS Aborted. (Not supported)
15 "Timeout" FILERES15 Timeout. Could not get a grant to access the volume within defined period
16 "Locked Out" FILERES16 Locked. The operation is rejected according to the file sharing policy
17 "LFN Buffer Overflow" FILERES17 No Buffer. LFN working buffer could not be allocated
18 "Too Many Open Files" FILERES18 Too Many Open Files. Number of open files > 5
19 "Invalid Parameter" FILERES19 Invalid Parameter. Given parameter is invalid

The error strings in FILERES0 to FILERES19 are variables of type TXT and have a maximum length of 32 characters. They can be accessed and changed, as any other text variable. For example:
  LOAD( FILERES4, "File was not found!" ); // Change default "File Not Found" message
  TEXT( txtName, FILERES1 );; // Display the Disk Error message on the screen

Maximum simultaneous open files - v49.19
Increased maximum simultaneous open files to 8 (this includes menu files, images, as well as those opened with FILE() command).

File Tests - v49.32
Tests added to check filename length when reading/writing to NAND. Note maximum length is 15 characters.

Potential Future Commands - Not Yet Supported
These commands are not implemented but could be made available in future development depending on customer demand.
FILE( "DIR", [fileRes], dst, [format], pathName ); // Formatted directory listing
FILE( "APPENDLN", [fileRes], fileObj, fileName, [numWritten], data [, data [, ...]] ); // Open, Append Line, Close File (given fileName)
FILE( "READLN", [fileRes], fileObj, [numRead], data [, numToRead] ); // Read Line (given open fileObj)
FILE( "STATUS", [fileRes], fileName ); // Get File Status
FILE( "WRITELN", [fileRes], fileObj, [numWritten], data [, data [, ...]] ); // Write Line (given open fileObj)
FILE( "WRITELN", [fileRes], fileObj, fileName, [numWritten], data [, data [, ...]] ); // Open, Write Line, Close File (given fileName) 
 
Example File Examples

Example 1 - Simple Logging

  VAR( varFileObj, 0, FILEASC ); // Create a file object variable
  FUNC( fncLogStatus )
  {
      FILE( "APPEND", varRes, varFileObj, "SDHC/logs/log1.txt",,, varTime, ": ", varTemperature1, "\\0d\\0a" );
      IF( varRes != 0 ? fncReportError );
  }

Example 2 - Running a Log with Dated File Name

  VAR( varFileObj, 0, FILEASC ); // Create a file object variable
  VAR( varDay, -1, S16 ); // Variable to store time last log was made
  VAR( varS32Tmp, 0, S32 ); // Variable for temporary storage
  VAR( varTxtRes, "", TXT ); // Text variable for file result
  VAR( varTxtTmp, "", TXT ); // Text variable for temporary storage
  FUNC( fncTimerExpired )
  {
      LOAD( varS32Tmp, RTCHOURS );
      IF( varDay != varS32Tmp ? fncOpenLogFile );
      FILE( "WRITE", varTxtRes, varFileObj,,,varLogData1, varLogData2, "\\0a" );
      IF( varTxtRes != "OK" ? [ LOAD( RS2, "Log File Write Error: ", varTxtRes, "\\0d\\0a" ); ] );
  }
  FUNC( fncOpenLogFile )
  {
      LOAD( varDay, RTCHOURS );
      CALC( varS32Tmp, varFileObj, "EVIS" );
      IF( varS32Tmp == 1 ? [ FILE( "CLOSE", , varFileObj ); ] );
      FILE( "MKFN", varTxtRes, varTxtTmp, "SDHC/logs/log", varDay, ".txt" );
      IF( varTxtRes != "OK" ? [ LOAD( RS2, "Log File Name Error: ", varTxtRes, "\\0d\\0a" ); ] );
      FILE( "OPEN+W", varTxtRes, varFileObj, varTxtTmp );
      IF( varTxtRes != "OK" ? [ LOAD( RS2, "Log File Open Error: ", varTxtRes, "\\0d\\0a" ); ] );
  }
  INT( intTmr0, TIMER0, fncTimerExpired ); // Call function every minute
  LOAD( TIMER0, 60000, 0 ); // Create a 1 minute repetitive timer
 

Command FILE - "APPEND"
 
Description Append data to a file on SD/SDHC. Opens file, appends data to the end of the file, closes the file. Use "WRITE" if the file is already open.
 
Syntax/Parameters FILE( "APPEND", [fileRes], fileObj, fileName, [numWritten], [numToWrite], data [, data [, ...]] );
 
Options "APPEND" - Append data to file. - Immediate string.
fileRes - Result of file operation. See File Result. (optional) - Entity Name of numeric variable (U8, U16 etc), text variable, text.
fileObj - File object variable. See File Object Variable. - Entity name of file object variable.
fileName - File name. See File and Directory Names. -Immediate string or text variable of file name.
numWritten - Number of bytes written to file. (optional) - Entity Name of numeric variable (U32 etc).
numToWrite - Maximum number of bytes to write to file. (optional) - Entity Name of numeric variable (U32 etc).
data - One of more sets of data to write to file. - Immediate strings or numbers plus entity names of text or numeric variables or pointers to variables.
 
Example   FILE( "APPEND", txtVarRes, varFileObj, "SDHC/logs/mylog1.txt", , , "Hello", " World: ", varCount, "\\0a" );
  FILE( "APPEND", , varFileObj, varFileName, varNumBytes, 1024, varData ); 
 
Command FILE - "CLOSE"
 
Description Close an open file on SD/SDHC.
 
Syntax/Parameters FILE( "CLOSE", [fileRes], fileObj );
 
Options "CLOSE" -Close file. - Immediate string.
fileRes - Result of file operation. See File Result. (optional) - Entity Name of numeric variable (U8, U16 etc), text variable, text.
fileObj - File object variable. See File Object Variable. - Entity name of file object variable. 
 
Example   FILE( "CLOSE", txtVarRes, varFileObj1 );
  FILE( "CLOSE", , varFileObj4 ); 
 

Command FILE - "COPY"
 
Description Copy a file from SD/SDHC to SD/SDHC or between SD/SDHC and NAND.
 
Syntax/Parameters FILE( "COPY", [fileRes], dstFileName, srcFileName ); // Copy File - doesn't copy and reports error if file exists
FILE( "COPY+O", [fileRes], dstFileName, srcFileName ); // Copy File - overwrites file if it exists
 
Options "COPY" - Copy source file to destination file if destination file does not exist. - Immediate string.
"COPY+O" - Copy source file to destination file and overwrite if destination file already exists. - Immediate string.
fileRes - Result of file operation. See File Result. (optional) - Entity Name of numeric variable (U8, U16 etc), text variable, text.
dstFileName - Destination file name. See File and Directory Names. - Immediate string or text variable of file name.
srcFileName - Source file name. See File and Directory Names. - Immediate string or text variable of file name. 
 
Example   FILE( "COPY", varRes, "NAND/tree.bmp", "SDHC/images/A Tree Somewhere.bmp" );
  FILE( "COPY+O", , varDstName, varSrcName ); 
 

Command FILE - "DATE"
 
Description Get file date and time.
 
Syntax/Parameters FILE( "DATE", [fileRes], dst, [format], fileName );
 
Options "DATE" - Get formatted file time and date. - Immediate string.
fileRes - Result of file operation. See File Result. (optional) - Entity Name of numeric variable (U8, U16 etc), text variable, text.
dst - Formatted file time and date. - Entity Name of text variable.
format - Format of time and date. See Date Format. Default formatting will apply if not supplied (optional) - Immediate string or text variable of format.
fileName - File name. See File and Directory Names. - Immediate string or text variable of file name.

If the file does not exist or there is a file error then the default date is returned Saturday 1st January 2000 00:00:00.
 
Example

  FILE( "DATE", varRes, varTxt, "d M Y H:i:s", "NAND/tree.bmp" );
  FILE( "DATE", , varTxt, "Y", varSrcName ); 
 

Command FILE - "DELETE"
 
Description Delete a file on SD/SDHC or NAND.
 
Syntax/Parameters FILE( "DELETE", [fileRes], fileName );
 
Options "DELETE" - Delete file. - Immediate string.
fileRes - Result of file operation. See File Result. (Optional) - Entity Name of numeric variable (U8, U16 etc), text variable, text.
fileName - File name. See File and Directory Names. - Immediate string or text variable of file name.
 
Example   FILE( "DELETE", varRes, "SDHC/music/A-Nice-Bit-Of-Music.wav" );
  FILE( "DELETE", , varFileName );
 

Command FILE - "EXISTS"
 
Description Check whether a file or directory exists.
 
Syntax/Parameters FILE( "EXISTS", [fileRes], [dst], fileName );
 
Options "EXISTS" - Check if file or directory exists. - Immediate string.
fileRes - Result of file operation. See File Result. (Optional) - Entity Name of numeric variable (U8, U16 etc), text variable, text.
dst - Result of file existence check.  0 = File/path does not exist.  1 = File/path exists. - Entity Name of numeric variable (U8, U16 etc), text variable, text.
fileName - File name or path name. See File and Directory Names. - Immediate string or text variable of file/path name.

This command returns a fileRes of 0 ("OK") if the file/path exists or a fileRes of 4 ("File Not Found") or 5 ("Path Not Found") if the file/path does not exist. Other fileRes values will be returned for disk errors etc.
 
Example   FILE( "EXISTS", varRes, varExists, "SDHC/music/A-Nice-Bit-Of-Music.wav" );
  FILE( "EXISTS", , varExists, varFileName ); 
 

Command FILE - "FREE" - v49.50
 
Description Finding free space on SD card
 
Syntax/Parameters FILE( "FREE", [fileRes], [dst], "SDHC/" );
 
Options "FREE" - Check if file or directory exists. - Immediate string.
fileRes - Result of file operation. See File Result. (Optional) - Entity Name of numeric variable (U8, U16 etc), text variable, text.
dst - Result of file existence check.  0 = File/path does not exist.  1 = File/path exists. - Entity Name of numeric variable (U8, U16 etc), text variable, text.
 
Example   FILE( "FREE", varRes, varFree, "SDHC/" ); 
 

Command FILE - "GETPOS"
 
Description Get the current read/write position in the open file on SD/SDHC.
 
Syntax/Parameters FILE( "GETPOS", [fileRes], fileObj, posn );
 
Options "GETPOS" - Get current read/write position. - Immediate string.
fileRes - Result of file operation. See File Result. (Optional) - Entity Name of numeric variable (U8, U16 etc), text variable, text.
fileObj - File object variable. See File Object Variable. - Entity name of file object variable.
posn - Current absolute read/write position from start of file. - Entity Name of numeric variable (U8, U16 etc), text variable, text.
 
Example   FILE( "GETPOS", varRes, varFileObj3, varU32 );
  FILE( "GETPOS", , varFileObj, varPosn ); 
 

Command FILE - "MKDIR" - v49.18
 
Description Make a directory on the SD/SDHC
 
Syntax/Parameters FILE( "MKDIR", [fileRes], data [, data [, ...]] );
 
Options "MKDIR" - Make directory. - Immediate string.
fileRes - Result of file operation. See File Result. (optional) - Entity Name of numeric variable (U8, U16 etc), text variable, text.
data - One of more sets of data to concatenate to form the directory name. - Immediate strings or numbers plus entity names of text or numeric variables or pointers to variables.
 
Example   FILE( "MKDIR", , "SDHC/dir1/dir2" ); // Note dir1 must exist otherwise returns path error
  FILE( "MKDIR", txtVarRes, "SDHC/", varDir, "/", varSubDir ); // Note varDir must exist otherwise returns path error 
 

Command FILE - "MKFN"
 
Description Make a file name from a list of entities and strings.
 
Syntax/Parameters FILE( "MKFN", [fileRes], fileName, data [, data [, ...]] );
 
Options "MKFN" - Make filename. - Immediate string.
fileRes - Result of file operation. See File Result. (optional) - Entity Name of numeric variable (U8, U16 etc), text variable, text.
fileName - Destination for concatenated file name. See File and Directory Names. -Text variable for file name.
data - One of more sets of data to concatenate to form the file name. -Immediate strings or numbers plus entity names of text or numeric variables or pointers to variables.
 
Example   FILE( "MKFN", txtVarRes, txtVarFileName, "SDHC/", varDir, "/", varBaseName, ".txt" );
  FILE( "MKFN", , txtVarFileName, "NAND/file", varNum, ".bmp" ); 
 

Command FILE - "OPEN"
 
Description Open a file on SD/SDHC for read/write/append/overwrite. If the file does not exist then it is created. Not supported on NAND.
Use this command with a file object variable and "READ" or "WRITE" and "CLOSE" if you wish to read or modify the file by small blocks of data. See "READALL", "WRITEALL" and "APPEND" for details of reading or modifying a whole file.
 
Syntax/Parameters FILE( "OPEN", [fileRes], fileObj, fileName [, fileName [, ...]] ); // File Open for Read (from start of file) - same as "OPEN+R"
FILE( "OPEN+R", [fileRes], fileObj, fileName [, fileName [, ...]] ); // File Open for Read (from start of file)
FILE( "OPEN+W", [fileRes], fileObj, fileName [, fileName [, ...]] ); // File Open for Write (truncate file to zero length)
FILE( "OPEN+A", [fileRes], fileObj, fileName [, fileName [, ...]] ); // File Open for Append (start at end of file)
FILE( "OPEN+O", [fileRes], fileObj, fileName [, fileName [, ...]] ); // File Open for Write (overwrite from start of file)
 
Options "OPEN" - Open a file for reading data (from start of file). - Immediate string.
"OPEN+R" - Open a file for reading data (from start of file). - Immediate string.
"OPEN+W" - Open a file for writing data (truncate any existing file to zero length). - Immediate string.
"OPEN+A" - Open a file for appending data to end of file. - Immediate string.
"OPEN+O" - Open a file for overwriting data (from start of file). - Immediate string.
fileRes - Result of file operation. See File Result. (optional) - Entity Name of numeric variable (U8, U16 etc), text variable, text.
fileObj - File object variable. See File Object Variable. - Entity name of file object variable.
fileName - File name to open. Can be a concatenation of strings. See File and Directory Names. - Immediate string or text variable of file name.
 
Example   FILE( "OPEN+A", varRes, varFileObj, "SDHC/file.txt" );
  FILE( "OPEN+R", varRes, varFileObj1, "SDHC/info/", varBaseName, ".txt" );
  FILE( "OPEN+W", , varFileObj3, varFileName ); 
 

Command FILE - "READ"
 
Description Read data from an open file on SD/SDHC. The file must already be opened for read access using "OPEN+R".
 
Syntax/Parameters FILE( "READ", [fileRes], fileObj, [numRead], [numToRead], data );
 
Options "READ" - Read data from a file at the current file pointer. - Immediate string.
fileRes - Result of file operation. See File Result. (Optional) - Entity Name of numeric variable (U8, U16 etc), text variable, text.
fileName - File name. See File and Directory Names. - Immediate string or text variable of file name.
numRead - Number of bytes read from file. (Optional) - Entity Name of numeric variable (U32 etc).
numToRead - Maximum number of bytes to read from file. (Optional) Either the size of data is read or all remaining bytes (whichever is smaller) if this omitted. - Entity Name of numeric variable (U32 etc).
data - Destination of bytes read in. - Immediate strings or numbers plus entity names of text or numeric variables or pointers to variables.
 
Example   FILE( "READ", txtVarRes, varFileObj3, , varData, 1024 );
  FILE( "READ", , varFileObj2, varNumBytes, varData ); 
 

Command FILE - "READALL"
 
Description Read data from a file on SD/SDHC or NAND. Opens file, reads data, closes the file.
 
Syntax/Parameters FILE( "READALL", [fileRes], fileObj, fileName, [numRead], [numToRead], data );
 
Options "READALL" - Read data from a file. - Immediate string.
fileRes - Result of file operation. See File Result. (Optional) -Entity Name of numeric variable (U8, U16 etc), text variable, text.
fileObj - File object variable. See File Object Variable. - Entity name of file object variable.
numRead - Number of bytes read from file. (Optional) - Entity Name of numeric variable (U32 etc).
numToRead - Maximum number of bytes to read from file. (Optional) Either the size of data is read or all remaining bytes (whichever is smaller) if this omitted. - Entity Name of numeric variable (U32 etc).
data - Destination of bytes read in. - Immediate strings or numbers plus entity names of text or numeric variables or pointers to variables.
 
Example   FILE( "READALL", txtVarRes, varFileObj, "SDHC/logs/mylog1.txt", , 1024, varData );
  FILE( "READALL", , varFileObj, varFileName, varNumBytes , , varData ); 
 

Command FILE(''READLN''...);  - v49.42
 
Description File Read Line Functionality
* Lines of text can be read from an SD Card.
* Line endings are terminated by (\\0D\\0A). CR's (\\0D) are ignored and stripped out when the data is read. is placed at the end of a
line when the data is written to the file.
 
Syntax/Parameters "READLN" - Read Line from a file. - Immediate string.
fileRes - Result of file operation. See File Result. (Optional) -Entity Name of numeric variable (U8, U16 etc), text variable, text.
fileObj - File object variable. See File Object Variable. - Entity name of file object variable.
numRead - Number of bytes read from file. (Optional) - Entity Name of numeric variable (U32 etc).
numToRead - Maximum number of bytes to read from file. (Optional) Either the size of data is read or all remaining bytes (whichever is smaller) if this omitted. - Entity Name of numeric variable (U32 etc).
data - Destination of bytes read in. - Immediate strings or numbers plus entity names of text or numeric variables or pointers to variables.
 
Options FILE( "READLN", [fileRes], fileObj, [numRead], [numToRead], data ); // Read Line (given open fileObj);
 
Example FILE( "READLN", txtVarRes, varFileObj, ,,"Hello" ); // Read Line
 

Command FILE - "RENAME"
 
Description Rename a file on SD/SDHC or NAND or move a file from SD/SDHC to SD/SDHC or between SD/SDHC and NAND.
 
Syntax/Parameters FILE( "RENAME", [fileRes], dstFileName, srcFileName ); // Rename/Move File - doesn't move and reports error if file exists
FILE( "RENAME+O", [fileRes], dstFileName, srcFileName ); // Rename/Move File - overwrites file if it exists
 
Options "RENAME" - Move source file to destination file if destination file does not exist. - Immediate string.
"RENAME+O" - Move source file to destination file and overwrite if destination file already exists. - Immediate string.
fileRes - Result of file operation. See File Result. (Optional) -Entity Name of numeric variable (U8, U16 etc), text variable, text.
dstFileName - Destination file name. See File and Directory Names. - Immediate string or text variable of file name.
srcFileName - Source file name. See File and Directory Names. - Immediate string or text variable of file name.

If the source file is read only, then the source file will be copied, if possible, and the "Access Denied" file result will be returned.
 
Example   FILE( "RENAME", varRes, "NAND/tree.bmp", "SDHC/images/A Tree Somewhere.bmp" );
  FILE( "RENAME+O", , varDstName, varSrcName ); 
 

Command FILE - "SAVE"
 
Description Save media entity (image, audio etc) to a file on SD/SDHC or NAND in the appropriate file format.
 
Syntax/Parameters FILE( "SAVE", [fileRes], fileObj, fileName, [numWritten], [numToWrite], data ); // Save File - reports error if file exists
FILE( "SAVE+O", [fileRes], fileObj, fileName, [numWritten], [numToWrite], data ); // Save File - overwrites file if it exists
 
Options "SAVE" - Save formatted source to destination file if destination file does not exist. - Immediate string.
"SAVE+O" - Save formatted source to destination file and overwrite if destination file already exists. - Immediate string.
fileRes - Result of file operation. See File Result. (Optional) -Entity Name of numeric variable (U8, U16 etc), text variable, text.
fileObj - File object variable. See File Object Variable.- Entity name of file object variable.
fileName - Destination file name, required if file not already open. See File and Directory Names. -Immediate string or text variable of file name.
numWritten - -Number of bytes written to file. (Optional) - Entity Name of numeric variable (U32 etc).
numToWrite - Maximum number of bytes to write to file. (Optional) -Entity Name of numeric variable (U32 etc).
data - Source data entity name. -Immediate string or text variable of entity name.

File extensions are:
TFT raw image - ".tri" - TFT specific image file designed for fast loading.
TFT raw audio - ".tra" - TFT specific audio file designed for fast loading.
TFT raw layer - ".trl" - TFT specific layer file designed for fast loading.
R8G8B8 bitmap - ".bmp" - Standard Bitmap.

Note: Only saving processed library image to a TFT raw image ".tri" currently supported.
 
Example   FILE( "SAVE", varRes, varFileObj, "NAND/tree.tri", , , libImgTree );
  FILE( "SAVE+O", , varFileObj, , , , varSrcName ); 
 

Command FILE - "SETPOS"
 
Description Set a new read/write position in the open file on SD/SDHC.
 
Syntax/Parameters FILE( "SETPOS", [fileRes], fileObj, [actPosn], reqPosn ); // Set new absolute position - same as "SETPOS+A"
FILE( "SETPOS+A", [fileRes], fileObj, [actPosn], reqPosn ); // Set new absolute position
FILE( "SETPOS+R", [fileRes], fileObj, [actPosn], reqPosn ); // Set new relative position from current position
 
Options "SETPOS" - Set new file position from start of file (Absolute). - Immediate string.
"SETPOS+A" - Set new file position from start of file (Absolute). - Immediate string.
"SETPOS+R" - Set new file position relative to current file position. - Immediate string.
fileRes - Result of file operation. See File Result. (Optional) - Entity Name of numeric variable (U8, U16 etc), text variable, text.
fileObj - File object variable. See File Object Variable. - Entity name of file object variable.
actPosn - New read/write position after move - absolute position from start of file. (Optional) - Entity Name of numeric variable (U8, U16 etc), text variable, text.
reqPosn - Required read/write position. For relative positions, negative numbers move the position towards the start of the file and positive numbers move the position towards the end of the file. - Immediate number or entity name of numeric variable (U8, S8, U16, S16 etc).
 
Example   FILE( "SETPOS", varRes, varFileObj2, , varPosn );
  FILE( "SETPOS+R", , varFileObj, varNewPosn, -10 );
 

Command FILE - "SIZE"
 
Description Get file size on SD/SDHC or NAND.
 
Syntax/Parameters FILE( "SIZE", [fileRes], dst, fileName );
 
Options "SIZE" - Get file size. - Immediate string.
fileRes - Result of file operation. See File Result. (Optional) - Entity Name of numeric variable (U8, U16 etc), text variable, text.
dst - File size in bytes. -Entity Name of numeric variable (U8, U16 etc), text variable, text.
fileName - File name. See File and Directory Names. - Immediate string or text variable of file name.
 
Example   FILE( "SIZE", varRes, varSize, "NAND/tree.bmp" );
  FILE( "SIZE", , varSize, varFileName ); 
 

Command FILE - "WRITE"
 
Description Write data to an open file on SD/SDHC. The file must already be opened for write/append/overwrite access using "OPEN+W", "OPEN+A", or "OPEN+O".
 
Syntax/Parameters FILE( "WRITE", [fileRes], fileObj, [numWritten], [numToWrite], data [, data [, ...]] );
 
Options "WRITE" - Write data to a file at current file pointer - Immediate string.
fileRes - Result of file operation. See File Result. (Optional) - Entity Name of numeric variable (U8, U16 etc), text variable, text.
fileObj - File object variable. See File Object Variable. - Entity name of file object variable.
numWritten - Number of bytes written to file. (Optional) - Entity Name of numeric variable (U32 etc).
numToWrite - Maximum number of bytes to write to file. (Optional) - Entity Name of numeric variable (U32 etc).
data - One of more sets of data to write to file. - Immediate strings or numbers plus entity names of text or numeric variables or pointers to variables.
 
Example   FILE( "WRITE", txtVarRes, varFileObj2, , , "Hello", " World: ", varCount, "\\0a" );
  FILE( "WRITE", , varFileObj1, varNumBytes, 1024, varData ); 
 

Command FILE - "WRITEALL"
 
Description Write data to a file on SD/SDHC or NAND. Opens file for write, truncates file, writes data, closes the file.
 
Syntax/Parameters FILE( "WRITEALL", [fileRes], fileObj, fileName, [numWritten], [numToWrite], data [, data [, ...]] ); // SD/SDHC
FILE( "WRITEALL", [fileRes], fileObj, fileName, [numWritten], [numToWrite], data ); // NAND
 
Options "WRITEALL" - Write data to a file (truncate to zero if already exists). - Immediate string.
fileRes - Result of file operation. See File Result.(Optional) - Entity Name of numeric variable (U8, U16 etc), text variable, text.
fileObj - File object variable. See File Object Variable. - Entity name of file object variable.
fileName - File name. See File and Directory Names. - Immediate string or text variable of file name.
numWritten - Number of bytes written to file.(Optional) - Entity Name of numeric variable (U32 etc).
numToWrite - Maximum number of bytes to write to file.(Optional) - Entity Name of numeric variable (U32 etc).
data - One of more sets of data to write to file. NAND only supports one data source. - Immediate strings or numbers plus entity names of text or numeric variables or pointers to variables.
 
Example   FILE( "WRITEALL", txtVarRes, varFileObj, "SDHC/logs/mylog1.txt", , , "Hello", " World: ", varCount, "\\0a" );
  FILE( "WRITEALL", , varFileObj, varFileName, varNumBytes, 1024, varData ); 
 

Command FILE(''WRITELN''...);- v49.42
 
Description File Write Line Functionality
* Lines of text can be written to an SD Card.
* Line endings are terminated by (\\0D\\0A). CR's (\\0D) are ignored and stripped out when the data is read. is placed at the end of a
line when the data is written to the file.
 
Syntax/Parameters "WRITELN" - Write data to a Line
fileRes - Result of file operation. See File Result.(Optional) - Entity Name of numeric variable (U8, U16 etc), text variable, text.
fileObj - File object variable. See File Object Variable. - Entity name of file object variable.
fileName - File name. See File and Directory Names. - Immediate string or text variable of file name.
numWritten - Number of bytes written to file.(Optional) - Entity Name of numeric variable (U32 etc).
numToWrite - Maximum number of bytes to write to file.(Optional) - Entity Name of numeric variable (U32 etc).
data - One of more sets of data to write to file. NAND only supports one data source. - Immediate strings or numbers plus entity names of text or numeric variables or pointers to variables.
 
Options FILE( "WRITELN", [fileRes], fileObj, [numWritten], [numToWrite], data [, data [, ...]] ); // Write Line (given open fileObj)
 
Example FILE( "WRITELN", txtVarRes, varFileObj, ,,"Hello" ); // Write Line
 
Update Information

 Version

 Title

Date  

 Details

49.58

 FILE

07 Sep 15 

Show

* Added CSUM command - gets 16 bit checksum of file data
* Modified some error codes to better reflect error type

49.58

 FILE command

07 Sep 15 

Show

* FILE() commands now return an FR_INVALID_DRIVE result and "fail gracefully" if the file source drive is not recognised rather than
entering the module's error page. This is so the user can manage the error themselves from within their project code.

00.01.00

 SD Card Mounting Improvement

13 Feb 15 

Show

Added retry mechanism to resolve some issues of SD cards failing to mount correctly

00.01.00

 File Checksum - FILE(''CSUM''...);

13 Feb 15 

Show

Added 'CSUM' command to calculate 16bit checksum of a given file in NAND or on SD card
FILE( "CSUM", [fileRes], fileObj, dst, fileName ); // Get checksum of given fileName

49.55

 FILE(''action''....) Command - ''action'' only works in uppercase

13 Mar 14 

Show

* FILE("action",....); now accepts case insensitive "action". Previously "action" had to be uppercase.

49.50

 Finding Free Space on SD card

17 Jan 14 

Show

* Added command to return free bytes on SD card:
FILE( "FREE", [fileRes], free, "SDHC/" );
* Note the first time this function is called, there is a delay whilst the SD card is fully examined. Subsequent reads are shorter.

49.48

 SD Card Write ''Access Denied'' - Increase Number of ''Similar'' Filenames

21 Nov 13 

Show

* When a number "similarly" named files are written to a directory on an SD or SDHC card then an Access Denied (error number 7) can occur.
* "Similarly" named files could have just an incrementing number in the file name or could be just the date and time.
* Within the file system, to be compatible with Windows, an 8.3 short file name (SFN) is created from the long file name (LFN) provided by the user. This SFN is created by a hash of the LFN and contains a '~' followed by a 4 character hexadecimal number. The SFN must be unique within the directory, if it is not then another hash is tried. After 100 attempts (collisions) at creating a unique SFN the module would return an Access Denied error.
* The hash algorithm has now been modified to create a 6 character hexadecimal number plus the number of permissible collisions has been increased to 1000.

* It is recommended that, when using the time/date in the filename then a new directory is created each day/hour to keep file access times reasonable as processing collisions can significantly increase file creation times. Also keeping the filename within the 8.3 format will significantly improve performance.

49.44

 Structure support in FILE() and TEXT() commands

09 Oct 13 

Show

* Structure variables can now be used in all the parameters in the FILE() commands.
* Structure variables can now be used for the source in the TEXT() command.

49.44

 Problem reading files after FILE(''SETPOS'',...);

05 Oct 13 

Show

If a position not divisible by 4 (ie 32 bits) was selected with FILE("SETPOS",...) then the data read from SD card was corrupted. This is now fixed.

49.42

 File Read Line Functionality - FILE(''READLN''...); [Also ''WRITELN'' added]

06 Sep 13 

Show

* Lines of text can be read from or written to an SD Card.
FILE( "READLN", [fileRes], fileObj, [numRead], [numToRead], data ); // Read Line (given open fileObj);
FILE( "WRITELN", [fileRes], fileObj, [numWritten], [numToWrite], data [, data [, ...]] ); // Write Line (given open fileObj)
* Line endings are terminated by (\\0D\\0A). CR's (\\0D) are ignored and stripped out when the data is read. is placed at the end of a line when the data is written to the file.

49.37

 USB Host via MCBK37A - USBH

10 Jun 13 

Show

* Added USBH device and setup to support MCBK37A via AS1. All existing FILE functions can be used using "USBH/..." prefix.

49.32

 Files - Tests added to check filename length when reading/writing to NAND.

14 Feb 13 

Show

* Tests added to check filename length when reading/writing to NAND. Note maximum length is 15 characters.
* Fixed problem with filename corruption in FILE("OPEN"...) and FILE("MKDIR"...). Filename was corrupted during a FILE("WRITE"...)

49.19

 SD Card Files - Increased maximum simultaneous open files to 8.

05 Oct 12 

Show

Increased maximum simultaneous open files to 8 (this includes menu files, images, as well as those opened with FILE() command).
* Modified code to guarantee file close performed where necessary.

49.18

 FILE(''WRITE''|''APPEND''|''WRITEALL'') - Support for numbers, U8, FLT, immediate etc added

22 Sep 12 

Show

* Support for numbers, U8, FLT, immediate etc added

49.18

 FILE(''MKFN'') - Fixed concatenation of file name.

22 Sep 12 

Show

* Fixed concatenation of file name
* File result now indicates if valid drive and valid filename

49.18

 FILE(''MKDIR'') - Added command to allow directory creation on SD/SDHC card.

22 Sep 12 

Show

* Added command to allow directory creation on SD/SDHC card.

49.18

 Data maximum length - Special case for buffers required greater than 8192 bytes, use bufLen rather than maxLen/length.

22 Sep 12 

Show

Special case for buffers required greater than 8192 bytes, use bufLen rather than maxLen/length. CALC() and other commands may have unexpected results if buffers greater than 8182 are used. This is intended for use with file writing.

49.18

 Boot Files - Fix to support FAT16 SD cards with more than 255 entries in root directory.

22 Sep 12 

Show

Fix to support FAT16 SD cards with more than 255 entries in root directory (maximum is 512 under FAT16).
* Fix to prevent erasure of images, fonts etc from NAND during updates.
* Fix to support file sizes of exact multiples of 4KB.
* Fix for clearing screen
* New boot files:
boot.bin V00.20
newflash.bin V00.26
nandboot.bin V00.25
iuloader.bin V00.36

49.16

 Raw Image Files - Added support for new TFT raw image file (*.tri) format.

14 Sep 12 

Show

Added support for new TFT raw image file (*.tri) format.
* A converted library BMP/JPG can be stored as .tri format using FILE("SAVE") command
* Raw image files are loaded using LIB() command directly into the library entities memory, thus greatly speeding up loading.
* File Format:
Offset Size Description
\\00 8 bytes Identifier (IUK_TRIF)
\\08 4 bytes size of image (N) in bytes (LSB first)
\\0C 4 bytes width of image in pixels (LSB first)
\\10 4 bytes height of image in pixels (LSB first)
\\14 1 byte number of bytes per pixel
\\15 3 bytes unused
\\18 4 bytes starting address (XX) of data (LSB first)
\\XX N bytes pixel data

49.16

 Added FILE() commands - New FILE() commands have been added.

14 Sep 12 

Show

The following FILE() commands have been added:
"APPEND" Append data to 'filename'.
"CLOSE" Close an open file on SD/SDHC.
"COPY" Copy a file.
"DATE" Get file time and date.
"DELETE" Delete a file.
"EXISTS" Check whether a file or directory exists.
"GETPOS" Get current read/write position in the file.
"MKFN" Make a file name from a list of entities and strings.
"OPEN" Open a file on SD/SDHC for read/write/append/overwrite.
"READ" Read data from an open file on SD/SDHC.
"READALL" Read data from 'filename'.
"RENAME" Rename/Move a file.
"SAVE" Save media (eg image) to a file.
"SETPOS" Set new read/write position in the file.
"SIZE" Get file size.
"WRITE" Write data to an open file on SD/SDHC.
"WRITEALL" Write data to 'filename'.
* Refer to the FILE() command on the website for a detailed explanation.
* Limitations are for read and write only text variables, text entities and (for write) immediate strings are supported. All data is written as U8 data, ie text vars and text are converted to U8s (FILEASC format).
* The FILE("SAVE") command saves a library image to SDHC or NAND in a raw format which allows for resized/rotated images to be saved after loading by LIB(). This is a proprietry file format.
* The Real Time Clock should be configured as this is used to date the files stored to SD Card or NAND.

49.03

 LOAD( ''SDHC/filename.txt'', var, var, ... ) - Fixed. The file now appends rather than truncating each time.

01 Jun 12 

Show

Fixed. The file now appends rather than truncating each time.
* File write speeds improved.

49.02

 File Handling - New FAT file system implemented.

15 May 12 

Show

New FAT file system implemented
* SD card now supports long filenames and unlimited directories.