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