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 |
|
|
|