|
FILE(...) File handling commands for SD/SDHC Card and NAND Flash. 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 Commands Summary Detailed explanations of the commands can be found further down this page.
FILE - "APPEND" 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. FILE( "APPEND", [fileRes], fileObj, fileName, [numWritten], [numToWrite], data [, data [, ...]] ); The parameters are:
Examples: FILE( "APPEND", txtVarRes, varFileObj, "SDHC/logs/mylog1.txt", , , "Hello", " World: ", varCount, "\\0a" ); FILE( "APPEND", , varFileObj, varFileName, varNumBytes, 1024, varData ); FILE - "CLOSE" Close an open file on SD/SDHC. FILE( "CLOSE", [fileRes], fileObj ); The parameters are:
Examples: FILE( "CLOSE", txtVarRes, varFileObj1 ); FILE( "CLOSE", , varFileObj4 ); FILE - "COPY" Copy a file from SD/SDHC to SD/SDHC or between SD/SDHC and NAND. 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 The parameters are:
Examples: FILE( "COPY", varRes, "NAND/tree.bmp", "SDHC/images/A Tree Somewhere.bmp" ); FILE( "COPY+O", , varDstName, varSrcName ); FILE - "DATE" Get file date and time. FILE( "DATE", [fileRes], dst, [format], fileName ); The parameters are:
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. Examples: FILE( "DATE", varRes, varTxt, "d M Y H:i:s", "NAND/tree.bmp" ); FILE( "DATE", , varTxt, "Y", varSrcName ); FILE - "DELETE" Delete a file on SD/SDHC or NAND. FILE( "DELETE", [fileRes], fileName ); The parameters are:
Examples: FILE( "DELETE", varRes, "SDHC/music/A-Nice-Bit-Of-Music.wav" ); FILE( "DELETE", , varFileName ); FILE - "EXISTS" Check whether a file or directory exists. FILE( "EXISTS", [fileRes], [dst], fileName ); The parameters are:
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. Examples: FILE( "EXISTS", varRes, varExists, "SDHC/music/A-Nice-Bit-Of-Music.wav" ); FILE( "EXISTS", , varExists, varFileName ); FILE - "GETPOS" Get the current read/write position in the open file on SD/SDHC. FILE( "GETPOS", [fileRes], fileObj, posn ); The parameters are:
Examples: FILE( "GETPOS", varRes, varFileObj3, varU32 ); FILE( "GETPOS", , varFileObj, varPosn ); FILE - "MKDIR" Make a directory on the SD/SDHC. FILE( "MKDIR", [fileRes], data [, data [, ...]] ); The parameters are:
Examples: 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 FILE - "MKFN" Make a file name from a list of entities and strings. FILE( "MKFN", [fileRes], fileName, data [, data [, ...]] ); The parameters are:
Examples: FILE( "MKFN", txtVarRes, txtVarFileName, "SDHC/", varDir, "/", varBaseName, ".txt" ); FILE( "MKFN", , txtVarFileName, "NAND/file", varNum, ".bmp" ); FILE - "OPEN" 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. 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) The parameters are:
Examples: FILE( "OPEN+A", varRes, varFileObj, "NAND/file.txt" ); FILE( "OPEN+R", varRes, varFileObj1, "SDHC/info/", varBaseName, ".txt" ); FILE( "OPEN+W", , varFileObj3, varFileName ); FILE - "READ" Read data from an open file on SD/SDHC. The file must already be opened for read access using "OPEN+R". FILE( "READ", [fileRes], fileObj, [numRead], [numToRead], data ); The parameters are:
Examples: FILE( "READ", txtVarRes, varFileObj3, , varData, 1024 ); FILE( "READ", , varFileObj2, varNumBytes, varData ); FILE - "READALL" Read data from a file on SD/SDHC or NAND. Opens file, reads data, closes the file. FILE( "READALL", [fileRes], fileObj, fileName, [numRead], [numToRead], data ); The parameters are:
Examples: FILE( "READALL", txtVarRes, varFileObj, "SDHC/logs/mylog1.txt", , varData, 1024 ); FILE( "READALL", , varFileObj, varFileName, varNumBytes, varData ); FILE - "RENAME" Rename a file on SD/SDHC or NAND or move a file from SD/SDHC to SD/SDHC or between SD/SDHC and NAND. 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 The parameters are:
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. Examples: FILE( "RENAME", varRes, "NAND/tree.bmp", "SDHC/images/A Tree Somewhere.bmp" ); FILE( "RENAME+O", , varDstName, varSrcName ); FILE - "SAVE" Save media entity (image, audio etc) to a file on SD/SDHC or NAND in the appropriate file format. 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 The parameters are:
File extensions are:
Note: Only saving processed library image to a TFT raw image ".tri" currently supported. Examples: FILE( "SAVE", varRes, varFileObj, "NAND/tree.tri", , , libImgTree ); FILE( "SAVE+O", , varFileObj, , , , varSrcName ); FILE - "SETPOS" Set a new read/write position in the open file on SD/SDHC. 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 The parameters are:
Examples: FILE( "SETPOS", varRes, varFileObj2, , varPosn ); FILE( "SETPOS+R", , varFileObj, varNewPosn, -10 ); FILE - "SIZE" Get file size on SD/SDHC or NAND. FILE( "SIZE", [fileRes], dst, fileName ); The parameters are:
Examples: FILE( "SIZE", varRes, varSize, "NAND/tree.bmp" ); FILE( "SIZE", , varSize, varFileName ); FILE - "WRITE" 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". FILE( "WRITE", [fileRes], fileObj, [numWritten], [numToWrite], data [, data [, ...]] ); The parameters are:
Examples: FILE( "WRITE", txtVarRes, varFileObj2, , , "Hello", " World: ", varCount, "\\0a" ); FILE( "WRITE", , varFileObj1, varNumBytes, 1024, varData ); FILE - "WRITEALL" Write data to a file on SD/SDHC or NAND. Opens file for write, truncates file, writes data, closes the file. FILE( "WRITEALL", [fileRes], fileObj, fileName, [numWritten], [numToWrite], data [, data [, ...]] ); // SD/SDHC FILE( "WRITEALL", [fileRes], fileObj, fileName, [numWritten], [numToWrite], data ); // NAND The parameters are:
Examples: FILE( "WRITEALL", txtVarRes, varFileObj, "SDHC/logs/mylog1.txt", , , "Hello", " World: ", varCount, "\\0a" ); FILE( "WRITEALL", , varFileObj, varFileName, varNumBytes, 1024, varData ); 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) 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. 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.
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 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, "\\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 |