NXT Functions File Access

From ROBOTC API Guide
Jump to: navigation, search
NXTFunctions and Variables → File Access


Color Key
Function:
Variable:

Example

Below is a simple program highlighting the features of ROBOTC File IO:
/*****************************\
|* Example File Input/Output *|
|* Bence Feher 22/Dec/2011   *|
\*****************************/
 
task main()
{
  TFileHandle   hFileHandle;              // will keep track of our file
  TFileIOResult nIOResult;                // will store our IO results
  string        sFileName = "test.txt";   // the name of our file
  int           nFileSize = 100;          // will store our file size 
 
  byte CR = 0x13;   // define CR (carriage return)
  byte LF = 0x10;   // define LF (line feed)
 
  string        sMessageToWrite = "ROBOTC IO test!";    // we will write this to the file
  string        sMesageToWrite_2 = "A new line!";       // we will also write this to the file on the next line
  char          incommingChar;                          // this will store each char as we read back in from the file
  string        incommingString[5];                     // this will store the final, fully-read strings (with new strings getting put into new indexes
  int           nLineCounter = 0;                       // this will let us know which line we are on when reading and writing (used as the index to 'incommingString[]')
 
  Delete("test.txt",nIOResult);
  OpenWrite(hFileHandle, nIOResult, sFileName, nFileSize);    // open the file for writing (creates the file if it does not exist)
  WriteText(hFileHandle, nIOResult, sMessageToWrite);         // write 'sMessageToWrite' to the file
  WriteByte(hFileHandle, nIOResult, CR);                      // write 'CR' to the file (carriage return)
  WriteByte(hFileHandle, nIOResult, LF);                      // write 'LF' to the file (line feed)
  WriteText(hFileHandle, nIOResult, sMesageToWrite_2);        // write 'sMesageToWrite_2' to the file
  Close(hFileHandle, nIOResult);                              // close the file (DON'T FORGET THIS STEP!)
 
  wait1Msec(1000);  // just a wait so we can see the variables updating in the ROBOTC debugger in order (this is not necessary)
 
  OpenRead(hFileHandle, nIOResult, sFileName, nFileSize);     // open our file 'sFileName' for reading
 
  for(int i = 0; i < nFileSize; i++)                          // iterate through the file until we've hit the end:
  {
    ReadByte(hFileHandle, nIOResult, incommingChar);            // read in a single byte
 
    if(incommingChar == CR || incommingChar == LF)              // if the incomming byte is a carriage return or a line feed:
    {
      if(incommingChar == LF)                                     // if it's a line feed:
        nLineCounter++;                                             // increment our index (will now store next char on a 'new line' (a new index into our 'incommingString[]')
    }
    else
    { 
      incommingString[nLineCounter] += incommingChar;             // append that byte (char) to the end of our final string, at the right index
    }
  }
  Close(hFileHandle, nIOResult);                              // close our file (DON'T FORGET THIS STEP!)
 
  for(int i = 1; i <= 5; i++)
  {
    nxtDisplayCenteredTextLine(i, incommingString[i-1]);
  }
 
 
  while(true);  // infinite loop to keep our program running so that we can view the ROBOTC debugger variables
}


Close

void Close(TFileHandle hFileHandle, TFileIOResult &nIoResult)
(void) Closes the specified file handle. This should be the last file I/O operation after all reads or write are completed. nIoResult is non-zero when error occurs.
Parameter Explanation Data Type
hFileHandle The handle of the file to close. TFileHandle
nIoResult The result of the IO operation. TFileIOResult
Close(myFileHandle, IOResult);  // closes the file belonging to 'myFileHandle'
                                // and stores the result to 'IOResult'


Delete

void Delete(const string &sFileName, TFileIOResult &nIoResult)
(void) Deletes the specified filename from the NXT. nIoResult is non-zero when error occurs.
Parameter Explanation Data Type
sFileName The name of the file to delete. string
nIoResult The result of the IO operation. TFileIOResult
Delete("myFile.txt", IOResult);  // deletes the file, myFile.txt
                                 // and stores the result to 'IOResult'


FindFirstFile

void FindFirstFile(TFileHandle &hFileHandle, TFileIOResult &nIoResult, const string sSearch, string &sFileName, short &nFilesize)
(void) This function is used to start searching (iterating) through the list of files on the NXT. nIoResult is non-zero if no files exist in the NXT file system.. sSearch is the pattern match to use for the search string. For example:
  • "*.*" will find all files
  • "*.rso" will find all files with file extension “rso” which is the extension used for sound files
  • sFileName is the name of the first file found and nFilesize is the number of data bytes in the file.
  • hFileHandle returns a handle used to keep track of the search. You should use “Close” when the search is finished to release the handle so that the NXT can re-use it
Parameter Explanation Data Type
hFileHandle The handle of the search. TFileHandle
nIoResult The result of the search operation. TFileIOResult
sSearch The pattern to search for. string
sFileName The name of the first file found that matches the string pattern, 'sSearch'. string
nFilesize The size of the file 'sFileName' in bytes, returned by the search operation. short
TFileHandle myFileHandle;  // create a file handle variable 'myFileHandle'
TFileIOResult IOResult;    // create an IO result variable 'IOResult'
string myFileName = "";    // create and initialize a string variable 'myFileName'
int myFileSize = 0;        // create and initialize an integer variable 'myFileSize'
 
FindFirstFile(myFileHandle, IOResult, "*.txt", myFileName, myFileSize);  // return the first ".txt" file


FindNextFile

void FindNextFile(const TFileHandle hFileHandle, TFileIOResult &nIoResult, string &sFileName, short &nFilesize)
(void) Finds the next file in a previously initiated search.
Parameter Explanation Data Type
hFileHandle The handle of the search. TFileHandle
nIoResult The result of the search operation. TFileIOResult
sFileName The name of the first file found that matches the string pattern, 'sSearch'. string
nFilesize The size of the file 'sFileName' in bytes, returned by the search operation. short
TFileHandle myFileHandle;  // create a file handle variable 'myFileHandle'
TFileIOResult IOResult;    // create an IO result variable 'IOResult'
string myFileName = "";    // create and initialize a string variable 'myFileName'
int myFileSize = 0;        // create and initialize an integer variable 'myFileSize'
 
FindFirstFile(myFileHandle, IOResult, "*.txt", myFileName, myFileSize);  // store the name of the first txt file to 'myFileName'
 
string secondFile = "";
FindNextFile(myFileHandle, IOResult, secondFile, myFileSize);  // store the name of the next txt file to 'secondFile'


nAvailFlash

short nAvailFlash
(short) The amount of flash memory that is currently unused and available for file storage. Units are 1/10 of 1K (i.e. 100 bytes).
short flashLeft = nAvailFlash;  // creates a short variable 'flashLeft'
                                // and sets it equal to the amount of flash available


OpenRead

void OpenRead(TFileHandle &hFileHandle, TFileIOResult &nIoResult, const string &sFileName, word &nFileSize)
(void) Opens sFileName for reading. hFileHandle is used for subsequent reads to this file. nFileSize is filled with the file length. nIoResult is non-zero when error occurs.
Parameter Explanation Data Type
hFileHandle The handle assigned to the file once opened. TFileHandle
nIoResult The result of the IO operation. TFileIOResult
sFileName The name of the file to open. string
nFilesize Will store the size (in bytes) of file opened. word
TFileHandle myFileHandle;          // create a file handle variable 'myFileHandle'
TFileIOResult IOResult;            // create an IO result variable 'IOResult'
string myFileName = "myFile.txt";  // create and initialize a string variable 'myFileName'
int myFileSize = 0;                // create and initialize an integer variable 'myFileSize'
 
OpenRead(myFileHandle, IOResult, myFileName, myFileSize);  // open for read: "myFile.txt",
                                                           // storing its size in 'myFileSize'


OpenWrite

void OpenWrite(TFileHandle &hFileHandle, TFileIOResult &nIoResult, const string &sFileName, word &nFileSize)
(void) Opens sFileName for writing with specified size of nFileSize. hFileHandle is used for subsequent writes to this file. nIoResult is non-zero when error occurs. sFileName must be a valid NXT file name. The file must not already exist on the NXT for this function to succeed.
Parameter Explanation Data Type
hFileHandle The handle assigned to the file once opened. TFileHandle
nIoResult The result of the IO operation. TFileIOResult
sFileName The name of the file to open. string
nFilesize Will store the size (in bytes) of file opened. word
TFileHandle myFileHandle;          // create a file handle variable 'myFileHandle'
TFileIOResult IOResult;            // create an IO result variable 'IOResult'
string myFileName = "myFile.txt";  // create and initialize a string variable 'myFileName'
int myFileSize = 10;               // create and initialize an integer variable 'myFileSize'
 
OpenWrite(myFileHandle, IOResult, myFileName, myFileSize);  // open for write: "myFile.txt"


ReadByte

void ReadByte(const TFileHandle hFileHandle, TFileIOResult &nIoResult, byte &nParm)
(void) Reads a byte variable (8-bit) from the specified file. nIoResult is non-zero when error occurs.
Parameter Explanation Data Type
hFileHandle The handle of the opened file to read from. TFileHandle
nIoResult The result of the IO operation. TFileIOResult
nParm The byte read in will be assigned to this variable. byte
int readBytes = 0;  // create and initialize an integer variable 'readBytes'
ReadByte(myFileHandle, IOResult, readBytes);  // read a byte from the file and store it to 'readBytes'


ReadFloat

void ReadFloat(const TFileHandle hFileHandle, TFileIOResult &nIoResult, float &fParm)
(void) Reads a float variable from the specified file. nIoResult is non-zero when error occurs.
Parameter Explanation Data Type
hFileHandle The handle of the opened file to read from. TFileHandle
nIoResult The result of the IO operation. TFileIOResult
fParm The float read in will be assigned to this variable. float
float readFloats = 0.0;  // create and initialize a float variable 'readFloats'
ReadFloat(myFileHandle, IOResult, readFloats);  // read a float from the file and store it to 'readFloats'


ReadLong

void ReadLong(const TFileHandle hFileHandle, TFileIOResult &nIoResult, long &nParm)
(void) Reads a long integer variable (32-bit) from the specified file. nIoResult is non-zero when error occurs.
Parameter Explanation Data Type
hFileHandle The handle of the opened file to read from. TFileHandle
nIoResult The result of the IO operation. TFileIOResult
nParm The long read in will be assigned to this variable. long
long readLongs = 0.0;  // create and initialize a long variable 'readLongs'
ReadLong(myFileHandle, IOResult, readLongs);  // read a long from the file and store it to 'readLongs'


ReadShort

void ReadShort(const TFileHandle hFileHandle, TFileIOResult &nIoResult, word &nParm)
(void) Reads a short integer variable (16-bit) from the specified file. nIoResult is non-zero when error occurs.
Parameter Explanation Data Type
hFileHandle The handle of the opened file to read from. TFileHandle
nIoResult The result of the IO operation. TFileIOResult
nParm The short read in will be assigned to this variable. short
short readShorts = 0.0;  // create and initialize a short variable 'readShorts'
ReadShort(myFileHandle, IOResult, readShorts);  // read a short from the file and store it to 'readShorts'


Rename

void Rename(const string &sFileName, TFileIOResult &nIoResult, const string &sOriginalFileName)
(void) Renames file sOriginalFileName to sFileName.
Parameter Explanation Data Type
sFileName The NEW name for the file. string
nIoResult The result of the IO operation. TFileIOResult
sOriginalFileName The OLD name of the file. string
Rename("NewName.txt", IOResult, "originalFile.txt");  // renames 'originalFile.txt' to 'NewName.txt'


WriteByte

void WriteByte(const TFileHandle hFileHandle, TFileIOResult &nIoResult, const byte nParm)
(void) Writes a single byte to the specified file. nIoResult is non-zero when error occurs.
Parameter Explanation Data Type
hFileHandle The handle of the file to write to. TFileHandle
nIoResult The result of the IO operation. TFileIOResult
nParm The bytes to write. byte
int writeMe = 4246;                          // create an int variable 'writeMe' and set it to 4246
WriteByte(myFileHandle, IOResult, writeMe);  // writes "4246" to the file handled by 'myFileHandle'


WriteFloat

void WriteFloat(const TFileHandle hFileHandle, TFileIOResult &nIoResult, const float fParm)
(void) Writes a float variable to the specified file. nIoResult is non-zero when error occurs.
Parameter Explanation Data Type
hFileHandle The handle of the file to write to. TFileHandle
nIoResult The result of the IO operation. TFileIOResult
fParm The float to write. float
float writeMe = 2.718;                        // create a float variable 'writeMe' and set it to 2.718
WriteFloat(myFileHandle, IOResult, writeMe);  // writes "2.718" to the file handled by 'myFileHandle'


WriteLong

void WriteLong(const TFileHandle hFileHandle, TFileIOResult &nIoResult, const long nParm)
(void) Writes a float variable to the specified file. nIoResult is non-zero when error occurs.
Parameter Explanation Data Type
hFileHandle The handle of the file to write to. TFileHandle
nIoResult The result of the IO operation. TFileIOResult
nParm The long to write. long
long writeMe = 424246;                       // create a long variable 'writeMe' and set it to 424246
WriteLong(myFileHandle, IOResult, writeMe);  // writes "424246" to the file handled by 'myFileHandle'


WriteShort

void WriteShort(const TFileHandle hFileHandle, TFileIOResult &nIoResult, const word nParm)
(void) Writes a short integer variable (16-bit) to the specified file. nIoResult is non-zero when error occurs.
Parameter Explanation Data Type
hFileHandle The handle of the file to write to. TFileHandle
nIoResult The result of the IO operation. TFileIOResult
nParm The short to write. short
short writeMe = 42;                           // create a short variable 'writeMe' and set it to 42
WriteShort(myFileHandle, IOResult, writeMe);  // writes "42" to the file handled by 'myFileHandle'


WriteString

void WriteString(const TFileHandle hFileHandle, TFileIOResult &nIoResult, const string sParm)
(void) Writes a string to the specified file including null terminator. nIoResult is non-zero when error occurs.
Parameter Explanation Data Type
hFileHandle The handle of the file to write to. TFileHandle
nIoResult The result of the IO operation. TFileIOResult
sParm The string to write. string
string writeMe = "ROBOTC";                     // create a string variable 'writeMe' and set it to "ROBOTC"
WriteString(myFileHandle, IOResult, writeMe);  // writes "ROBOTC" with a NULL terminator to the file handled by 'myFileHandle'


WriteText

void WriteText(const TFileHandle hFileHandle, TFileIOResult &nIoResult, const string sParm)
(void) Writes a string to the specified file without null terminator. nIoResult is non-zero when error occurs.
Parameter Explanation Data Type
hFileHandle The handle of the file to write to. TFileHandle
nIoResult The result of the IO operation. TFileIOResult
sParm The string to write. string
string writeMe = "ROBOTC";                   // create a string variable 'writeMe' and set it to "ROBOTC"
WriteText(myFileHandle, IOResult, writeMe);  // writes "ROBOTC" without a NULL terminator to the file handled by 'myFileHandle'